build_command: Add the PARALLEL_LEVEL argument

Issue: #19712

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

Help/release/dev/generate-cmake-build-command-parallel.rst

@@ -0,0 +1,4 @@
+generate-cmake-build-command-parallel
+-------------------------------------
+
+* The :command:`build_command` command gained a ``PARALLEL_LEVEL`` option.

Source/cmBuildCommand.cxx

@@ -28,12 +28,14 @@ bool MainSignature(std::vector<std::string> const& args,
   std::string configuration;
   std::string project_name;
   std::string target;
+  std::string parallel;
   enum Doing
   {
     DoingNone,
     DoingConfiguration,
     DoingProjectName,
-    DoingTarget
+    DoingTarget,
+    DoingParallel
   };
   Doing doing = DoingNone;
   for (unsigned int i = 1; i < args.size(); ++i) {
@@ -43,6 +45,8 @@ bool MainSignature(std::vector<std::string> const& args,
       doing = DoingProjectName;
     } else if (args[i] == "TARGET") {
       doing = DoingTarget;
+    } else if (args[i] == "PARALLEL_LEVEL") {
+      doing = DoingParallel;
     } else if (doing == DoingConfiguration) {
       doing = DoingNone;
       configuration = args[i];
@@ -52,6 +56,9 @@ bool MainSignature(std::vector<std::string> const& args,
     } else if (doing == DoingTarget) {
       doing = DoingNone;
       target = args[i];
+    } else if (doing == DoingParallel) {
+      doing = DoingNone;
+      parallel = args[i];
     } else {
       status.SetError(cmStrCat("unknown argument \"", args[i], "\""));
       return false;
@@ -77,7 +84,7 @@ bool MainSignature(std::vector<std::string> const& args,
   }
 
   std::string makecommand = mf.GetGlobalGenerator()->GenerateCMakeBuildCommand(
-    target, configuration, "", "", mf.IgnoreErrorsCMP0061());
+    target, configuration, parallel, "", mf.IgnoreErrorsCMP0061());
 
   mf.AddDefinition(variable, makecommand);
 

Tests/RunCMake/build_command/ParallelLevel.cmake

@@ -0,0 +1,5 @@
+cmake_policy(SET CMP0061 NEW)
+build_command(cmd PARALLEL_LEVEL 1)
+if(NOT cmd MATCHES [[ --parallel "1"]])
+  message(FATAL_ERROR "Cannot find the --parallel flag")
+endif()

Tests/RunCMake/build_command/RunCMakeTest.cmake

@@ -14,3 +14,5 @@ if(RunCMake_GENERATOR MATCHES "Make")
 else()
   run_cmake(CMP0061-OLD-other)
 endif()
+
+run_cmake(ParallelLevel)