dilim/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-06-30 19:57:41 +00:00
Code Issues Packages Projects Releases Wiki Activity

Help: Add roles to abbreviate command-line options

Browse Source 
Add a handful of helper roles that allow many more command-line option
references to be written without explicit targets. Specifically, what
used to be written ':option:`--foo[=bar] <program --foo>` can now be
written ':program-option:`--foo`'. This allows many such references to
be significantly shortened.

For now, supported programs are 'cmake', 'cpack'. 'ctest',
'cmake--build' and 'cmake--install', which should cover most cases, but
more can be trivially added. Additionally, this does not make a
concerted effort to replace all existing uses, as it is intended mainly
for use in future updates.
This commit is contained in:
Matthew Woehlke
2026-03-31 12:56:16 -04:00
parent ed6b21f478
commit 3d82ccbe0d
5 changed files with 102 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
Help/command/build_command.rst
View File

@@ -29,7 +29,7 @@ underlying build system tool.
.. versionadded:: 3.21
The ``PARALLEL_LEVEL`` argument can be used to set the
:option:`--parallel <cmake--build --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 ``<cachevariable>`` to a command-line string as
above but without the :option:`--target <cmake--build --target>` option.
above but without the :cmake-build-option:`--target` option.
The ``<makecommand>`` is ignored but should be the full path to
devenv, nmake, make or one of the end user build tools
for legacy invocations.

62
Help/manual/cmake.1.rst
View File

@@ -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 <cmake -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 ``<options>`` 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 <cmake -S>` or :option:`-B <cmake -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 <cmake -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] <regex>
@@ -499,7 +498,7 @@ Options
is an entry in the given comma-separated list of case-sensitive package
names.
Like :option:`--debug-find <cmake --debug-find>`, but limiting scope
Like :cmake-option:`--debug-find`, but limiting scope
to the specified packages.
.. option:: --debug-find-var=<var>[,...]
@@ -510,7 +509,7 @@ Options
as the result variable, where ``<var>`` is an entry in the given
comma-separated list.
Like :option:`--debug-find <cmake --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 <cmake --trace>`, but with variables expanded.
Like :cmake-option:`--trace`, but with variables expanded.
.. option:: --trace-format=<format>
@@ -669,9 +668,8 @@ Options
.. versionadded:: 3.18
Used in conjunction with
:option:`--profiling-format <cmake --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=<file>
@@ -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 <cmake -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 <cmake -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 ``<type>``. Valid values for
``<type>`` are ``configure``, ``build``, ``test``, ``package``, or ``all``.
If ``<type>`` is omitted, ``configure`` is assumed. The current working
directory must contain CMake preset files unless the :option:`-S <cmake -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 <cmake --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 <cmake --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 <cmake --debugger>` mode
is supported and ``false`` otherwise.
``true`` if the :cmake-option:`--debugger` mode is supported
and ``false`` otherwise.
.. option:: cat [--] <files>...

4
Help/manual/cpack.1.rst
View File

@@ -26,11 +26,11 @@ All supported generators are specified in the :manual:`cpack-generators
<cpack-generators(7)>` 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 <cpack -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 <cmake-language(7)>`. Unless chosen differently
through the command-line option :option:`--config <cpack --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

105
Help/manual/ctest.1.rst
View File

@@ -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 <ctest --no-tests>` 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 <level>
While running tests in parallel (e.g. with :option:`-j <ctest -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 <ctest --output-log>` is
specified. Options such as :option:`--verbose <ctest --verbose>`,
:option:`--extra-verbose <ctest --extra-verbose>`, and
:option:`--debug <ctest --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 <file>, --output-log <file>
@@ -207,16 +206,16 @@ The options for running tests are:
This option tells CTest to write test results to ``<file>`` in JUnit XML
format. If ``<file>`` already exists, it will be overwritten. If using the
:option:`-S <ctest -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[=<format>]
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 <ctest -R>`
and :option:`-E <ctest -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 <regex>, --fixture-exclude-setup <regex>
Same as :option:`-FA <ctest -FA>` except only matching setup tests are
excluded.
Same as :ctest-option:`-FA` except only matching setup tests are excluded.
.. option:: -FC <regex>, --fixture-exclude-cleanup <regex>
Same as :option:`-FA <ctest -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 <ctest -I>` and :option:`-R <ctest -R>`.
Take the Union of :ctest-option:`-I` and :ctest-option:`-R`.
When both :option:`-R <ctest -R>` and :option:`-I <ctest -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 <ctest -L>`, :option:`-R <ctest -R>`, :option:`-E <ctest -E>`,
:option:`-LE <ctest -LE>`, :option:`-I <ctest -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 <ctest -R>` or :option:`-L <ctest -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 <ctest -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 <ctest -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 <ctest -LE>` option works just like :option:`-L <ctest -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 <ctest -L>` will never
include that test, and :option:`-LE <ctest -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 <ctest --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 ``<model>``
can be ``Experimental``, ``Nightly``, and ``Continuous``.
Combining ``-M`` and :option:`-T <ctest -T>` is similar to
:option:`-D <ctest -D>`.
Combining ``-M`` and :ctest-option:`-T` is similar to :ctest-option:`-D`.
.. option:: -T <action>, --test-action <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 <ctest -M>` and ``-T`` is similar to
:option:`-D <ctest -D>`.
Combining :ctest-option:`-M` and ``-T`` is similar to :ctest-option:`-D`.
.. option:: -S <script>, --script <script>
@@ -819,10 +813,10 @@ Options for Dashboard Client include:
Execute a dashboard for a configuration.
This option does the same operations as :option:`-S <ctest -S>` but it
will do them in a separate process. This is primarily useful in cases
where the script may modify the environment and you do not want the modified
environment to impact other :option:`-S <ctest -S>` scripts.
This option does the same operations as :ctest-option:`-S` but it will do
them in a separate process. This is primarily useful in cases where the
script may modify the environment and you do not want the modified
environment to impact other :ctest-option:`-S` scripts.
.. _`Dashboard Options`:
@@ -833,7 +827,7 @@ The available ``<dashboard-options>`` are the following:
Define a variable for script mode.
Pass in variable values on the command line. Use in conjunction
with :option:`-S <ctest -S>` to pass variable values to a dashboard script.
with :ctest-option:`-S` to pass variable values to a dashboard script.
Parsing ``-D`` arguments as variable values is only attempted if the value
following ``-D`` does not match any of the known dashboard types.
@@ -1274,9 +1268,9 @@ Configuration settings include:
``DefaultCTestConfigurationType``
When the build system to be launched allows build-time selection
of the configuration (e.g. ``Debug``, ``Release``), this specifies
the default configuration to be built when no :option:`-C <ctest -C>`
option is given to the :program:`ctest` command. The value will be substituted
into the value of ``MakeCommand`` to replace the literal string
the default configuration to be built when no :ctest-option:`-C`
option is given to the :program:`ctest` command. The value will be
substituted into the value of ``MakeCommand`` to replace the literal string
``${CTEST_CONFIGURATION_TYPE}`` if it appears.
* `CTest Script`_ variable: :variable:`CTEST_CONFIGURATION_TYPE`
@@ -1348,7 +1342,7 @@ Configuration settings include:
See `Label and Subproject Summary`_.
``TestLoad``
While running tests in parallel (e.g. with :option:`-j <ctest -j>`),
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.
@@ -1358,7 +1352,7 @@ Configuration settings include:
``TimeOut``
The default timeout for each test if not specified by the
:prop_test:`TIMEOUT` test property or the
:option:`--timeout <ctest --timeout>` flag.
:ctest-option:`--timeout` flag.
* `CTest Script`_ variable: :variable:`CTEST_TEST_TIMEOUT`
* :module:`CTest` module variable: ``DART_TESTING_TIMEOUT``
@@ -1724,7 +1718,7 @@ model is defined as follows:
Test name. This cannot be empty.
``config``
Optional field specifying the configuration for which the test will run.
This will always match the :option:`-C <ctest -C>` option specified on the
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.
``command``
@@ -1842,11 +1836,10 @@ generated dynamically as part of test execution (see
If a dashboard script is used and ``RESOURCE_SPEC_FILE`` is not specified, the
value of :variable:`CTEST_RESOURCE_SPEC_FILE` in the dashboard script is used
instead. If :option:`--resource-spec-file <ctest --resource-spec-file>`,
``RESOURCE_SPEC_FILE``, and :variable:`CTEST_RESOURCE_SPEC_FILE` in the
dashboard script are not specified, the value of
:variable:`CTEST_RESOURCE_SPEC_FILE` in the CMake build is used instead.
If none of these are specified, no resource spec file is used.
instead. If :ctest-option:`--resource-spec-file`, ``RESOURCE_SPEC_FILE``, and
:variable:`CTEST_RESOURCE_SPEC_FILE` in the dashboard script are not specified,
the value of :variable:`CTEST_RESOURCE_SPEC_FILE` in the CMake build is used
instead. If none of these are specified, no resource spec file is used.
The resource specification file must be a JSON object. All examples in this
document assume the following resource specification file:
@@ -2043,9 +2036,9 @@ Job Server Integration
On POSIX systems, when running under the context of a `Job Server`_,
CTest shares its job slots. This is independent of the :prop_test:`PROCESSORS`
test property, which still counts against CTest's :option:`-j <ctest -j>`
parallel level. CTest acquires exactly one token from the job server before
running each test, and returns it when the test finishes.
test property, which still counts against CTest's :ctest-option:`-j` parallel
level. CTest acquires exactly one token from the job server before running
each test, and returns it when the test finishes.
For example, consider the ``Makefile``:

19
Utilities/Sphinx/cmake.py
View File

@@ -21,6 +21,7 @@ if sphinx.version_info >= (2,):
from sphinx import addnodes
from sphinx.directives import ObjectDescription, nl_escape_re
from sphinx.domains import Domain, ObjType
from sphinx.domains.std import OptionXRefRole
from sphinx.roles import XRefRole
from sphinx.util import logging, ws_re
from sphinx.util.docutils import ReferenceRole
@@ -585,6 +586,16 @@ class CMakeXRefRole(CMakeReferenceRole[XRefRole]):
# pass
class CMakeOptionXRefRole(OptionXRefRole):
def __init__(self, command: str) -> None:
self.command = command
super().__init__()
def __call__(self, typ, rawtext, text, *args, **kwargs):
content = f'{text} <{self.command} {text.split('=')[0]}>'
return super().__call__('std:option', text, content, *args, **kwargs)
class CMakeXRefTransform(Transform):
# Run this transform early since we insert nodes we want
@@ -670,6 +681,7 @@ class CMakeDomain(Domain):
# Other `object_types` cannot be created except by the `CMakeTransform`
}
roles = {
# General CMake reference roles.
'cref': CMakeCRefRole(),
'command': CMakeXRefRole(fix_parens=True, lowercase=True),
'cpack_gen': CMakeXRefRole(),
@@ -689,6 +701,13 @@ class CMakeDomain(Domain):
'prop_test': CMakeXRefRole(),
'prop_tgt': CMakeXRefRole(),
'manual': CMakeXRefRole(),
# Roles for program-specific command-line options without the program
# name (which add the name to form the ref).
'cmake-option': CMakeOptionXRefRole('cmake'),
'cmake-build-option': CMakeOptionXRefRole('cmake--build'),
'cmake-install-option': CMakeOptionXRefRole('cmake--install'),
'cpack-option': CMakeOptionXRefRole('cpack'),
'ctest-option': CMakeOptionXRefRole('ctest'),
}
initial_data = {
'objects': {}, # fullname -> ObjectEntry