Merge topic 'generate-cmake-build-command-parallel'

d2b856bc92 ctest_build: Add the PARALLEL_LEVEL argument
fc2ac46043 build_command: Add the PARALLEL_LEVEL argument
4dd4e9dd6c cmGlobalGenerator: Add parallel parameter to GenerateCMakeBuildCommand

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Brad King <brad.king@kitware.com>
Merge-request: !6069

3 files changed, 25 insertions, 5 deletions

diff --git a/Help/command/build_command.rst b/Help/command/build_command.rst
index 6659005bee..a03979d10a 100644
--- a/Help/command/build_command.rst
+++ b/Help/command/build_command.rst
@@ -8,23 +8,29 @@ This is mainly intended for internal use by the :module:`CTest` module.
 
   build_command(<variable>
                 [CONFIGURATION <config>]
+                [PARALLEL_LEVEL <parallel>]
                 [TARGET <target>]
                 [PROJECT_NAME <projname>] # legacy, causes warning
                )
 
 Sets the given ``<variable>`` to a command-line string of the form::
 
- <cmake> --build . [--config <config>] [--target <target>...] [-- -i]
+ <cmake> --build . [--config <config>] [--parallel <parallel>] [--target <target>...] [-- -i]
 
 where ``<cmake>`` is the location of the :manual:`cmake(1)` command-line
-tool, and ``<config>`` and ``<target>`` are the values provided to the
-``CONFIGURATION`` and ``TARGET`` options, if any.  The trailing ``-- -i``
-option is added for :ref:`Makefile Generators` if policy :policy:`CMP0061`
-is not set to ``NEW``.
+tool, and ``<config>``, ``<parallel>`` and ``<target>`` are the values
+provided to the ``CONFIGURATION``, ``PARALLEL_LEVEL`` and ``TARGET``
+options, if any.  The trailing ``-- -i`` option is added for
+:ref:`Makefile Generators` if policy :policy:`CMP0061` is not set to
+``NEW``.
 
 When invoked, this ``cmake --build`` command line will launch the
 underlying build system tool.
 
+.. versionadded:: 3.21
+  The ``PARALLEL_LEVEL`` argument can be used to set the ``--parallel``
+  flag.
+
 .. code-block:: cmake
 
   build_command(<cachevariable> <makecommand>)
diff --git a/Help/command/ctest_build.rst b/Help/command/ctest_build.rst
index 4d6dc5a43a..e05df1afcd 100644
--- a/Help/command/ctest_build.rst
+++ b/Help/command/ctest_build.rst
@@ -7,6 +7,7 @@ Perform the :ref:`CTest Build Step` as a :ref:`Dashboard Client`.
 
   ctest_build([BUILD <build-dir>] [APPEND]
               [CONFIGURATION <config>]
+              [PARALLEL_LEVEL <parallel>]
               [FLAGS <flags>]
               [PROJECT_NAME <project-name>]
               [TARGET <target-name>]
@@ -42,6 +43,13 @@ The options are:
   Otherwise the ``-C <cfg>`` option given to the :manual:`ctest(1)`
   command will be used, if any.
 
+``PARALLEL_LEVEL <parallel>``
+  .. versionadded:: 3.21
+
+  Specify the parallel level of the underlying build system.  If not
+  specified, the :envvar:`CMAKE_BUILD_PARALLEL_LEVEL` environment
+  variable will be checked.
+
 ``FLAGS <flags>``
   Pass additional arguments to the underlying build command.
   If not specified the ``CTEST_BUILD_FLAGS`` variable will be checked.
diff --git a/Help/release/dev/generate-cmake-build-command-parallel.rst b/Help/release/dev/generate-cmake-build-command-parallel.rst
new file mode 100644
index 0000000000..1b8dd40acb
--- /dev/null
+++ b/Help/release/dev/generate-cmake-build-command-parallel.rst
@@ -0,0 +1,6 @@
+generate-cmake-build-command-parallel
+-------------------------------------
+
+* The :command:`build_command` command gained a ``PARALLEL_LEVEL`` option.
+
+* The :command:`ctest_build` command gained a ``PARALLEL_LEVEL`` option.