diff --git a/Help/command/build_command.rst b/Help/command/build_command.rst index 21adab9473..6bb7d5802a 100644 --- a/Help/command/build_command.rst +++ b/Help/command/build_command.rst @@ -29,7 +29,7 @@ underlying build system tool. .. versionadded:: 3.21 The ``PARALLEL_LEVEL`` argument can be used to set the - :option:`--parallel ` flag. + :cmake-build-option:`--parallel` flag. .. code-block:: cmake @@ -39,7 +39,7 @@ This second signature is deprecated, but still available for backwards compatibility. Use the first signature instead. It sets the given ```` to a command-line string as -above but without the :option:`--target ` option. +above but without the :cmake-build-option:`--target` option. The ```` is ignored but should be the full path to devenv, nmake, make or one of the end user build tools for legacy invocations. diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index fcb294ecb9..c5c62d3605 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -99,9 +99,8 @@ Generator This chooses the kind of buildsystem to generate. See the :manual:`cmake-generators(7)` manual for documentation of all generators. Run :option:`cmake --help` to see a list of generators available locally. - Optionally use the :option:`-G ` option below to specify a - generator, or simply accept the default CMake chooses for the current - platform. + Optionally use the :cmake-option:`-G` option below to specify a generator, + or simply accept the default CMake chooses for the current platform. When using one of the :ref:`Command-Line Build Tool Generators` CMake expects that the environment needed by the compiler toolchain @@ -158,11 +157,11 @@ source and build trees and generate a buildsystem: In all cases the ```` may be zero or more of the `Options`_ below. The above styles for specifying the source and build trees may be mixed. -Paths specified with :option:`-S ` or :option:`-B ` -are always classified as source or build trees, respectively. Paths -specified with plain arguments are classified based on their content -and the types of paths given earlier. If only one type of path is given, -the current working directory (cwd) is used for the other. For example: +Paths specified with :cmake-option:`-S` or :cmake-option:`-B` are always +classified as source or build trees, respectively. Paths specified with plain +arguments are classified based on their content and the types of paths given +earlier. If only one type of path is given, the current working directory +(cwd) is used for the other. For example: ============================== ============ =========== Command Line Source Dir Build Dir @@ -225,12 +224,12 @@ Options List non-advanced cached variables. List ``CACHE`` variables will run CMake and list all the variables from - the CMake ``CACHE`` that are not marked as ``INTERNAL`` or :prop_cache:`ADVANCED`. - This will effectively display current CMake settings, which can then be - changed with :option:`-D ` option. Changing some of the variables - may result in more variables being created. If ``A`` is specified, then it - will display also advanced variables. If ``H`` is specified, it will also - display help for each variable. + the CMake ``CACHE`` that are not marked as ``INTERNAL`` or + :prop_cache:`ADVANCED`. This will effectively display current CMake + settings, which can then be changed with :cmake-option:`-D` option. + Changing some of the variables may result in more variables being created. + If ``A`` is specified, then it will display also advanced variables. + If ``H`` is specified, it will also display help for each variable. .. option:: -LR[A][H] @@ -499,7 +498,7 @@ Options is an entry in the given comma-separated list of case-sensitive package names. - Like :option:`--debug-find `, but limiting scope + Like :cmake-option:`--debug-find`, but limiting scope to the specified packages. .. option:: --debug-find-var=[,...] @@ -510,7 +509,7 @@ Options as the result variable, where ```` is an entry in the given comma-separated list. - Like :option:`--debug-find `, but limiting scope + Like :cmake-option:`--debug-find`, but limiting scope to the specified variable names. .. option:: --trace @@ -523,7 +522,7 @@ Options Put cmake in trace mode. - Like :option:`--trace `, but with variables expanded. + Like :cmake-option:`--trace`, but with variables expanded. .. option:: --trace-format= @@ -669,9 +668,8 @@ Options .. versionadded:: 3.18 - Used in conjunction with - :option:`--profiling-format ` to output to a - given path. + Used in conjunction with :cmake-option:`--profiling-format` + to output to a given path. .. option:: --profiling-format= @@ -698,9 +696,9 @@ Options on these files, see :manual:`cmake-presets(7)`. The presets are read before all other command line options, although the - :option:`-S ` option can be used to specify the source directory + :cmake-option:`-S` option can be used to specify the source directory containing the ``CMakePresets.json`` and ``CMakeUserPresets.json`` files. - If :option:`-S ` is not given, the current directory is assumed to + If :cmake-option:`-S` is not given, the current directory is assumed to be the top level source directory and must contain the presets files. The options specified by the chosen preset (variables, generator, etc.) can all be overridden by manually specifying them on the command line. For example, @@ -712,18 +710,18 @@ Options Lists the available presets of the specified ````. Valid values for ```` are ``configure``, ``build``, ``test``, ``package``, or ``all``. If ```` is omitted, ``configure`` is assumed. The current working - directory must contain CMake preset files unless the :option:`-S ` + directory must contain CMake preset files unless the :cmake-option:`-S` option is used to specify a different top level source directory. .. option:: --debugger - Enables interactive debugging of the CMake language. CMake exposes a debugging - interface on the pipe named by :option:`--debugger-pipe ` - that conforms to the `Debug Adapter Protocol`_ specification with the following - modifications. + Enables interactive debugging of the CMake language. CMake exposes a + debugging interface on the pipe named by :cmake-option:`--debugger-pipe` + that conforms to the `Debug Adapter Protocol`_ specification with the + following modifications. - The ``initialize`` response includes an additional field named ``cmakeVersion`` - which specifies the version of CMake being debugged. + The ``initialize`` response includes an additional field named + ``cmakeVersion`` which specifies the version of CMake being debugged. .. code-block:: json :caption: Debugger initialize response @@ -1117,7 +1115,7 @@ Available commands are: A JSON object with version information. Keys are: ``string`` - The full version string as displayed by cmake :option:`--version `. + The full version string as displayed by cmake :cmake-option:`--version`. ``major`` The major version number in integer form. ``minor`` @@ -1178,8 +1176,8 @@ Available commands are: ``debugger`` .. versionadded:: 3.27 - ``true`` if the :option:`--debugger ` mode - is supported and ``false`` otherwise. + ``true`` if the :cmake-option:`--debugger` mode is supported + and ``false`` otherwise. .. option:: cat [--] ... diff --git a/Help/manual/cpack.1.rst b/Help/manual/cpack.1.rst index d1ca26825c..b6ac33177f 100644 --- a/Help/manual/cpack.1.rst +++ b/Help/manual/cpack.1.rst @@ -26,11 +26,11 @@ All supported generators are specified in the :manual:`cpack-generators ` manual. The command ``cpack --help`` prints a list of generators supported for the target platform. Which of them are to be used can be selected through the :variable:`CPACK_GENERATOR` variable -or through the command-line option :option:`-G `. +or through the command-line option :cpack-option:`-G`. The :program:`cpack` program is steered by a configuration file written in the :manual:`CMake language `. Unless chosen differently -through the command-line option :option:`--config `, the +through the command-line option :cpack-option:`--config`, the file ``CPackConfig.cmake`` in the current directory is used. In the standard CMake workflow, the file ``CPackConfig.cmake`` is generated diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index f982ecf849..b66a5a7d52 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -57,9 +57,9 @@ in the following cases: * .. versionadded:: 4.4 No arguments are given and no ``CTestTestfile.cmake`` exists. -* The :option:`--no-tests=error ` argument is given and no - tests are executed, e.g., when ``CTestTestfile.cmake`` defines no tests, - or when the given arguments exclude all tests. +* The :ctest-option:`--no-tests=error` argument is given and no tests are + executed, e.g., when ``CTestTestfile.cmake`` defines no tests, or when the + given arguments exclude all tests. * At least one test fails. @@ -175,9 +175,8 @@ The options for running tests are: .. option:: --test-load - While running tests in parallel (e.g. with :option:`-j `), try - not to start tests when they may cause the CPU load to pass above a given - threshold. + While running tests in parallel (e.g. with :ctest-option:`-j`), try not to + start tests when they may cause the CPU load to pass above a given threshold. When :program:`ctest` is run as a `Dashboard Client`_ this sets the ``TestLoad`` option of the `CTest Test Step`_. @@ -187,10 +186,10 @@ The options for running tests are: Make CTest quiet. This option will suppress all the output. The output log file will - still be generated if the :option:`--output-log ` is - specified. Options such as :option:`--verbose `, - :option:`--extra-verbose `, and - :option:`--debug ` are ignored + still be generated if the :ctest-option:`--output-log` is specified. + Options such as :ctest-option:`--verbose`, + :ctest-option:`--extra-verbose`, and + :ctest-option:`--debug` are ignored if ``--quiet`` is specified. .. option:: -O , --output-log @@ -207,16 +206,16 @@ The options for running tests are: This option tells CTest to write test results to ```` in JUnit XML format. If ```` already exists, it will be overwritten. If using the - :option:`-S ` option to run a dashboard script, use the - ``OUTPUT_JUNIT`` keyword with the :command:`ctest_test` command instead. + :ctest-option:`-S` option to run a dashboard script, use the ``OUTPUT_JUNIT`` + keyword with the :command:`ctest_test` command instead. .. option:: -N, --show-only[=] Disable actual execution of tests. This option tells CTest to list the tests that would be run but not - actually run them. Useful in conjunction with the :option:`-R ` - and :option:`-E ` options. + actually run them. Useful in conjunction with the :ctest-option:`-R` + and :ctest-option:`-E` options. .. versionadded:: 3.14 @@ -305,13 +304,11 @@ The options for running tests are: .. option:: -FS , --fixture-exclude-setup - Same as :option:`-FA ` except only matching setup tests are - excluded. + Same as :ctest-option:`-FA` except only matching setup tests are excluded. .. option:: -FC , --fixture-exclude-cleanup - Same as :option:`-FA ` except only matching cleanup tests are - excluded. + Same as :ctest-option:`-FA` except only matching cleanup tests are excluded. .. option:: -I [Start,End,Stride,test#,test#|Test file], --tests-information @@ -325,11 +322,11 @@ The options for running tests are: .. option:: -U, --union - Take the Union of :option:`-I ` and :option:`-R `. + Take the Union of :ctest-option:`-I` and :ctest-option:`-R`. - When both :option:`-R ` and :option:`-I ` are specified - by default the intersection of tests are run. By specifying ``-U`` the union - of tests is run instead. + When both :ctest-option:`-R` and :ctest-option:`-I` are specified by default + the intersection of tests are run. By specifying ``-U`` the union of tests + is run instead. .. option:: --rerun-failed @@ -338,8 +335,8 @@ The options for running tests are: This option tells CTest to perform only the tests that failed during its previous run. When this option is specified, CTest ignores all other options intended to modify the list of tests to run ( - :option:`-L `, :option:`-R `, :option:`-E `, - :option:`-LE `, :option:`-I `, etc). In the event that + :ctest-option:`-L`, :ctest-option:`-R`, :ctest-option:`-E`, + :ctest-option:`-LE`, :ctest-option:`-I`, etc). In the event that CTest runs and no tests fail, subsequent calls to CTest with the ``--rerun-failed`` option will run the set of tests that most recently failed (if any). @@ -552,7 +549,7 @@ The options for running tests are: ctest --verbose -- --success All selected tests receive the same extra arguments. - Use :option:`-R ` or :option:`-L ` to limit + Use :ctest-option:`-R` or :ctest-option:`-L` to limit which tests are executed. A bare ``--`` with no following arguments is silently ignored. @@ -575,17 +572,16 @@ or excluded from a test run by filtering on the labels. Each individual filter is a regular expression applied to the labels attached to a test. -When :option:`-L ` is used, in order for a test to be included in a -test run, each regular expression must match at least one -label. Using more than one :option:`-L ` option means "match **all** -of these". +When :ctest-option:`-L` is used, in order for a test to be included in a test +run, each regular expression must match at least one label. Using more than +one :ctest-option:`-L` option means "match **all** of these". -The :option:`-LE ` option works just like :option:`-L `, +The :ctest-option:`-LE` option works just like :ctest-option:`-L`, but excludes tests rather than including them. A test is excluded if each regular expression matches at least one label. -If a test has no labels attached to it, then :option:`-L ` will never -include that test, and :option:`-LE ` will never exclude that test. +If a test has no labels attached to it, then :ctest-option:`-L` will never +include that test, and :ctest-option:`-LE` will never exclude that test. As an example of tests with labels, consider five tests, with the following labels: @@ -745,7 +741,7 @@ this mode include: .. option:: --test-command The command to run as the test step with the - :option:`--build-and-test ` option. + :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. @@ -792,8 +788,7 @@ Options for Dashboard Client include: This option tells CTest to act as a CDash client where the ```` can be ``Experimental``, ``Nightly``, and ``Continuous``. - Combining ``-M`` and :option:`-T ` is similar to - :option:`-D `. + Combining ``-M`` and :ctest-option:`-T` is similar to :ctest-option:`-D`. .. option:: -T , --test-action @@ -802,8 +797,7 @@ Options for Dashboard Client include: This option tells CTest to act as a CDash client and perform some action such as ``start``, ``build``, ``test`` etc. See `Dashboard Client Steps`_ for the full list of actions. - Combining :option:`-M ` and ``-T`` is similar to - :option:`-D `. + Combining :ctest-option:`-M` and ``-T`` is similar to :ctest-option:`-D`. .. option:: -S