27.2. Ninja Build Generator

Note

This is an experimental new feature. It is subject to change and/or removal without a depreciation cycle.

Loading the ninja tool into SCons will make significant changes in SCons' normal functioning.

  • SCons will no longer execute any commands directly and will only create the build.ninja and run ninja.

  • Any targets specified on the command line will be passed along to ninja

To enable this feature you'll need to use one of the following:

# On the command line --experimental=ninja

# Or in your SConstruct
SetOption('experimental', 'ninja')
    

Ninja is a small build system that tries to be fast by not making decisions. SCons can at times be slow because it makes lots of decisions to carry out its goal of "correctness". The two tools can be paired to benefit some build scenarios: by using the ninja tool, SCons can generate the build file ninja uses (basically doing the decision-making ahead of time and recording that for ninja), and can invoke ninja to perform a build. For situations where relationships are not changing, such as edit/build/debug iterations, this works fine and should provide considerable speedups for more complex builds. The implication is if there are larger changes taking place, ninja is not as appropriate - but you can always use SCons to regenerate the build file. You are NOT advised to use this for production builds.

To use the ninja tool you'll need to first install the Python ninja package, as the tool depends on being able to do an import of the package. This can be done via:

# In a virtualenv, or "python" is the native executable:
python -m pip install ninja

# Windows using Python launcher:
py -m pip install ninja

# Anaconda:
conda install -c conda-forge ninja
        

Reminder that like any non-default tool, you need to initialize it before use (e.g. env.Tool('ninja')).

It is not expected that the Ninja builder will work for all builds at this point. It is still under active development. If you find that your build doesn't work with ninja please bring this to the users mailing list or #scons-help channel on our Discord server.

Specifically if your build has many (or even any) Python function actions you may find that the ninja build will be slower as it will run ninja, which will then run SCons for each target created by a Python action. To alleviate some of these, especially those Python based actions built into SCons there is special logic to implement those actions via shell commands in the ninja build file.

When ninja runs the generated ninja build file, ninja will launch scons as a daemon and feed commands to that scons process which ninja is unable to build directly. This daemon will stay alive until explicitly killed, or it times out. The timeout is set by $NINJA_SCONS_DAEMON_KEEP_ALIVE .

The daemon will be restarted if any SConscript file(s) change or the build changes in a way that ninja determines it needs to regenerate the build.ninja file

See:

Ninja Build System
Ninja File Format Specification