buildtool(1)¶
USAGE:¶
buildtool [<mode-options>] [<misc-options>] [--]
[<cmake-build-options>] [-- <generator-options>]
buildtool --help|-h
buildtool --usage
Mode options¶
[-C|–cmake-only|-A|–all|–info] || { [-b|–build] [-i|–install] [-p|–package] [-t|–test] }
Combo options¶
[-R|–release] || [-T|–test-all]
Misc options¶
-D<CMake-definition>]+
-E|–export-compile-commands
-G<CMake-generator-string>
-I|–install-prefix <install-location>
—L <label-regex>
–LE <label-regex>
-c|–clean
—clean-logs
–cmake-debug
—cmake-trace
–deleted-header[s] <header>[,<header>]+
-f|–force-top
-g|–graphviz=<dot-file> [–gfilt <gfilt-opt>[,<gfilt-opt>]+]
[–generator <make|ninja>[:<secondary-generator>]]
-j #
-l|–log[=<log-file>]|–log-file[=<log-file>]
-q|–quiet
-s|–subdir
—tee
–test-labels|–labels|–test-groups|–groups <group>[<;|,><group>]+
-v|–verbose
Options suffixed with ‘+’ are repeatable and cumulative. If a non-repeatable option is specified multiple times, last invocation wins.
The -G and –generator options are mutually-exclusive, and may be specified at most once.
Required environment: CETPKG_BUILD CETPKG_SOURCE
Optional environment: CETPKG_INSTALL CETPKG_J
DETAILS¶
Required environment variables:
CETPKG_BUILD: The build area for the current package.
Optional environment variables:
- CETPKG_INSTALL: The default location of the private (or public) UPS
products area into which to install the package if install is requested. This is overridden by -I option, but will override existing CMAKE_INSTALL_PREFIX from CMake.
- CETPKG_J: Default parallelism for all appropriate steps, assuming
-j is not specified explicitly.
Other configuration items:
The following items are obtained from the package’s cetpkg_info.sh file, which is generated by sourcing setup_for_development:
CETPKG_SOURCE: The source area for the current package (containing the top-level CMakeLists.txt).
MODE OPTIONS¶
If any of -A (–all), C (–cmake-only) or –info are set, they override all other mode options. The cmake-only mode overrides the all option. 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).
-A –all
Execute all stages.
-C –cmake-only
Execute only the CMake stage.
-b –build
Execute the build stage from the current directory. This is default if no other mode option is specified.
-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.
- --info
If already configured (CMake has been run at least once since the last clean), give some basic information about the package, then exit.
-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.
–short-circuit –sc
Execute only the specified stages and not those that might be implied (CMake stage, build stage when test stage is specified, etc).
-t –test
Execute configured tests with ctest from the current directory. Implies –build.
COMBO MODE OPTIONS¶
-R –release
Equivalent to -t –test-labels=RELEASE.
-T –test-all
Equivalent to -t –test-labels=ALL.
MISC. 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-install-dir> –install-prefix <ups-install-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 regex. Both options are mutually exclusive with –test-labels, -T and -R, but not with each other. Specifying one of these options implies -t.
-c –clean
Remove CMake-generated files and caches and other build products.
- --clean-logs
Remove .log files in the $CETPKG_BUILD top directory.
- --cmake-debug
Add –debug-output to the CMake command line options.
- --cmake-trace
Add –trace to the CMake command line options.
–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.
- --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 below $CETPKG_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[=<opt>[,<opt>]+]
Filter the graphviz output from CMake through cmake-graphviz-filt, with the following options:
exes|no-exes
With or without executables shown (default without).
dicts|no-dicts
With or without dictionary and map libraries (default without).
extlibs|no-extlibs
With or without extlibs shown (default without).
short-libnames|no-short-libnames
Any fully-specified library pathnames are shortened to their basenames (default long).
test-tree|no-test-tree
With or without libraries and execs from the test directory hierarchy (default without).
tred|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-file>] –log-file[=<log-file>]
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-file name will be generated. The long forms should use “=” to separate the option from its 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 to $CETPKG_BUILD. Incompatible with –force-top. <subdir> will be used in preference to the current user directory, even if the latter is a subdirectory of $CETPKG_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. Since cetbuildtools v6_00_00, this is integrated with the CMake labels facility, and the test selection is done at CTest invocation time rather than CMake time as previously. 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 of ALL is substituted with all known test labels. A leading `-‘ for a label will lead to its explicit exclusion. See also -T, -R options. Mutually-exclusive with –L and –LE options.
- --usage
Short help.
-v –verbose
Extra information about the commands being executed at each step
EXAMPLES¶
Build, test, install and create a package tarball from scratch with output to a default-named log file, using parallelism:
$ buildtool -A -c -l -I <install-dir> -j16
As above, but copying output to screen:
$ 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 (eg) 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