ctest_build: Add the PARALLEL_LEVEL argument

Fixes: #19712

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.

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

@@ -2,3 +2,5 @@ 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.

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,7 +99,7 @@ cmCTestGenericHandler* cmCTestBuildCommand::InitializeHandler()
       std::string dir = this->CTest->GetCTestConfiguration("BuildDirectory");
       std::string buildCommand =
         this->GlobalGenerator->GenerateCMakeBuildCommand(
-          cmakeBuildTarget, cmakeBuildConfiguration, "",
+          cmakeBuildTarget, cmakeBuildConfiguration, this->ParallelLevel,
           cmakeBuildAdditionalFlags, this->Makefile->IgnoreErrorsCMP0061());
       cmCTestOptionalLog(this->CTest, HANDLER_VERBOSE_OUTPUT,
                          "SetMakeCommand:" << buildCommand << "\n",

Source/CTest/cmCTestBuildCommand.h

@@ -60,4 +60,5 @@ protected:
   std::string Configuration;
   std::string Flags;
   std::string ProjectName;
+  std::string ParallelLevel;
 };

Tests/RunCMake/ctest_build/ParallelLevel-check.cmake

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

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