Command reference#

Invocation of the sb command is central to the usage of simplebuild. Additionally two other commands, sbenv and sbrun, are provided for convenience. All of these commands have builtin documentation accessible from the command itself (e.g. sb --help or sb --h). For completeness, the documentation is repeated in the following sections.

Build variants#

The build mode (release, reldbg, or debug) and any extra compilation or link flags are normally taken from the [build] section of the simplebuild cfg file. The combination of these is referred to as the build variant. All of the commands sb, sbrun, and sbenv support the following flags for selecting a different build variant:

  • -r: Use build mode release.

  • -g: Use build mode reldbg.

  • -d: Use build mode debug.

  • -x: Ignore any extra_cflags and extra_ldflags from the cfg file.

  • -X NAME: Use the extra flags of the flag set NAME from the flagsets table of the [build] section of the cfg file, instead of extra_cflags and extra_ldflags.

At most one of -r, -g, and -d can be used, but they can be combined with -x or -X NAME, e.g. sb -dx, sb -d -x, sb -dX fma, or sb -d -X fma. The -x and -X flags can not be used together. For sbrun and sbenv, the flags must be placed before the command to run, since all arguments after it are passed on to that command. For instance, in sbrun -d mycmd -x the -d selects the debug build variant, while -x is passed on to mycmd.

Each build variant uses its own build and installation directories in the cache directory, so switching between them (e.g. between sb and sb -d) does not throw away any previous build output. To limit disk usage, at most max_cachedirs (default 5) build variants are kept in the cache directory, and the least recently used ones are automatically removed when needed. The sb -c command removes the build output of all build variants, while for instance sb -c debug only removes that of the variants with the build mode debug, and sb -c ubsan that of the variants with the extra flags of the flag set ubsan. Use sb -s to see which build variants are in the cache directory (see below).

Note that the outcome of any of these commands only depends on the code, the simplebuild cfg file, and the command line arguments. In particular, it never depends on which build variant was used in a previous command. So if you for instance build with sb -d, you must also run your commands with sbenv -d mycmd or sbrun -d mycmd to use the resulting debug build. Likewise, eval "$(sb -d --env-setup)" sets up the environment for the debug build. If you use the sb shell function (see here), it sets up the environment after each build, for the build variant used in that build.

Inspecting the configuration#

The sb -s command (or sb --summary) prints a summary of the configuration of the selected build variant: the cfg files and bundles used, the package search path, the number of packages, the build mode and extra flags (and where they come from), the cache directories, and the external dependencies. Nothing is built, and the cache directories are not modified. As for a build, the build variant flags can be used (e.g. sb -s -d). The output consists of KEY : VALUE lines, with the values of lists continuing on the following lines:

main_cfg_file          : /path/to/myproject/simplebuild.cfg
bundles                : myproject
                         dgcode
                         core
...
build.mode             : debug
build.mode_from        : -d
build.extra_cflags     : -mfma
...
extdeps.present        : Geant4 11.4.3
                         NCrystal 4.4.6
extdeps.missing        : ROOT
extdeps.unused         : HDF5

The text output ends with an overview of the cache directories of all build variants currently in the cache directory, with their sizes on disk. Each variant is shown with its build mode and extra flags, preceded by the name of the flag set if it matches one that can be selected with -X NAME.

The external dependencies are only known after the environment has been inspected (which happens at the first build of the build variant). Use sb -s -e to inspect it if needed, without building anything. External dependencies which are not used by any packages are not inspected, and are listed as extdeps.unused.

All the information is also available in JSON format with sb -s=json (or sb -s json), and single values can be printed with sb --showcfg KEY, where KEY is one of the keys shown by sb -s, or a key path in the JSON output, for instance:

sb --showcfg build.mode
sb --showcfg -d variant.installdir
sb --showcfg extdeps.Geant4.version

Values which are lists are printed one per line, and tables as KEY : VALUE lines.

The same information is installed by each build, and is available from Python code in the packages via the simplebuild.cfg module, as the dictionary simplebuild.cfg.info (the same as the output of sb -s=json for the build variant). For convenience, the module also provides some of the values directly: build_mode, extra_cflags, extra_ldflags, flagset, bundles, main_cfg_file, and extdeps. For instance:

import simplebuild.cfg
if simplebuild.cfg.build_mode == 'debug':
    print('This is a debug build')
geant4 = simplebuild.cfg.extdeps['Geant4']
if geant4['present']:
    print('Geant4 version:', geant4['version'])

The module also provides information about all packages in simplebuild.cfg.pkgs (including the name of the bundle providing each package), and the installation directories in simplebuild.cfg.dirs.

The sb command#

Invokes the simplebuild configuration and build system. Usually this means locating a simplebuild.cfg file in the current (or a parent directory), and using the corresponding configuration. The default action is to configure and build those packages, but as described below, certain options might change this in order to instead display information, launch unit tests, initialise new bundle directories, etc.

usage: sb [-h|--help] [options]

Controlling the build#

The build will be carried out and installed in a cache directory (use -s to see which). The following options affects the build process.

-v, --verbose

Enable more verbosity.

-q, --quiet

Less verbose. Silence even some warnings. Only errors are printed (on stderr, while all output including errors otherwise goes to stdout).

-j, --jobs

Use up to N parallel processes (default: auto).

Default: 0

-e, --examine

Force (re)examination of environment.

-i, --insist

Insist on reconf/rebuild/reinstall from scratch.

Selecting the build variant#

By default, the build mode and any extra flags are taken from the [build] section of the simplebuild cfg file. The following flags can override this. Each build variant uses its own cache directories, so switching between them does not require a full rebuild (at most build.max_cachedirs are kept, removing the least recently used ones). The same flags are also supported by sbrun and sbenv.

-d

Use build mode ‘debug’ (overriding build.mode).

-r

Use build mode ‘release’ (overriding build.mode).

-g

Use build mode ‘reldbg’ (overriding build.mode).

-x

Ignore build.extra_cflags and build.extra_ldflags.

-X

Use the extra flags of the flag set NAME in build.flagsets (instead of build.extra_cflags and build.extra_ldflags).

Query options#

--version

Show simplebuild version.

-s, --summary

Print a summary of the configuration of the selected build variant, without building anything. FORMAT can be “text” (default) or “json” (e.g. -s=json). Add -e to also inspect the external dependencies if not already done.

--showcfg

Print the value of KEY in the configuration of the selected build variant (e.g. build.mode or extdeps.Geant4.version). The keys are those shown by -s, or any key path in the output of -s=json.

--pkginfo

Print information about package PKG.

Default: ''

--buildtimes

Print the N (default 20) slowest compilation and linking steps, as recorded in the most recent build of each file (without building anything).

--includecosts

Print rough estimates of the compilation cost of the N (default 20) most costly files (based on build timings and include statements, requires numpy).

--incinfo

Show inclusion relationships for CFILE in C++/C format. Specify multiple files with comma- separation and wildcards (“*”).

Default: ''

--pkggraph

Create graph of package dependencies.

--activegraph

Create graph for enabled packages only.

--grep

Search the files in packages for lines containing PATTERN. In PATTERN, ‘*’ matches any characters and ‘?’ any single character (or use a regular expression after the prefix ‘RE::’). Patterns without upper case letters ignore case, other patterns are case sensitive. For patterns starting with a dash, use the form –grep=PATTERN (e.g. –grep=–force).

Default: ''

--grepi

Like –grep but always ignore case.

Default: ''

--grepc

Like –grep but show only count per package.

Default: ''

--grepci

Like –grepc but always ignore case.

Default: ''

--find

Search for files and directories in packages with paths matching PATTERN (with the same syntax as for –grep).

--findi

Like –find but always ignore case.

New bundle initialisation options#

--init

New bundle initialisation mode (“sb –init”) is used to initialise a new simplebuild bundle in the current directory by creating a simplebuild.cfg file. Additional arguments can be used to specify bundles which the new bundle should depend on, or they can be a special keyword (DEBUG|RELDBG|COMPACT|…). In any case, it might be most convenient to edit the simplebuild.cfg file afterwards to fine-tune the desired settings.

Examples of sb –init usage:

$> sb –init core_val

Set up bundle which depends on the core_val bundle.

$> sb –init RELEASE

Set up bundle with default build options for compilation of binaries (build.mode=’release’). This is the default behaviour.

$> sb –init DEBUG

Set up bundle with build options for producing debug symbols (build.mode=’debug’). Also reduces compiler optimisation levels and enables additional safe checks in code.

$> sb –init RELDBG

Set up bundle with build options for producing debug symbols but otherwise keep all compiler optimisations (build.mode=’reldbg’).

$> sb –init COMPACT

The resulting simplebuild.cfg file will have all comments and empty lines stripped.

$> sb –init core_val dgcode COMPACT DEBUG

Set up bundle with dependency on core_val and dgcode bundles, with the build option for producing debug symbols, and a compact simplebuild.cfg file.

$> sb –init dgcode CACHEDIR::/some/where

Set up bundle with a dependency on the dgcode bundle, and the build.cachedir option set to the directory “/some/where”.

$> sb –init dgcode PKGFILTER::SomeFilter

Set up bundle with a dependency on the dgcode bundle, and “SomeFilter” appended to the build.pkg_filter option array.

Unit testing options#

-t, --tests

Run unit tests after the build.

--testreport

Print report of the test results from the last run of tests (without building or running tests), or customise the report when used with -t. Optional SPEC is a comma separated list of “relevance” (the default sort order, with failed and slow tests at the bottom of printed reports, and running and failed tests at the top of interactive ones), “time” (slowest first), or “name” (sort order), “failed” (only show failed tests), and “interactive” (browse results, inspect output and reference logs, and rerun tests).

--reflogupdate

Interactively review differences between the output of tests and their reference logs from the last run of tests (or the run triggered by -t), and update the reference logs. Use –testfilter to select tests.

--testorder

Possible choices: slowest, fastest

Order in which tests are started, based on their timings in previous runs: “slowest” first (the default, for the shortest total time), or “fastest” first (to get results quickly).

Default: 'slowest'

--testtime

Only run the tests expected to complete within approximately SECONDS (based on timings in previous runs), by skipping the slowest tests. Tests without previous timings are always run.

--failearly

Stop running tests as soon as one fails (tests which did not complete are reported as aborted).

--testexcerpts

Print N first+last lines of failed test log files.

Default: 0

--testfilter

Only run tests with names matching at least one of the provided patterns (use wildcards, comma separation, and “!” prefix to negate). An entry “COVERAGE” will enable coverage testing of python tests

Default: ''

Other options#

-c, --clean

Remove the cache directories of all build variants and exit. With NAME, only remove those of the variants with the build mode NAME or the flag set NAME (e.g. -c debug or -c ubsan).

--replace

Global search and replace in packages via pattern like ‘/OLDCONT/NEWCONT/’ (use with care!).

--requirepkg

Fail unless all listed packages are enabled.

--exportcmds

Export build commands for static analysis.

--removelock

Force removal of lockfile.

--env-setup

Emit shell code needed to modify environment variables to use build packages, then exit.

--env-unsetup

Emit shell code undoing the effect of any previous –env-setup usage, then exit.

The sbenv command#

The sbenv command can be used to prefix any other command, causing that command to run within the simplebuild environment without needing that environment to be activated for the current shell session. This should not be needed if you have installed simplebuild via the simple-build-system conda package as recommended.

Thus running sbenv mycmd arg1 arg2 is similar to running eval "$(sb --env--setup)" && mycmd arg1 arg2 in a sub-shell.

$> sbenv --help
usage: sbenv [-h] [-d|-r|-g] [-x|-X NAME] <program> [args]

Runs <program> within the simplebuild runtime environment. Note that if you wish
to make sure the codebase has been built first (with simplebuild) you should use
sbrun rather than sbenv.

The flags -d, -r, -g, -x, and -X NAME can be used to select the build variant,
exactly as for the sb command (see "sb --help"). They must be placed before <program>,
since all arguments after it are passed on to <program>.

options:
  -h, --help  show this help message and exit
  -d          Use build mode 'debug' (overriding build.mode).
  -r          Use build mode 'release' (overriding build.mode).
  -g          Use build mode 'reldbg' (overriding build.mode).
  -x          Ignore build.extra_cflags and build.extra_ldflags.
  -X NAME     Use the extra flags of the flag set NAME in build.flagsets
              (instead of build.extra_cflags and build.extra_ldflags).

The sbrun command#

The sbrun command can be used to prefix any other command, causing both a build and (if successful) the command to be invoked. This is convenient when one is repeatedly running the same command while editing C or C++ code that needs to be recompiled each time.

Thus running sbrun mycmd arg1 arg2 is similar to running sb && sbenv mycmd arg1 arg2.

$> sbrun --help
usage: sbrun [-h] [-d|-r|-g] [-x|-X NAME] <program> [args]

Runs the simplebuild 'sb' command (quietly) and if it finishes successfully,
then proceeds to launch <program> within the simplebuild runtime environment.

The flags -d, -r, -g, -x, and -X NAME can be used to select the build variant,
exactly as for the sb command (see "sb --help"). They must be placed before <program>,
since all arguments after it are passed on to <program>.

options:
  -h, --help  show this help message and exit
  -d          Use build mode 'debug' (overriding build.mode).
  -r          Use build mode 'release' (overriding build.mode).
  -g          Use build mode 'reldbg' (overriding build.mode).
  -x          Ignore build.extra_cflags and build.extra_ldflags.
  -X NAME     Use the extra flags of the flag set NAME in build.flagsets
              (instead of build.extra_cflags and build.extra_ldflags).