%scons; %builders-mod; %functions-mod; %tools-mod; %variables-mod; ]> Sometimes a project needs to interact with other projects in various ways. For example, many open source projects make use of components from other open source projects, and want to use those in their released form, not recode their builds into &SCons;. As another example, sometimes the flexibility and power of &SCons; is useful for managing the overall project, but developers might like faster incremental builds when making small changes by using a different tool. This chapter shows some techniques for interacting with other projects and tools effectively from within &SCons;.

Tooling to perform analysis and modification of source code often needs to know not only the source code itself, but also how it will be compiled, as the compilation line affects the behavior of macros, includes, etc. &SCons; has a record of this information once it has run, in the form of Actions associated with the sources, and can emit this information so tools can use it. The Clang project has defined a JSON Compilation Database. This database is in common use as input into Clang tools and many IDEs and editors as well. See JSON Compilation Database Format Specification for complete information. &SCons; can emit a compilation database in this format by enabling the &t-link-compilation_db; tool and calling the &b-link-CompilationDatabase; builder (available since &scons; 4.0). The compilation database can be populated with source and output files either with paths relative to the top of the build, or using absolute paths. This is controlled by COMPILATIONDB_USE_ABSPATH=(True|False) which defaults to False. The entries in this file can be filtered by using COMPILATIONDB_PATH_FILTER='pattern' where the filter pattern is a string following the &Python; fnmatch syntax. This filtering can be used for outputting different build variants to different compilation database files. The following example illustrates generating a compilation database containing absolute paths: env = Environment(COMPILATIONDB_USE_ABSPATH=True) env.Tool('compilation_db') env.CompilationDatabase() env.Program('hello.c') int main(int argc, char* argv[]) { return 0; } scons -Q compile_commands.json contains: [ { "command": "gcc -o hello.o -c hello.c", "directory": "/home/user/sandbox", "file": "/home/user/sandbox/hello.c", "output": "/home/user/sandbox/hello.o" } ] Notice that the generated database contains only an entry for the hello.c/hello.o pairing, and nothing for the generation of the final executable hello - the transformation of hello.o to hello does not have any information that affects interpretation of the source code, so it is not interesting to the compilation database. Although it can be a little surprising at first glance, a compilation database target is, like any other target, subject to &scons; target selection rules. This means if you set a default target (that does not include the compilation database), or use command-line targets, it might not be selected for building. This can actually be an advantage, since you don't necessarily want to regenerate the compilation database every build. The following example shows selecting relative paths (the default) for output and source, and also giving a non-default name to the database. In order to be able to generate the database separately from building, an alias is set referring to the database, which can then be used as a target - here we are only building the compilation database target, not the code. env = Environment() env.Tool('compilation_db') cdb = env.CompilationDatabase('compile_database.json') Alias('cdb', cdb) env.Program('test_main.c') #include "test_main.h" int main(int argc, char* argv[]) { return 0; } /* dummy include file */ scons -Q cdb compile_database.json contains: [ { "command": "gcc -o test_main.o -c test_main.c", "directory": "/home/user/sandbox", "file": "test_main.c", "output": "test_main.o" } ] The following (incomplete) example shows using filtering to separate build variants. In the case of using variants, you want different compilation databases for each, since the build parameters differ, so the code analysis needs to see the correct build lines for the 32-bit build and 64-bit build hinted at here. For simplicity of presentation, the example omits the setup details of the variant directories: env = Environment() env.Tool("compilation_db") env1 = env.Clone() env1["COMPILATIONDB_PATH_FILTER"] = "build/linux32/*" env1.CompilationDatabase("compile_commands-linux32.json") env2 = env.Clone() env2["COMPILATIONDB_PATH_FILTER"] = "build/linux64/*" env2.CompilationDatabase('compile_commands-linux64.json') compile_commands-linux32.json contains: [ { "command": "gcc -o hello.o -c hello.c", "directory": "/home/mats/github/scons/exp/compdb", "file": "hello.c", "output": "hello.o" } ] compile_commands-linux64.json contains: [ { "command": "gcc -m64 -o build/linux64/test_main.o -c test_main.c", "directory": "/home/user/sandbox", "file": "test_main.c", "output": "build/linux64/test_main.o" } ]

This is an experimental new feature. It is subject to change and/or removal without a depreciation cycle. Loading the &t-link-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 &t-link-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 &t-link-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 &b-link-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 &cv-link-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