diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 61482ea22f..8a81c0df85 100644 --- 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 @@ -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 , --fixture-exclude-any @@ -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 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 .. 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 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 Switch into the build and test mode. -.. option:: --build-target +.. option:: --build-target 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 Specify directory to run programs from. @@ -723,57 +725,59 @@ this mode include: Run CMake twice. -.. option:: --build-exe-dir +.. option:: --build-exe-dir Specify the directory for the executable. -.. option:: --build-generator +.. option:: --build-generator Specify the generator to use. See the :manual:`cmake-generators(7)` manual. -.. option:: --build-generator-platform +.. option:: --build-generator-platform Specify the generator-specific platform. -.. option:: --build-generator-toolset +.. option:: --build-generator-toolset Specify the generator-specific toolset. -.. option:: --build-project +.. option:: --build-project Specify the name of the project to build. -.. option:: --build-makeprogram +.. option:: --build-makeprogram 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 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 [...] - 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 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 - The time limit in seconds + The time limit in seconds. .. _`Dashboard Client`: @@ -859,9 +863,9 @@ The available ```` are the following: .. option:: --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 ` 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 ` 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 `) 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_ @@ -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. diff --git a/Source/cmakemain.cxx b/Source/cmakemain.cxx index d7f0c8858c..842c4b87c2 100644 --- a/Source/cmakemain.cxx +++ b/Source/cmakemain.cxx @@ -1049,7 +1049,7 @@ int do_workflow(int ac, char const* const* av) "Usage: cmake --workflow \n" "Options:\n" " --preset = Workflow preset to execute.\n" - " --presets-file = Path to a presets file.\n" + " --presets-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" diff --git a/Source/ctest.cxx b/Source/ctest.cxx index fc8e5a3ee6..8052f0ceb6 100644 --- a/Source/ctest.cxx +++ b/Source/ctest.cxx @@ -29,6 +29,8 @@ cmDocumentationEntry const cmDocumentationUsage = { {}, " ctest [options]" }; cmDocumentationEntry const cmDocumentationOptions[] = { { "--preset , --preset=", "Read arguments from a test preset." }, + { "--presets-file , --presets-file=", + "Load test presets from the given file." }, { "--list-presets", "List available test presets." }, { "-C , --build-config ", "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 ", "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 ", + "Configure, build and run a test." }, + { "--build-target ", "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 ", "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 ", "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-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 ", + "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." }, { "--tomorrow-tag", "Nightly or experimental starts with next day tag." }, - { "--overwrite", "Overwrite CTest configuration option." }, + { "--overwrite ", "Overwrite CTest configuration option." }, { "--extra-submit [;]", "Submit extra files to the dashboard." }, { "--http-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 ", + "Override seed for random order of tests" }, + { "--submit-index ", "Submit individual dashboard tests with specific index" }, { "--timeout ", "Set the default test timeout." }, { "--stop-time