ctest: Allow passing -j without value to choose a contextual default

Under job server integration, added by commit 80fe56c481 (ctest: Add
support for running under a make job server on POSIX systems,
2023-11-15, v3.29.0-rc1~324^2), use a very high default so that
parallelism is effectively limited only by available job server tokens.

Otherwise, choose a default limit based on the number of processors.

Also allow passing `0` to specify unbounded parallelism.

Fixes: #25739

4 files changed, 43 insertions, 11 deletions

diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst
index 4d56577..c1862df 100644
--- a/Help/command/ctest_test.rst
+++ b/Help/command/ctest_test.rst
@@ -18,7 +18,7 @@ Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`.
              [EXCLUDE_FIXTURE <regex>]
              [EXCLUDE_FIXTURE_SETUP <regex>]
              [EXCLUDE_FIXTURE_CLEANUP <regex>]
-             [PARALLEL_LEVEL <level>]
+             [PARALLEL_LEVEL [<level>]]
              [RESOURCE_SPEC_FILE <file>]
              [TEST_LOAD <threshold>]
              [SCHEDULE_RANDOM <ON|OFF>]
@@ -104,9 +104,14 @@ The options are:
 
   Same as ``EXCLUDE_FIXTURE`` except only matching cleanup tests are excluded.
 
-``PARALLEL_LEVEL <level>``
-  Specify a positive number representing the number of tests to
-  be run in parallel.
+``PARALLEL_LEVEL [<level>]``
+  Run tests in parallel, limited to a given level of parallelism.
+
+  .. versionadded:: 3.29
+
+    The ``<level>`` may be omitted, or ``0``, to let ctest use a default
+    level of parallelism, or unbounded parallelism, respectively, as
+    documented by the :option:`ctest --parallel` option.
 
 ``RESOURCE_SPEC_FILE <file>``
   .. versionadded:: 3.16
diff --git a/Help/envvar/CTEST_PARALLEL_LEVEL.rst b/Help/envvar/CTEST_PARALLEL_LEVEL.rst
index 126bdb3..0ef01d5 100644
--- a/Help/envvar/CTEST_PARALLEL_LEVEL.rst
+++ b/Help/envvar/CTEST_PARALLEL_LEVEL.rst
@@ -8,4 +8,15 @@ For example, if ``CTEST_PARALLEL_LEVEL`` is set to 8, CTest will run
 up to 8 tests concurrently as if ``ctest`` were invoked with the
 :option:`--parallel 8 <ctest --parallel>` option.
 
+.. versionchanged:: 3.29
+
+  The value may be empty, or ``0``, to let ctest use a default level of
+  parallelism, or unbounded parallelism, respectively, as documented by
+  the :option:`ctest --parallel` option.
+
+  On Windows, environment variables cannot be set to an empty string.
+  CTest will interpret a whitespace-only string as empty.
+
+  In CMake 3.28 and earlier, an empty or ``0`` value was equivalent to ``1``.
+
 See :manual:`ctest(1)` for more information on parallel test execution.
diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst
index 602a82d..edbd5a4 100644
--- a/Help/manual/ctest.1.rst
+++ b/Help/manual/ctest.1.rst
@@ -118,17 +118,27 @@ Run Tests
  previously interrupted.  If no interruption occurred, the ``-F`` option
  will have no effect.
 
-.. option:: -j <jobs>, --parallel <jobs>
+.. option:: -j [<level>], --parallel [<level>]
 
- Run the tests in parallel using the given number of jobs.
+ Run tests in parallel, optionally limited to a given level of parallelism.
 
- This option tells CTest to run the tests in parallel using given
- number of jobs. This option can also be set by setting the
- :envvar:`CTEST_PARALLEL_LEVEL` environment variable.
+ .. versionadded:: 3.29
 
- This option can be used with the :prop_test:`PROCESSORS` test property.
+    The ``<level>`` may be omitted, or ``0``, in which case:
 
- See `Label and Subproject Summary`_.
+    * Under `Job Server Integration`_, parallelism is limited by
+      available job tokens.
+
+    * Otherwise, if the value is omitted, parallelism is limited
+      by the number of processors, or 2, whichever is larger.
+
+    * Otherwise, if the value is ``0``, parallelism is unbounded.
+
+ This option may instead be specified by the :envvar:`CTEST_PARALLEL_LEVEL`
+ environment variable.
+
+ This option can be used with the :prop_test:`PROCESSORS` test property.
+ See the `Label and Subproject Summary`_.
 
 .. option:: --resource-spec-file <file>
 
diff --git a/Help/release/3.29.rst b/Help/release/3.29.rst
index 659237e..42f6491 100644
--- a/Help/release/3.29.rst
+++ b/Help/release/3.29.rst
@@ -150,6 +150,12 @@ CTest
 * :manual:`ctest(1)` now supports :ref:`job server integration
   <ctest-job-server-integration>` on POSIX systems.
 
+* The :option:`ctest -j` option may now be given without a value to let
+  ctest choose a default level of parallelism, or with ``0`` to let ctest
+  use unbounded parallelism.  The corresponding :envvar:`CTEST_PARALLEL_LEVEL`
+  environment variable, if set to the empty string, is now equivalent to
+  passing ``-j`` with no value.
+
 * The :command:`ctest_test` command gained options
   ``INCLUDE_FROM_FILE`` and ``EXCLUDE_FROM_FILE`` to run or exclude
   tests named in a file.