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