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.

At most one of -r, -g, and -d can be used, but they can be combined with -x, e.g. sb -dx or sb -d -x. 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.

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.

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.

Query options

--version

Show simplebuild version.

-s, --summary

Print a summary of the configuration.

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

Grep files in packages for PATTERN.

Default: ''

--grepc

Like –grep but show only count per package.

Default: ''

--find

Search for file and path names matching PATTERN.

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.

--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: Completely remove cache directories and exit.
--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] <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, and -x 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.

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] <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, and -x 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.

Command reference

Build variants

The sb command

Controlling the build

Selecting the build variant

Query options

New bundle initialisation options

Unit testing options

Other options

The sbenv command

The sbrun command

The `sb` command

The `sbenv` command

The `sbrun` command