Skip to main content

compile_commands.json generation for SCons build system

Project description

Build Status PyPI version

SCons Compilation DB support

scons-compiledb adds a support for generating JSON formatted compilation database defined by Clang.

Features:

  • Multiple construction environments support.
  • compile_commands.json merge across SCons invocations
  • Customisation for DB entry generation.
  • Build with command line option, --compiledb
  • Simpler installation with PyPI

At the moment, SCons mainline does not have compilation DB generation functionality and it is likely to have it in the near feature. However, this module can still provide some advantages such as supporting old version of SCons and other useful features.

The module was tested with Python 2.x/3.x along with SCons 2.x/3.x.

Installation

Install and update using pip

pip install scons-compiledb

Usage

Enable and use CompileDb builder

import scons_compiledb

env = DefaultEnvironment()  # Or with any other way
scons_compiledb.enable(env)
# 
# ... use env normally ...
#
env.CompileDb()

enable(env) adds a new builder, CompileDb to the specified environment, env. In order to build the compile_commands.json file, CompileDb() should be called. It can also specify the DB file name as an optional argument.

Note that enable(env) should be called before the env is used to compile any targets.

Simpler usage with command line option --compiledb

Instead of enable(), enable_with_cmdline() can be used to add a command line option --compiledb, which, when specified, generates 'compile_commands.json' as default target.

import scons_compiledb

env = DefaultEnvironment()  # Or with any other way
scons_compiledb.enable_with_cmdline(env)

#
# ... Use env normnally ...
#

With the above build script, compile_commands.json file will be generated when SCons is invoked with --compiledb command line option as follows:

$ scons --compiledb=

Note that the command line option requires an option string as argument and the trailing = means empty. The comma-separated option string can specify the bool type config options(see below) as follows:

$ scons --compiledb=reset,multi

In order to build DB while building other target, compiledb can be used as an alias as follows:

$ scons --compiledb= compiledb other_targets

Customisation

While enabling, a Config object can be passed. For example:

config = scons_compiledb.Config(db='foo.json')
scons_compiledb.enable(env, config)

Parameter Value Default
db filename of compilation DB. '#/compile_commands.json'
entry_func function to determine the entry dict for each source file. entry_func_default
cxx_suffixes Suffixes for C++ files. ('.cpp', '.cc')
ccc_suffixes Suffixes for C files. ('.c,)
reset Whether to remove existing entries False
multi Whether to allow multiple entries with the same 'file'. False

entry_func

entry_func is the main logic to convert source file node in SCons to a dict containing directory, source and command as keys. There are predefined entry functions as follows:

  • entry_func_default

This is default and it should work for the most of cases.

  • entry_func_simple

Use CPPPATH and CPPDEFINES only and clang/clang++ as compiler tool name. This will be useful to use clangd with compilers, which use command line arguments clangd cannot understand.

entry_func can be easily customised. Please refer to the source code of the predefined functions

reset

As default, compile_commands.json file is merged across the multiple invocations of SCons so that one DB file can be used. This is usually good thing. However, if it is not desirable for any reasons, reset config can be used to remove any existing entries before generating new ones.

multi

As default, compile_commands.json file keeps only one entry with the same file as the key. However, some tools can handle multiple entries with the same key. If multi is set, multiple entries are stored as long as they generate the different target(output) files.

Details

enable(env) modifies the builders related to the compilations, such as StaticObject, to add a additional Scanner, which make sure that the compilation commands are captured. enable(env) also adds a new builder CompileDb, which generates compile_commands.json from the captured commands.

scons_compiledb maintains an internal dot file .compile_commands.json as default, to merge compile commands across the multiple SCons invocations. The final file, compile_commands.json is touched only when the internal dot file is changed.

When the compile commands are merged, it is based on source/output file name. It means that the entry with the same pair will be overwritten.

enabled(env) can be called to check whether it is enabled before or not.

Examples

Please check SConscript files in test folder

Credits

The core functionality of scons-compiledb is based on MongoDB source code.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

scons-compiledb-0.7.2.tar.gz (7.0 kB view details)

Uploaded Source

Built Distributions

scons_compiledb-0.7.2-py3-none-any.whl (11.6 kB view details)

Uploaded Python 3

scons_compiledb-0.7.2-py2-none-any.whl (11.6 kB view details)

Uploaded Python 2

File details

Details for the file scons-compiledb-0.7.2.tar.gz.

File metadata

  • Download URL: scons-compiledb-0.7.2.tar.gz
  • Upload date:
  • Size: 7.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/46.1.3 requests-toolbelt/0.9.1 tqdm/4.45.0 CPython/3.7.1

File hashes

Hashes for scons-compiledb-0.7.2.tar.gz
Algorithm Hash digest
SHA256 dfefda07b8463ee295dc7864124d22da3cac29750b375e111d44f894dc5093d3
MD5 5e64d0f3a01f33805c5d59b64a32ea54
BLAKE2b-256 2a9b584b000c03b18ae257fa5459b553bb9bd1d9633aac57dcc91ab4fde33ced

See more details on using hashes here.

File details

Details for the file scons_compiledb-0.7.2-py3-none-any.whl.

File metadata

  • Download URL: scons_compiledb-0.7.2-py3-none-any.whl
  • Upload date:
  • Size: 11.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/46.1.3 requests-toolbelt/0.9.1 tqdm/4.45.0 CPython/3.7.1

File hashes

Hashes for scons_compiledb-0.7.2-py3-none-any.whl
Algorithm Hash digest
SHA256 062313e8f3e6a49b9197c22dd6eee79755e262df0c7faeb7174579d5cbf43d37
MD5 7e8a74094806d442b2041f1d8c82e92f
BLAKE2b-256 c8a970bd73905ee513ef0764b95311ff2273fc429f77c2e85f9b3ecb5e2ae629

See more details on using hashes here.

File details

Details for the file scons_compiledb-0.7.2-py2-none-any.whl.

File metadata

  • Download URL: scons_compiledb-0.7.2-py2-none-any.whl
  • Upload date:
  • Size: 11.6 kB
  • Tags: Python 2
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.15.0 pkginfo/1.5.0.1 requests/2.23.0 setuptools/44.1.0 requests-toolbelt/0.9.1 tqdm/4.45.0 CPython/2.7.15

File hashes

Hashes for scons_compiledb-0.7.2-py2-none-any.whl
Algorithm Hash digest
SHA256 c910e25de987e30335fe8e2f3f73f7f327931c6f4eb7ae1e457a92c7174902c2
MD5 790993c947f65ffe3b7502db6ca5c113
BLAKE2b-256 ddcbc0e7f6a84f2a28241e770a2f4c084832726dcff0c8f98cbf1f15bc4e4434

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page