Help/command/build_command.rst

   1 build_command
   2 -------------
   3
   4 Get a command line to build the current project.
   5 This is mainly intended for internal use by the :module:`CTest` module.
   6
   7 .. code-block:: cmake
   8
   9   build_command(<variable>
  10                 [CONFIGURATION <config>]
  11                 [PARALLEL_LEVEL <parallel>]
  12                 [TARGET <target>]
  13                 [PROJECT_NAME <projname>] # legacy, causes warning
  14                )
  15
  16 Sets the given ``<variable>`` to a command-line string of the form::
  17
  18  <cmake> --build . [--config <config>] [--parallel <parallel>] [--target <target>...] [-- -i]
  19
  20 where ``<cmake>`` is the location of the :manual:`cmake(1)` command-line
  21 tool, and ``<config>``, ``<parallel>`` and ``<target>`` are the values
  22 provided to the ``CONFIGURATION``, ``PARALLEL_LEVEL`` and ``TARGET``
  23 options, if any.  The trailing ``-- -i`` option is added for
  24 :ref:`Makefile Generators` if policy :policy:`CMP0061` is not set to
  25 ``NEW``.
  26
  27 When invoked, this :option:`cmake --build` command line will launch the
  28 underlying build system tool.
  29
  30 .. versionadded:: 3.21
  31   The ``PARALLEL_LEVEL`` argument can be used to set the
  32   :option:`--parallel <cmake--build --parallel>` flag.
  33
  34 .. code-block:: cmake
  35
  36   build_command(<cachevariable> <makecommand>)
  37
  38 This second signature is deprecated, but still available for backwards
  39 compatibility.  Use the first signature instead.
  40
  41 It sets the given ``<cachevariable>`` to a command-line string as
  42 above but without the :option:`--target <cmake--build --target>` option.
  43 The ``<makecommand>`` is ignored but should be the full path to
  44 devenv, nmake, make or one of the end user build tools
  45 for legacy invocations.
  46
  47 .. note::
  48  In CMake versions prior to 3.0 this command returned a command
  49  line that directly invokes the native build tool for the current
  50  generator.  Their implementation of the ``PROJECT_NAME`` option
  51  had no useful effects, so CMake now warns on use of the option.