Project

General

Profile

Buildtool script

To see the latest, type "buildtool -h"

usage: buildtool [<mode-options>] [<misc-options>] [--] [<generator-build-options>]
       buildtool --help|-h

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>]+ [-I|--install-prefix <install-location>]
              [-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 <generator>]]
              [-j #] [-l|--log[=<log-file>]|--log-file[=<log-file>]]
              [-q|--quiet] [--tee]
              [--test-groups|--groups <group>[<;|,><group>]+]
              [-v|--verbose]

Options suffixed with '+' are repeatable and cumulative.

Required environment: CETPKG_BUILD
Optional environment: CETPKG_INSTALL CETPKG_J CETPKG_QUAL

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_variable_report file, which is generated by sourcing
setup_for_development:

CETPKG_SOURCE:  The source area for the current package (containing the
                top-level CMakeLists.txt).
CETPKG_TYPE:    The build type, required by CMake.
CETPKG_QUAL:    If set, causes -Dqualifier:STRING=$CETPKG_QUAL to be added
                to the CMake arguments.

MODE OPTIONS.

If any of -A (--all), C (--cmake-only) or --info are set, they override
all other mode options. The cmake-only option overrides the all
option. If any of the other options are selected, they will be executed
in order *after* the CMake stage (which is always executed in the
CETPKG_BUILD directory).

-A
--all

  Execute all targets.

-C
--cmake-only

  Execute *only* the CMake stage.

-b
--build

  Execute the build stage from the current directory. Since this is
  default, this is only required if you specify --install or --package
  and do *not* also specify test (see below).

-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 the
  explicit build option is deactivated. However, you *may* wish to
  specify --build anyway in the case that you wish to pass arguments to
  the generator procedure for the build phase.

--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 an install
  tarball. See the notes for --install above regarding the build option.

--short-circuit
--sc

  Execute only the specified targets 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-groups=RELEASE.

-T
--test-all

  Equivalent to -t --test-groups=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.

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

-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 take place in the
  CETPKG_BUILD area (default is to build / test in current directory).

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

  Use the specified generator. Currently supported values are "make" and
  "ninja" (default make).

-h|--help

  This help (long-form).

-j #

  Specify the level of parallelism for stages for which it is
  appropriate.

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

--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-groups <group>[<;|,><group>]+
--groups <group>[<;|,><group>]+

  Specify optional test groups to configure per cet_test macro
  (CetTest.cmake). Equivalent to -DCET_TEST_GROUPS=... if multiple
  groups are delimited with semicolons they should be escaped or
  quoted to protect them from the shell. A warning shall be issued if
  this option is specified but the CMake stage is not to be executed.

-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 a particular target only (eg):

  cd art/Framework/IO/Root; buildtool -- RootOutput_source.o

To build and test only:

  buildtool -t -j16

To install and package only:

  buildtool -i -p -j16