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.

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.

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

Query options

--version

Show simplebuild version.

-s, --summary

Print a summary of the configuration.

--pkginfo

Print information about package PKG.

Default: ''

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

--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 <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 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 <program> [args]

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