Merge topic 'ctest-help-args'

c0eddfb8c8 ctest: Add missing help strings for documented options 2f3de9e2f3 Help/ctest: Improve formatting and grammar 36e486555d Help, ctest: Add argument placeholders e16767d962 presets: Fix command help for --presets-file Acked-by: Kitware Robot <kwrobot@kitware.com> Merge-request: !12088
2026-08-08 08:40:48 +00:00 · 2026-05-20 19:01:20 +00:00
parent aa08e3b2e0 c0eddfb8c8
commit d2e20c74ed
4 changed files with 97 additions and 80 deletions
--- a/Help/manual/ctest.1.rst
+++ b/Help/manual/ctest.1.rst
@@ -153,7 +153,7 @@ The options for running tests are:

 Output anything outputted by the test program if the test should fail.
 This option can also be enabled by setting the
- :envvar:`CTEST_OUTPUT_ON_FAILURE` environment variable
+ :envvar:`CTEST_OUTPUT_ON_FAILURE` environment variable.

 .. option:: --stop-on-failure

@@ -302,7 +302,8 @@ The options for running tests are:
 The file must contain one exact test name per line.
 Lines that do not exactly match any test names are ignored.
 This option can be combined with the other options like
- ``-R``, ``-E``, ``-L`` or ``-LE``.
+ :ctest-option:`-R`, :ctest-option:`-E`, :ctest-option:`-L`, or
+ :ctest-option:`-LE`.

 .. option:: --exclude-from-file <filename>

@@ -314,7 +315,8 @@ The options for running tests are:
 The file must contain one exact test name per line.
 Lines that do not exactly match any test names are ignored.
 This option can be combined with the other options like
- ``-R``, ``-E``, ``-L`` or ``-LE``.
+ :ctest-option:`-R`, :ctest-option:`-E`, :ctest-option:`-L`, or
+ :ctest-option:`-LE`.

 .. option:: -FA <regex>, --fixture-exclude-any <regex>

@@ -472,7 +474,7 @@ The options for running tests are:
 Truncate ``tail`` (default), ``middle`` or ``head`` of test output once
 maximum output size is reached.

-.. option:: --overwrite
+.. option:: --overwrite <option-name>

 Overwrite CTest configuration option.

@@ -482,7 +484,7 @@ The options for running tests are:
 .. option:: --force-new-ctest-process

 Ignored.  This option once disabled a now-removed optimization
- for tests running ``ctest`` itself.
+ for tests running :program:`ctest` itself.

 .. option:: --schedule-random

@@ -491,16 +493,16 @@ The options for running tests are:
 This option will run the tests in a random order.  It is commonly
 used to detect implicit dependencies in a test suite.

-.. option:: --schedule-random-seed
+.. option:: --schedule-random-seed <seed>

 .. versionadded:: 4.1

- Override the random order seed
+ Override the random order seed.

 This option is used to allow recreating failures owing to
- random order of execution by ``--schedule-random``.
+ random order of execution by :ctest-option:`--schedule-random`.

-.. option:: --submit-index
+.. option:: --submit-index <index>

 Legacy option for old Dart2 dashboard server feature.
 Do not use.
@@ -694,11 +696,11 @@ be provided to use ``--build-and-test``.  If ``--test-command`` is specified
 then that will be run after the build is complete.  Other options that affect
 this mode include:

-.. option:: --build-and-test
+.. option:: --build-and-test <path-to-source> <path-to-build>

 Switch into the build and test mode.

-.. option:: --build-target
+.. option:: --build-target <tgt>

 Specify a specific target to build.  The option can be given multiple times
 with different targets, in which case each target is built in turn.
@@ -709,11 +711,11 @@ this mode include:

 .. option:: --build-nocmake

- Run the build without running cmake first.
+ Run the build without running :program:`cmake` first.

- Skip the cmake step.
+ Skip the :program:`cmake` step.

-.. option:: --build-run-dir
+.. option:: --build-run-dir <dir>

 Specify directory to run programs from.

@@ -723,57 +725,59 @@ this mode include:

 Run CMake twice.

-.. option:: --build-exe-dir
+.. option:: --build-exe-dir <dir>

 Specify the directory for the executable.

-.. option:: --build-generator
+.. option:: --build-generator <generator-name>

 Specify the generator to use. See the :manual:`cmake-generators(7)` manual.

-.. option:: --build-generator-platform
+.. option:: --build-generator-platform <platform-name>

 Specify the generator-specific platform.

-.. option:: --build-generator-toolset
+.. option:: --build-generator-toolset <toolset-name>

 Specify the generator-specific toolset.

-.. option:: --build-project
+.. option:: --build-project <project-name>

 Specify the name of the project to build.

-.. option:: --build-makeprogram
+.. option:: --build-makeprogram <program-name>

 Specify the explicit make program to be used by CMake when configuring and
- building the project. Only applicable for Make and Ninja based generators.
+ building the project. Only applicable for :ref:`Makefile Generators` and
+ :ref:`Ninja Generators`.

 .. option:: --build-noclean

 Skip the make clean step.

-.. option:: --build-config-sample
+.. option:: --build-config-sample <exe-name>

 A sample executable to use to determine the configuration that
- should be used.  e.g.  ``Debug``, ``Release`` etc.
+ should be used (e.g.  ``Debug``, ``Release``, etc.).

-.. option:: --build-options
+.. option:: --build-options [<options>...]

- Additional options for configuring the build (i.e. for CMake, not for
- the build tool).  Note that if this is specified, the ``--build-options``
- keyword and its arguments must be the last option given on the command
- line, with the possible exception of ``--test-command``.
+ Additional options for configuring the build (i.e. for :manual:`cmake(1)`,
+ not for the build tool).  Note that if this is specified, the
+ ``--build-options`` keyword and its arguments must be the last option given
+ on the command line, with the possible exception of
+ :ctest-option:`--test-command`.

-.. option:: --test-command
+.. option:: --test-command <command>

 The command to run as the test step with the
 :ctest-option:`--build-and-test` option.
 All arguments following this keyword will be assumed to be part of the
 test command line, so it must be the last option given.

-.. option:: --test-timeout
+.. option:: --test-timeout <timeout>

- The time limit in seconds
+ The time limit in seconds.

 .. _`Dashboard Client`:

@@ -859,9 +863,9 @@ The available ``<dashboard-options>`` are the following:

 .. option:: --group <group>

- Specify what group you'd like to submit results to
+ Specify the group to which to submit results.

- Submit dashboard to specified group instead of default one.  By
+ Submit dashboard to specified group instead of the default.  By
 default, the dashboard is submitted to Nightly, Experimental, or
 Continuous group, but by specifying this option, the group can be
 arbitrary.
@@ -1780,8 +1784,8 @@ model is defined as follows:
  ``config``
    Optional field specifying the configuration for which the test will run.
    This will always match the :ctest-option:`-C` option specified on the
-    ``ctest`` command line.  If no such option was given, this field will not
-    be present.
+    :program:`ctest` command line.  If no such option was given, this field
+    will not be present.
  ``command``
    Optional array where the first element is the test command and the
    remaining elements are the command arguments.  Normally, this field should
@@ -1818,11 +1822,11 @@ prevents them from trying to claim resources that are not available.
 When the resource allocation feature is used, CTest will not oversubscribe
 resources. For example, if a resource has 8 slots, CTest will not run tests
 that collectively use more than 8 slots at a time. This has the effect of
-limiting how many tests can run at any given time, even if a high ``-j``
-argument is used, if those tests all use some slots from the same resource.
-In addition, it means that a single test that uses more of a resource than is
-available on a machine will not run at all (and will be reported as
-``Not Run``).
+limiting how many tests can run at any given time, even if a high
+:ctest-option:`-j` argument is used, if those tests all use some slots from the
+same resource. In addition, it means that a single test that uses more of a
+resource than is available on a machine will not run at all (and will be
+reported as ``Not Run``).

 A common use case for this feature is for tests that require the use of a GPU.
 Multiple tests can simultaneously allocate memory from a GPU, but if too many
@@ -1860,27 +1864,27 @@ form of a set of
 described below. Using this information to decide which resource to connect to
 is left to the test writer.

-The ``RESOURCE_GROUPS`` property tells CTest what resources a test expects
-to use grouped in a way meaningful to the test.  The test itself must read
-the :ref:`environment variables <ctest-resource-environment-variables>` to
+The :prop_test:`RESOURCE_GROUPS` property tells CTest what resources a test
+expects to use grouped in a way meaningful to the test.  The test itself must
+read the :ref:`environment variables <ctest-resource-environment-variables>` to
 determine which resources have been allocated to each group.  For example,
 each group may correspond to a process the test will spawn when executed.

-Note that even if a test specifies a ``RESOURCE_GROUPS`` property, it is still
-possible for that to test to run without any resource allocation (and without
-the corresponding
+Note that even if a test specifies a :prop_test:`RESOURCE_GROUPS` property, it
+is still possible for that to test to run without any resource allocation
+(and without the corresponding
 :ref:`environment variables <ctest-resource-environment-variables>`)
 if the user does not pass a resource specification file. Passing this file,
-either through the ``--resource-spec-file`` command-line argument or the
-``RESOURCE_SPEC_FILE`` argument to :command:`ctest_test`, is what activates the
-resource allocation feature. Tests should check the
+either through the :ctest-option:`--resource-spec-file` command-line argument
+or the ``RESOURCE_SPEC_FILE`` argument to :command:`ctest_test`, is what
+activates the resource allocation feature. Tests should check the
 ``CTEST_RESOURCE_GROUP_COUNT`` environment variable to find out whether or not
 resource allocation is activated. This variable will always (and only) be
 defined if resource allocation is activated. If resource allocation is not
 activated, then the ``CTEST_RESOURCE_GROUP_COUNT`` variable will not exist,
-even if it exists for the parent :program:`ctest` process. If a test absolutely must
-have resource allocation, then it can return a failing exit code or use the
-:prop_test:`SKIP_RETURN_CODE` or :prop_test:`SKIP_REGULAR_EXPRESSION`
+even if it exists for the parent :program:`ctest` process. If a test absolutely
+must have resource allocation, then it can return a failing exit code or use
+the :prop_test:`SKIP_RETURN_CODE` or :prop_test:`SKIP_REGULAR_EXPRESSION`
 properties to indicate a skipped test.

 .. _`ctest-resource-specification-file`:
@@ -1890,7 +1894,7 @@ Resource Specification File

 The resource specification file is a JSON file which is passed to CTest in one
 of a number of ways. It can be specified on the command line with the
-:option:`ctest --resource-spec-file` option, it can be given using the
+:ctest-option:`--resource-spec-file` option, it can be given using the
 ``RESOURCE_SPEC_FILE`` argument of :command:`ctest_test`, or it can be
 generated dynamically as part of test execution (see
 :ref:`ctest-resource-dynamically-generated-spec-file`).
@@ -2020,9 +2024,9 @@ The following variables are passed to the test process:
  * ``CTEST_RESOURCE_GROUP_COUNT=3``

  This variable will only be defined if :manual:`ctest(1)` has been given a
-  ``--resource-spec-file``, or if :command:`ctest_test` has been given a
-  ``RESOURCE_SPEC_FILE``. If no resource specification file has been given,
-  this variable will not be defined.
+  :ctest-option:`--resource-spec-file`, or if :command:`ctest_test` has been
+  given a ``RESOURCE_SPEC_FILE``. If no resource specification file has been
+  given, this variable will not be defined.

 .. envvar:: CTEST_RESOURCE_GROUP_<num>

@@ -2106,8 +2110,8 @@ For example, consider the ``Makefile``:
 .. literalinclude:: CTEST_EXAMPLE_MAKEFILE_JOB_SERVER.make
  :language: make

-When invoked via ``make -j 2 test``, ``ctest`` connects to the job server,
-acquires a token for each test, and runs at most 2 tests concurrently.
+When invoked via ``make -j 2 test``, CTest connects to the job server, acquires
+a token for each test, and runs at most 2 tests concurrently.

 On Windows systems, job server integration is not yet implemented.

--- a/Source/cmakemain.cxx
+++ b/Source/cmakemain.cxx
@@ -1049,7 +1049,7 @@ int do_workflow(int ac, char const* const* av)
      "Usage: cmake --workflow <options>\n"
      "Options:\n"
      "  --preset <preset>     = Workflow preset to execute.\n"
-      "  --presets-file <file>  = Path to a presets file.\n"
+      "  --presets-file <file> = Path to a presets file.\n"
      "  --list-presets        = List available workflow presets.\n"
      "  --fresh               = Configure a fresh build tree, removing any "
                                "existing cache file.\n"
--- a/Source/ctest.cxx
+++ b/Source/ctest.cxx
@@ -29,6 +29,8 @@ cmDocumentationEntry const cmDocumentationUsage = { {}, "  ctest [options]" };
 cmDocumentationEntry const cmDocumentationOptions[] = {
  { "--preset <preset>, --preset=<preset>",
    "Read arguments from a test preset." },
+  { "--presets-file <file>, --presets-file=<file>",
+    "Load test presets from the given file." },
  { "--list-presets", "List available test presets." },
  { "-C <cfg>, --build-config <cfg>", "Choose configuration to test." },
  { "--progress", "Enable short progress output from tests." },
@@ -125,32 +127,39 @@ cmDocumentationEntry const cmDocumentationOptions[] = {
    "Disable timing summary information for "
    "subprojects." },
  { "--test-dir <dir>", "Specify the directory in which to look for tests." },
-  { "--build-and-test", "Configure, build and run a test." },
-  { "--build-target", "Specify a specific target to build." },
+  { "--build-and-test <path-to-source> <path-to-build>",
+    "Configure, build and run a test." },
+  { "--build-target <tgt>", "Specify a specific target to build." },
  { "--build-nocmake", "Run the build without running cmake first." },
-  { "--build-run-dir", "Specify directory to run programs from." },
+  { "--build-run-dir <dir>", "Specify directory to run programs from." },
  { "--build-two-config", "Run CMake twice" },
-  { "--build-exe-dir", "Specify the directory for the executable." },
-  { "--build-generator", "Specify the generator to use." },
-  { "--build-generator-platform", "Specify the generator-specific platform." },
-  { "--build-generator-toolset", "Specify the generator-specific toolset." },
-  { "--build-project", "Specify the name of the project to build." },
-  { "--build-makeprogram", "Specify the make program to use." },
+  { "--build-exe-dir <dir>", "Specify the directory for the executable." },
+  { "--build-generator <generator-name>", "Specify the generator to use." },
+  { "--build-generator-platform <platform-name>",
+    "Specify the generator-specific platform." },
+  { "--build-generator-toolset <toolset-name>",
+    "Specify the generator-specific toolset." },
+  { "--build-project <project-name>",
+    "Specify the name of the project to build." },
+  { "--build-makeprogram <program-name>", "Specify the make program to use." },
  { "--build-noclean", "Skip the make clean step." },
-  { "--build-config-sample",
-    "A sample executable to use to determine the configuration" },
-  { "--build-options", "Add extra options to the build step." },
-
-  { "--test-command", "The test to run with the --build-and-test option." },
-  { "--test-timeout", "The time limit in seconds, internal use only." },
-  { "--test-load", "CPU load threshold for starting new parallel tests." },
+  { "--build-config-sample <exe-name>",
+    "A sample executable to use to determine the configuration." },
+  { "--build-options [<options>...]", "Add extra options to the build step." },
+  { "--test-command <command>",
+    "The test to run with the --build-and-test option." },
+  { "--test-timeout <timeout>",
+    "The time limit in seconds, internal use only." },
+  { "--test-load <level>",
+    "CPU load threshold for starting new parallel tests." },
  { "--tomorrow-tag", "Nightly or experimental starts with next day tag." },
-  { "--overwrite", "Overwrite CTest configuration option." },
+  { "--overwrite <option-name>", "Overwrite CTest configuration option." },
  { "--extra-submit <file>[;<file>]", "Submit extra files to the dashboard." },
  { "--http-header <header>", "Append HTTP header when submitting" },
  { "--schedule-random", "Use a random order for scheduling tests" },
-  { "--schedule-random-seed", "Override seed for random order of tests" },
-  { "--submit-index",
+  { "--schedule-random-seed <seed>",
+    "Override seed for random order of tests" },
+  { "--submit-index <index>",
    "Submit individual dashboard tests with specific index" },
  { "--timeout <seconds>", "Set the default test timeout." },
  { "--stop-time <time>",
@@ -159,7 +168,11 @@ cmDocumentationEntry const cmDocumentationOptions[] = {
  { "--no-compress-output", "Do not compress test output when submitting." },
  { "--print-labels", "Print all available test labels." },
  { "--no-tests=<[error|ignore]>",
-    "Regard no tests found either as 'error' or 'ignore' it." }
+    "Regard no tests found either as 'error' or 'ignore' it." },
+  { "--collect-instrumentation <build>",
+    "Manually collect instrumentation data from the specified build "
+    "directory." },
+  { "--", "Forward extra arguments to test executables." },
 };
 } // anonymous namespace

--- a/Tests/RunCMake/CMakePresetsWorkflow/InvalidOption-stderr.txt
+++ b/Tests/RunCMake/CMakePresetsWorkflow/InvalidOption-stderr.txt
@@ -2,6 +2,6 @@
 Usage: cmake --workflow <options>
 Options:
  --preset <preset>     = Workflow preset to execute\.
-  --presets-file <file>  = Path to a presets file\.
+  --presets-file <file> = Path to a presets file\.
  --list-presets        = List available workflow presets\.
  --fresh               = Configure a fresh build tree, removing any existing cache file\.$