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

13 files changed, 70 insertions, 13 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.
diff --git a/Source/CPack/cmCPackGenerator.cxx b/Source/CPack/cmCPackGenerator.cxx
index c512a36158..cd2adaa304 100644
--- a/Source/CPack/cmCPackGenerator.cxx
+++ b/Source/CPack/cmCPackGenerator.cxx
@@ -694,7 +694,7 @@ int cmCPackGenerator::RunPreinstallTarget(
   // Does this generator require pre-install?
   if (const char* preinstall = globalGenerator->GetPreinstallTargetName()) {
     std::string buildCommand = globalGenerator->GenerateCMakeBuildCommand(
-      preinstall, buildConfig, "", false);
+      preinstall, buildConfig, "", "", false);
     cmCPackLogger(cmCPackLog::LOG_DEBUG,
                   "- Install command: " << buildCommand << std::endl);
     cmCPackLogger(cmCPackLog::LOG_OUTPUT,
diff --git a/Source/CTest/cmCTestBuildCommand.cxx b/Source/CTest/cmCTestBuildCommand.cxx
index 88e2871604..483c316a63 100644
--- a/Source/CTest/cmCTestBuildCommand.cxx
+++ b/Source/CTest/cmCTestBuildCommand.cxx
@@ -27,6 +27,7 @@ void cmCTestBuildCommand::BindArguments()
   this->Bind("CONFIGURATION"_s, this->Configuration);
   this->Bind("FLAGS"_s, this->Flags);
   this->Bind("PROJECT_NAME"_s, this->ProjectName);
+  this->Bind("PARALLEL_LEVEL"_s, this->ParallelLevel);
 }
 
 cmCTestBuildCommand::~cmCTestBuildCommand() = default;
@@ -98,8 +99,8 @@ cmCTestGenericHandler* cmCTestBuildCommand::InitializeHandler()
       std::string dir = this->CTest->GetCTestConfiguration("BuildDirectory");
       std::string buildCommand =
         this->GlobalGenerator->GenerateCMakeBuildCommand(
-          cmakeBuildTarget, cmakeBuildConfiguration, cmakeBuildAdditionalFlags,
-          this->Makefile->IgnoreErrorsCMP0061());
+          cmakeBuildTarget, cmakeBuildConfiguration, this->ParallelLevel,
+          cmakeBuildAdditionalFlags, this->Makefile->IgnoreErrorsCMP0061());
       cmCTestOptionalLog(this->CTest, HANDLER_VERBOSE_OUTPUT,
                          "SetMakeCommand:" << buildCommand << "\n",
                          this->Quiet);
diff --git a/Source/CTest/cmCTestBuildCommand.h b/Source/CTest/cmCTestBuildCommand.h
index 00dbcc451b..1254dad9bb 100644
--- a/Source/CTest/cmCTestBuildCommand.h
+++ b/Source/CTest/cmCTestBuildCommand.h
@@ -60,4 +60,5 @@ protected:
   std::string Configuration;
   std::string Flags;
   std::string ProjectName;
+  std::string ParallelLevel;
 };
diff --git a/Source/cmBuildCommand.cxx b/Source/cmBuildCommand.cxx
index 2eaf31561f..56b080aa6c 100644
--- a/Source/cmBuildCommand.cxx
+++ b/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);
 
@@ -104,7 +111,7 @@ bool TwoArgsSignature(std::vector<std::string> const& args,
   }
 
   std::string makecommand = mf.GetGlobalGenerator()->GenerateCMakeBuildCommand(
-    "", configType, "", mf.IgnoreErrorsCMP0061());
+    "", configType, "", "", mf.IgnoreErrorsCMP0061());
 
   if (cacheValue) {
     return true;
diff --git a/Source/cmGlobalGenerator.cxx b/Source/cmGlobalGenerator.cxx
index ab76260f95..55fba7978f 100644
--- a/Source/cmGlobalGenerator.cxx
+++ b/Source/cmGlobalGenerator.cxx
@@ -2077,7 +2077,7 @@ bool cmGlobalGenerator::Open(const std::string& bindir,
 
 std::string cmGlobalGenerator::GenerateCMakeBuildCommand(
   const std::string& target, const std::string& config,
-  const std::string& native, bool ignoreErrors)
+  const std::string& parallel, const std::string& native, bool ignoreErrors)
 {
   std::string makeCommand = cmSystemTools::GetCMakeCommand();
   makeCommand =
@@ -2087,6 +2087,11 @@ std::string cmGlobalGenerator::GenerateCMakeBuildCommand(
     makeCommand += config;
     makeCommand += "\"";
   }
+  if (!parallel.empty()) {
+    makeCommand += " --parallel \"";
+    makeCommand += parallel;
+    makeCommand += "\"";
+  }
   if (!target.empty()) {
     makeCommand += " --target \"";
     makeCommand += target;
diff --git a/Source/cmGlobalGenerator.h b/Source/cmGlobalGenerator.h
index 590de268cf..fee0359b34 100644
--- a/Source/cmGlobalGenerator.h
+++ b/Source/cmGlobalGenerator.h
@@ -249,9 +249,13 @@ public:
 
   virtual void PrintBuildCommandAdvice(std::ostream& os, int jobs) const;
 
-  /** Generate a "cmake --build" call for a given target and config.  */
+  /**
+   * Generate a "cmake --build" call for a given target, config and parallel
+   * level.
+   */
   std::string GenerateCMakeBuildCommand(const std::string& target,
                                         const std::string& config,
+                                        const std::string& parallel,
                                         const std::string& native,
                                         bool ignoreErrors);
 
diff --git a/Tests/RunCMake/build_command/ParallelLevel.cmake b/Tests/RunCMake/build_command/ParallelLevel.cmake
new file mode 100644
index 0000000000..1d1e525f75
--- /dev/null
+++ b/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()
diff --git a/Tests/RunCMake/build_command/RunCMakeTest.cmake b/Tests/RunCMake/build_command/RunCMakeTest.cmake
index c3bef4c817..030db0b5c2 100644
--- a/Tests/RunCMake/build_command/RunCMakeTest.cmake
+++ b/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)
diff --git a/Tests/RunCMake/ctest_build/ParallelLevel-check.cmake b/Tests/RunCMake/ctest_build/ParallelLevel-check.cmake
new file mode 100644
index 0000000000..f45d2a29f5
--- /dev/null
+++ b/Tests/RunCMake/ctest_build/ParallelLevel-check.cmake
@@ -0,0 +1,11 @@
+file(GLOB build_xml_file "${RunCMake_TEST_BINARY_DIR}/Testing/*/Build.xml")
+if(build_xml_file)
+  file(STRINGS "${build_xml_file}" build_cmd LIMIT_COUNT 1 REGEX "<BuildCommand>")
+  if(NOT build_cmd MATCHES [[ --parallel "1"]])
+    set(RunCMake_TEST_FAILED
+      "Build.xml does not have expected build command with --parallel flag"
+      )
+  endif()
+else()
+  set(RunCMake_TEST_FAILED "Build.xml not found")
+endif()
diff --git a/Tests/RunCMake/ctest_build/RunCMakeTest.cmake b/Tests/RunCMake/ctest_build/RunCMakeTest.cmake
index 072fbac223..511cd71fbb 100644
--- a/Tests/RunCMake/ctest_build/RunCMakeTest.cmake
+++ b/Tests/RunCMake/ctest_build/RunCMakeTest.cmake
@@ -10,6 +10,7 @@ function(run_ctest_build CASE_NAME)
 endfunction()
 
 run_ctest_build(BuildQuiet QUIET)
+run_ctest_build(ParallelLevel PARALLEL_LEVEL 1)
 
 function(run_BuildFailure)
   set(CASE_CMAKELISTS_SUFFIX_CODE [[