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 moderelease.-g: Use build modereldbg.-d: Use build modedebug.-x: Ignore anyextra_cflagsandextra_ldflagsfrom the cfg file.-X NAME: Use the extra flags of the flag setNAMEfrom theflagsetstable of the[build]section of the cfg file, instead ofextra_cflagsandextra_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).