Help: Clarify interaction between CTest parallelism toggles

Help/command/ctest_test.rst

@@ -115,6 +115,13 @@ The options are:
     default level of parallelism, or unbounded parallelism, respectively, as
     documented by the :option:`ctest --parallel` option.
 
+  If given, this argument takes precedence over a test preset's
+  :preset:`testPresets.execution.jobs` field. Both this argument and that
+  field take precedence over the :envvar:`CTEST_PARALLEL_LEVEL` environment
+  variable, and over an explicit :option:`ctest --parallel` given on the
+  command line. See :envvar:`CTEST_PARALLEL_LEVEL` for the full precedence
+  order.
+
 ``RESOURCE_SPEC_FILE <file>``
   .. versionadded:: 3.16
 

Help/envvar/CTEST_PARALLEL_LEVEL.rst

@@ -5,12 +5,12 @@ CTEST_PARALLEL_LEVEL
 
 Specify the number of tests for CTest to run in parallel.
 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
+up to 8 tests concurrently as if :manual:`ctest(1)` 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
+  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.
 
@@ -18,4 +18,23 @@ up to 8 tests concurrently as if ``ctest`` were invoked with the
 
   In CMake 3.28 and earlier, an empty or ``0`` value was equivalent to ``1``.
 
+This environment variable is ignored if :option:`ctest --parallel` is given on
+the command line, and is overridden by the :preset:`testPresets.execution.jobs`
+field of a test preset, if that field is set.
+
+A test preset may also set this variable itself, using its own
+:preset:`testPresets.environment` field. Doing so is equivalent to setting
+the variable in the calling process's environment, except that it takes
+effect only for the preset's Test step, and only if ``execution.jobs`` is
+not also set (which would take precedence, as noted above).
+
+When a test preset is used by a :command:`ctest_test` command in a
+:ref:`CTest Script`, that command's own ``PARALLEL_LEVEL`` argument, if given,
+takes precedence over the preset's ``execution.jobs`` field. Together,
+``PARALLEL_LEVEL`` and ``execution.jobs`` take precedence not only over this
+environment variable, but over an explicit :option:`ctest --parallel` on the
+command line as well. This differs from a preset used directly via
+:option:`ctest --preset`, where an explicit ``--parallel`` always wins over the
+preset's ``execution.jobs`` field.
+
 See :manual:`ctest(1)` for more information on parallel test execution.

Help/manual/ctest.1.rst

@@ -187,7 +187,8 @@ The options for running tests are:
     * Otherwise, if the value is ``0``, parallelism is unbounded.
 
  This option may instead be specified by the :envvar:`CTEST_PARALLEL_LEVEL`
- environment variable.
+ environment variable.  See the documentation of that variable for how it
+ interacts with a test preset's :preset:`testPresets.execution.jobs` field.
 
  This option can be used with the :prop_test:`PROCESSORS` test property.
  See the `Label and Subproject Summary`_.

Help/manual/presets/execution-properties.rst

@@ -20,6 +20,11 @@
   :ctest-option:`--parallel` on the command line. If the value is
   ``0``, it is equivalent to unbounded parallelism.
 
+  If set, this field takes precedence over the
+  :envvar:`CTEST_PARALLEL_LEVEL` environment variable,
+  including when that variable is instead set via this test
+  preset's own :preset:`testPresets.environment` field.
+
   .. presets-versionchanged:: 11
 
     This field can also be a string, in which case it must be

Help/manual/presets/schema.yaml

@@ -1624,6 +1624,11 @@ properties:
                 :ctest-option:`--parallel` on the command line. If the value is
                 ``0``, it is equivalent to unbounded parallelism.
 
+                If set, this field takes precedence over the
+                :envvar:`CTEST_PARALLEL_LEVEL` environment variable,
+                including when that variable is instead set via this test
+                preset's own :preset:`testPresets.environment` field.
+
                 .. presets-versionchanged:: 11
 
                   This field can also be a string, in which case it must be