Help/command/ctest_build.rst

   1 ctest_build
   2 -----------
   3
   4 Perform the :ref:`CTest Build Step` as a :ref:`Dashboard Client`.
   5
   6 ::
   7
   8   ctest_build([BUILD <build-dir>] [APPEND]
   9               [CONFIGURATION <config>]
  10               [PARALLEL_LEVEL <parallel>]
  11               [FLAGS <flags>]
  12               [PROJECT_NAME <project-name>]
  13               [TARGET <target-name>]
  14               [NUMBER_ERRORS <num-err-var>]
  15               [NUMBER_WARNINGS <num-warn-var>]
  16               [RETURN_VALUE <result-var>]
  17               [CAPTURE_CMAKE_ERROR <result-var>]
  18               )
  19
  20 Build the project and store results in ``Build.xml``
  21 for submission with the :command:`ctest_submit` command.
  22
  23 The :variable:`CTEST_BUILD_COMMAND` variable may be set to explicitly
  24 specify the build command line.  Otherwise the build command line is
  25 computed automatically based on the options given.
  26
  27 The options are:
  28
  29 ``BUILD <build-dir>``
  30   Specify the top-level build directory.  If not given, the
  31   :variable:`CTEST_BINARY_DIRECTORY` variable is used.
  32
  33 ``APPEND``
  34   Mark ``Build.xml`` for append to results previously submitted to a
  35   dashboard server since the last :command:`ctest_start` call.
  36   Append semantics are defined by the dashboard server in use.
  37   This does *not* cause results to be appended to a ``.xml`` file
  38   produced by a previous call to this command.
  39
  40 ``CONFIGURATION <config>``
  41   Specify the build configuration (e.g. ``Debug``).  If not
  42   specified the ``CTEST_BUILD_CONFIGURATION`` variable will be checked.
  43   Otherwise the ``-C <cfg>`` option given to the :manual:`ctest(1)`
  44   command will be used, if any.
  45
  46 ``PARALLEL_LEVEL <parallel>``
  47   .. versionadded:: 3.21
  48
  49   Specify the parallel level of the underlying build system.  If not
  50   specified, the :envvar:`CMAKE_BUILD_PARALLEL_LEVEL` environment
  51   variable will be checked.
  52
  53 ``FLAGS <flags>``
  54   Pass additional arguments to the underlying build command.
  55   If not specified the ``CTEST_BUILD_FLAGS`` variable will be checked.
  56   This can, e.g., be used to trigger a parallel build using the
  57   ``-j`` option of make. See the :module:`ProcessorCount` module
  58   for an example.
  59
  60 ``PROJECT_NAME <project-name>``
  61   Ignored since CMake 3.0.
  62
  63   .. versionchanged:: 3.14
  64     This value is no longer required.
  65
  66 ``TARGET <target-name>``
  67   Specify the name of a target to build.  If not specified the
  68   ``CTEST_BUILD_TARGET`` variable will be checked.  Otherwise the
  69   default target will be built.  This is the "all" target
  70   (called ``ALL_BUILD`` in :ref:`Visual Studio Generators`).
  71
  72 ``NUMBER_ERRORS <num-err-var>``
  73   Store the number of build errors detected in the given variable.
  74
  75 ``NUMBER_WARNINGS <num-warn-var>``
  76   Store the number of build warnings detected in the given variable.
  77
  78 ``RETURN_VALUE <result-var>``
  79   Store the return value of the native build tool in the given variable.
  80
  81 ``CAPTURE_CMAKE_ERROR <result-var>``
  82   .. versionadded:: 3.7
  83
  84   Store in the ``<result-var>`` variable -1 if there are any errors running
  85   the command and prevent ctest from returning non-zero if an error occurs.
  86
  87 ``QUIET``
  88   .. versionadded:: 3.3
  89
  90   Suppress any CTest-specific non-error output that would have been
  91   printed to the console otherwise.  The summary of warnings / errors,
  92   as well as the output from the native build tool is unaffected by
  93   this option.