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 compilation_db tool and calling the 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')
            

% scons -Q
Building compilation database compile_commands.json
cc -o hello.o -c hello.c
cc -o hello hello.o

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')
            

% scons -Q cdb
Building compilation database compile_database.json

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"
    }
]