buildtool(1)¶
Synopsis¶
buildtool [mode-option…|combo-option…]
[misc-options]
[--
[CMake build options]
[--
generator options]]
buildtool --usage
- Exclusive mode options:
- Other mode options:
-b
|--build
-i
|--install
-p
|--package
--sc
|--short-circuit
-t
|--test
- Combo mode options:
- Miscellaneous mode options:
-j
#
Description¶
Despite the bewildering array of available options, buildtool is intended to simplify the task of building and debugging code, producing packages for use with UPS.
The process of producing a software package from its source consists of multiple steps:
Configuration
Build
Test
Installation
Packaging
buildtool assumes one is using CMake and the macros and functions defined within cetmodules inside a UPS environment to produce a UPS package. This in turn implies the existence of files ups/product.table
ups/product_deps
, and file:ups/setup_for_development, the latter of which has already been sourced prior to invoking buildtool.
Note
UPS is deprecated, in addition to being practically unknown outside certain areas of experimental particle physics. If your package is not already reliant on UPS, you are encouraged not to start: the macros and functions provided by cetmodules to aid building and packaging your code do not need UPS, or any of its accoutrements.
If your package does rely on UPS, you are encouraged to investigate migrate to facilitate evolving your package to no longer rely on UPS,becoming buildable via more general means such as Spack, while still being buildable with and for the UPS environment.
Options¶
Modes¶
If any of --info
, --cmake-only
, or --all
are set, they override all other mode options.
If any of the other options are selected, they will be executed in their natural order after the CMake stage (which is always executed
in the CETPKG_BUILD
directory) unless --short-circuit
is used.
Exclusive mode options¶
-
-A
,
--all
¶
Execute all stages.
-
-C
,
--cmake-only
¶
Execute only the CMake stage.
-
--info
¶
If already configured (CMake has been run at least once since the last clean), give some basic information about the package, then exit.
Other mode options¶
-
-b
,
--build
¶
Execute the build stage from the current directory. This is default if no other mode option is specified.
Note
implies execution of the configuration step unless combined with :option:
--short-circuit
.
-
-i
,
--install
¶
Execute the install stage from
CETPKG_BUILD
. CMake’s generated build procedure will ensure that all build targets are up to date, so an accompanying explicit--build
option is unnecessary.
-
-p
,
--package
¶
Execute the package stage from CETPKG_BUILD to create a binary installation archive. As for
--install
, CMake’s generated build procedure will ensure that all build targets are up to date so an accompanying explicit--build
option is unnecessary. Note that--package
does not imply--install
: the two operations are independent.
Combo options¶
-
-R
,
--release
¶
Equivalent to
-t
--test-labels=RELEASE
.
-
-T
,
--test-all
¶
Equivalent to
-t
--test-labels=ALL
.
Miscellaneous options¶
-
-D<CMake-definition>
¶
Pass definitions to the invocation of the CMake stage. A warning shall be issued if this option is specified but the CMake stage is not to be executed.
-
-E
,
--export-compile-commands
¶
Equivalent to
-DCMAKE_EXPORT_COMPILE_COMMANDS:BOOL=ON
. Useful for (e.g.) clang-tidy.
-
-G<CMake-generator-string>
¶
Pass the specified CMake generator string through to CMake. Note that, at this time, only the “Unix Makefiles” and “Ninja” generators are supported by buildtool. Any secondary generator specification is passed through unexamined.
-
-I
<ups-top-dir>
,
--install-prefix
<ups-top-dir>
¶ Specify the location of the private (or public) UPS products area into which to install the package if install is requested. Overrides the
CETPKG_INSTALL
environment variable and anything already known to CMake.
-
--L
<label-regex>
,
--LE
<label-regex>
¶ Per ctest, include (
--L
) or exclude (--LE
) labels by CMake regular expression. Both options are mutually exclusive with--test-labels
,-T
, and-R
, but not with each other. Specifying one of these options implies-t
.
-
-X<c|b|t|i|p>
<arg>[,<arg>]+[,--,<non-option-arg>[,<non-option-arg>]+]
¶ E
X
tra arguments to be passed to theC
onfigure,b
uild,t
est,i
nstall, orp
ackage stages.<arg>
s will be added at the end of option arguments, while<non-option-arg>
s will be added at the end of non-option arguments.
-
-c
,
--clean
¶
Remove CMake-generated files and caches and other build products.
-
--clean-logs
¶
Remove
.log
files in the :envvar:CETPKG_BUILD
top directory.
-
--cmake-debug
,
--cmake-trace
,
--cmake-trace-expand
¶
Add the corresponding CMake debug option (
s&cmake-&&
to the command-line options for the configure stage.See also
-Xc
.
-
--deleted-header[s]
<header>[,<header>]+
¶ Indicate that named headers have been removed from the source, to allow removal and regeneration of dependency files containing references to same.
-
-f
,
--force-top
¶
Force build and test stages (if applicable) to be executed from the top level
CETPKG_BUILD
area. Otherwise these stages will execute within the context of the user’s current directory at invocation if it is belowCETPKG_BUILD
.--force-top
is incompatible with--subdir
. In any event, any relative or unqualified log file will be output relative to the user’s current directory at the time buildtool was invoked.
-
-g
<dot-file>
,
--graphviz
=<dot-file>
¶ Ask CMake to produce a code dependency graph in graphviz (.dot) format.
Note that CMake can only tell you about the dependencies about which it knows. Libraries must have their dependencies resolved at library production time (NO_UNDEFINED) in order for the information to be complete.
-
--gfilt
[=<gfilt-opt>[,<gfilt-opt>]...]
¶ Filter the graphviz output from CMake through :program:cmake-graphviz-filt, with the following options:
-
[no-]exes
With or without executables shown (default without).
-
[no-]dicts
With or without dictionary and map libraries (default without).
-
[no-]extlibs
With or without extlibs shown (default without).
-
[no-]short-libnames
Any fully-specified library pathnames are shortened to their basenames (default long).
-
[no-]test-tree
With or without libraries and execs from the test directory hierarchy (default without).
-
[no-]tred
With or without transitive dependency reduction (default with).
Multiple options should be comma-separated. Note that all of these options may be specified in
~/.cgfrc
for the same effect (command-line overrides).-
-
--generator
<generator>[:<secondary-generator>]
¶ User-friendly way to specify the generator. Currently supported values are “make” and “ninja” (default make). If <secondary-generator> (e.g. CodeBlocks) is specified it will be passed through as-is.
-
-h
,
--help
¶
This help (long-form).
-
-j
<#>
¶ Specify the level of parallelism for stages for which it is appropriate (overrides
CETPKG_J
if specified).
-
-l
,
--log
[=<log-dir-or-filepath>]
,
--log-file
[=<log-dir-or-filepath>]
¶ All build output is redirected to the specified log-file, or one with a default name if no other is specified. Unless
--quiet
is also specified, stage information will still be printed to the screen—though see--tee
below. Note that the short variant does not accept an argument: a log filename will be generated. The long forms should use=
to separate the option from their argument.
-
-q
,
--quiet
¶
Suppress all non-error output to the screen (but see
--tee
below). A log file will still be written as normal if so specified.
-
-s
<subdir>
,
--subdir
<subdir>
¶ Execute build and install stages from the context of
<subdir>
, which will be interpreted relative toCETPKG_BUILD
. Incompatible with--force-top
.<subdir>
will be used in preference to the current user directory, even if the latter is a subdirectory ofCETPKG_BUILD
.
-
--tee
¶
Write to a log file (either as specified by
--log
or the default), but copy output to the screen also:--quiet
is overridden by this option.
-
--test-labels
=<group>[<;|,><group>]...
,
--labels
=<group>[<;|,><group>]...
,
--test-groups
=<group>[<;|,><group>]...
,
--groups
=<group>[<;|,><group>]+
¶ Specify optional CMake test labels to execute. Test selection is done at ctest invocation time. If this option is activated but tests are not to be run, a warning shall be issued. If no labels are selected, then
DEFAULT
is selected. A value ofALL
is substituted with all known test labels. A leading-
for a label will lead to its explicit exclusion. See also--test-all
, and--release
. Mutually-exclusive with--L
and--LE
.
-
--usage
¶
Short help.
-
-v
,
--verbose
¶
Extra information about the commands being executed at each step.
-
--short-circuit
,
--sc
¶
Execute only the specified stages and not those that might be implied.
CMake build options¶
Any options or arguments specified after a single instance of --
—or between two instances of same—will be passed to all stages invoked with cmake --build
: the build, install and package stages.
Generator options¶
Any options or arguments specified after a second instance of --
will be passed to the configured generator (e.g. “UNIX Makefiles” or “Ninja”) for the build stage only.
Examples¶
Build, test, install and create a package tarball from scratch with output to a default-named log file, using parallelism:
:program:`buildtool`\ -A -c -l -I <install-dir> -j16
As above, but copying output to screen:
:program:`buildtool`\ -A -c -l --tee -I <install-dir> -j16
The need for the -I
option may be obviated by defining CETPKG_INSTALL
;
the need for the explicit parallelism may be similarly voided by
defining (e.g.) CETPKG_J=16
.
To build only a particular target within a subdirectory:
buildtool --subdir art/Framework/IO/Root -- RootOutput_source.o
To build and test only:
buildtool -t -j16
To install and package only:
buildtool -i -p -j16
Environment¶
Required¶
-
CETPKG_BUILD
¶ The path to the build area. Set by sourcing
ups/setup_for_development
.
-
CETPKG_SOURCE
¶ The path to the source (i.e. the top-level
CMakeLists.txt
). Set by sourcingups/setup_for_development
.
Optional¶
-
CETPKG_INSTALL
¶ The installation area (must be a properly-initialized unified-UPS top level directory for the installed products to be usable by UPS). May be overridden by
-I
, but takes precedence overCMAKE_INSTALL_PREFIX
.
-
CETPKG_J
¶ The default level of parallelism for all appropriate steps; may be overridden by ::option::-j. If not specified, the default level of parallelism is controlled by the generator (e.g.
UNIX Makefiles
vsNinja
).