buildtool(1)

Synopsis

buildtool [mode-option|combo-option ...] [misc-options]
[-- [CMake build options][-- generator options]]

buildtool --help|-h

buildtool --usage

Exclusive mode options: -A|--all -C|--cmake-only --info

Other mode options: -b|--build -i|--install -p|--package --sc|--short-circuit -t|--test

Combo mode options: -R|--release -T|--test-all

Miscellaneous options:

-c|--clean

--clean-logs

--cmake-debug

--cmake-trace

--cmake-trace-expand

-D<CMake-definition>

--deleted-header[s] <header>[, <header>] …

-E|--export-compile-commands

-f|--force-top

-G<CMake-generator-string>|--generator <make|ninja>[:<secondary-generator>]

-g <dot-file>|--graphviz=<dot-file> [--gfilt[=<gfilt-opt>[,<gfilt-opt>] …]]

-I|--install-prefix <ups-top-dir>

--iwyu[=<iwyu-prog>]

-j #

--L <label-regex>

--LE <label-regex>

-l|--log[=<log-file>]|--log-file[=<log-file>]

--no-pc|--no-preset-configure

--pc|--preset-configure <preset-name>

-q|--quiet

-s|--subdir

--tee

--test-labels|--labels|--test-groups|--groups <group>[<;|,><group>] …

-v|--verbose

-X<c|b|t|i|p> <arg>[,<arg>] …

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. UPS is a deprecated domain-specific tool, so if your package is not already reliant on UPS, you are _strongly_ encouraged not to start. Instead you should use CMake directly and/or your favorite IDE or other build manager such as GNU Make or ninja.

Note

If your package _does_ rely on UPS currently, you are encouraged to investigate migrate(1) to facilitate evolving your package and its dependencies to be buildable via more general means such as Spack, while still being buildable with and for the UPS environment.

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 ups/setup_for_development, the latter of which has already been sourced prior to invoking buildtool.

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.

--sc, --short-circuit

Execute only the specified stages and not those that might be implied.

-t, --test

Execute configured tests with ctest from the current directory. Implies --build.

Combo options

-R, --release

Equivalent to -t --test-labels=RELEASE.

-T, --test-all

Equivalent to -t --test-labels=ALL.

Miscellaneous options

-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, --cmake-trace, --cmake-trace-expand

Add the corresponding CMake debug option (–debug-output, –trace, –trace-expand, respectively) to the command-line options for the configure stage.

Deprecated since version 2.15.00: use -Xc with the corresponding native CMake option.

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

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

-E, --export-compile-commands

Equivalent to -DCMAKE_EXPORT_COMPILE_COMMANDS:BOOL=ON. Useful for (e.g.) clang-tidy.

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

-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 external library dependencies 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 executabless 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

Long-form help.

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

--iwyu[=<iwyu-prog>]

New in version 3.19.00.

Specify the location of the include-what-you-use program (iwyu).

-j <#>

Specify the level of parallelism for stages for which it is appropriate (overrides CETPKG_J if specified).

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

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

--no-pc, --no-preset-configure

New in version 3.08.00.

Do not use a predefined CMake configure preset.

See also

--pc

--pc <preset-name>, --preset-configure <preset-name>

New in version 3.06.00.

Use the named CMake configure preset instead of CMake definitions genereated from ups/product_deps. Absent this option or --no-pc, the preset for_UPS will be used if defined in CETPKG_SOURCE/CMakePresets.json.

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

-X<c|b|t|i|p> <arg>[,<arg>]+[,--,<non-option-arg>[,<non-option-arg>]+]

New in version 2.15.00.

EXtra arguments to be passed to the Configure, build, test, install, or package 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.

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:

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 removed by defining CETPKG_INSTALL; the explicit parallelism may be similarly avoided 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 sourcing ups/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 over CMAKE_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 vs Ninja).