dilim/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-07-02 04:38:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

Help: Improve command usage formatting consistency

Browse Source 
Try to be a bit more consistent about:

- Placing angle brackets around text which serves as a placeholder
  rather than being literal.

- Using curly brackets rather than angle brackets to denote groups where
  one of the options is required.

- Describing optional list arguments like `<x>...` rather than
  `[<x>...]`. (Instances of lists not associated with keywords are
  intentionally left as-is, however.)

Also, teach our CMake lexer to understand curly braces used as above
(prior uses were only in parsed literals without syntax highlighting),
and to highlight them (and remaining uses of angle braces) as the type
Punctuation rather than the type Operator, for consistency with square
braces.
This commit is contained in:
Matthew Woehlke
2026-02-13 12:54:37 -05:00
parent 961ed3f2e9
commit 277c12a4c7
25 changed files with 100 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
Help/command/add_custom_command.rst
View File

@@ -14,18 +14,18 @@ The first signature is for adding a custom command to produce an output:
.. code-block:: cmake
add_custom_command(OUTPUT output1 [output2 ...]
COMMAND command1 [ARGS] [args1...]
[COMMAND command2 [ARGS] [args2...] ...]
add_custom_command(OUTPUT <output1> [<output2> ...]
COMMAND <command1> [ARGS] [<args1>...]
[COMMAND <command2> [ARGS] [<args2>...]] ...
[MAIN_DEPENDENCY depend]
[DEPENDS [depends...]]
[BYPRODUCTS [files...]]
[IMPLICIT_DEPENDS <lang1> depend1
[<lang2> depend2] ...]
[WORKING_DIRECTORY dir]
[COMMENT comment]
[DEPFILE depfile]
[JOB_POOL job_pool]
[DEPENDS <depends>...]
[BYPRODUCTS <files>...]
[IMPLICIT_DEPENDS <lang1> <depend1>
[<lang2> <depend2>] ...]
[WORKING_DIRECTORY <dir>]
[COMMENT <comment>]
[DEPFILE <depfile>]
[JOB_POOL <job_pool>]
[JOB_SERVER_AWARE <bool>]
[VERBATIM] [APPEND] [USES_TERMINAL]
[CODEGEN]
@@ -593,11 +593,11 @@ target is already built, the command will not execute.
add_custom_command(TARGET <target>
PRE_BUILD | PRE_LINK | POST_BUILD
COMMAND command1 [ARGS] [args1...]
[COMMAND command2 [ARGS] [args2...] ...]
[BYPRODUCTS [files...]]
[WORKING_DIRECTORY dir]
[COMMENT comment]
COMMAND <command1> [ARGS] [<args1>...]
[COMMAND <command2> [ARGS] [<args2>...]] ...
[BYPRODUCTS <files>...]
[WORKING_DIRECTORY <dir>]
[COMMENT <comment>]
[VERBATIM]
[COMMAND_EXPAND_LISTS]
[USES_TERMINAL])

16
Help/command/add_custom_target.rst
View File

@@ -5,17 +5,17 @@ Add a target with no output so it will always be built.
.. code-block:: cmake
add_custom_target(Name [ALL] [command1 [args1...]]
[COMMAND command2 [args2...] ...]
[DEPENDS depend depend depend ...]
[BYPRODUCTS [files...]]
[WORKING_DIRECTORY dir]
[COMMENT comment]
[JOB_POOL job_pool]
add_custom_target(Name [ALL] [command1 [<args1>...]]
[COMMAND command2 [<args2>...]] ...
[DEPENDS <depend>...]
[BYPRODUCTS <file>...]
[WORKING_DIRECTORY <dir>]
[COMMENT <comment>]
[JOB_POOL <job_pool>]
[JOB_SERVER_AWARE <bool>]
[VERBATIM] [USES_TERMINAL]
[COMMAND_EXPAND_LISTS]
[SOURCES src1 [src2...]])
[SOURCES <source>...])
Adds a target with the given name that executes the given commands.
The target has no output file and is *always considered out of date*

2
Help/command/configure_file.rst
View File

@@ -193,7 +193,7 @@ specify the output directory as an include directory:
.. code-block:: cmake
target_include_directories(<target> [SYSTEM] <INTERFACE|PUBLIC|PRIVATE> "${CMAKE_CURRENT_BINARY_DIR}")
target_include_directories(<target> [SYSTEM] {INTERFACE|PUBLIC|PRIVATE} "${CMAKE_CURRENT_BINARY_DIR}")
so that sources may include the header as ``#include <foo.h>``.

4
Help/command/define_property.rst
View File

@@ -8,8 +8,8 @@ Define and document custom properties.
define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
TEST | VARIABLE | CACHED_VARIABLE>
PROPERTY <name> [INHERITED]
[BRIEF_DOCS <brief-doc> [docs...]]
[FULL_DOCS <full-doc> [docs...]]
[BRIEF_DOCS <brief-doc> [<docs>...]]
[FULL_DOCS <full-doc> [<docs>...]]
[INITIALIZE_FROM_VARIABLE <variable>])
Defines one property in a scope for use with the :command:`set_property` and

2
Help/command/find_file.rst
View File

@@ -2,7 +2,7 @@ find_file
---------
.. |FIND_XXX| replace:: find_file
.. |NAMES| replace:: NAMES name1 [name2 ...]
.. |NAMES| replace:: NAMES <name>...
.. |SEARCH_XXX| replace:: full path to a file
.. |SEARCH_XXX_DESC| replace:: full path to a named file
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include``

2
Help/command/find_library.rst
View File

@@ -2,7 +2,7 @@ find_library
------------
.. |FIND_XXX| replace:: find_library
.. |NAMES| replace:: NAMES name1 [name2 ...] [NAMES_PER_DIR]
.. |NAMES| replace:: NAMES <name>... [NAMES_PER_DIR]
.. |SEARCH_XXX| replace:: library
.. |SEARCH_XXX_DESC| replace:: library
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/lib``

34
Help/command/find_package.rst
View File

@@ -135,10 +135,10 @@ Basic Signature
.. code-block:: cmake
find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
[REQUIRED|OPTIONAL] [[COMPONENTS] [components...]]
[OPTIONAL_COMPONENTS components...]
[REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
find_package(<PackageName> [<version>] [EXACT] [QUIET] [MODULE]
[REQUIRED|OPTIONAL] [[COMPONENTS] <component>...]
[OPTIONAL_COMPONENTS <component>...]
[REGISTRY_VIEW {64|32|64_32|32_64|HOST|TARGET|BOTH}]
[GLOBAL]
[NO_POLICY_SCOPE]
[BYPASS_PROVIDER]
@@ -209,7 +209,7 @@ target package:
.. _FIND_PACKAGE_VERSION_FORMAT:
The ``[version]`` argument requests a version with which the package found
The ``<version>`` argument requests a version with which the package found
should be compatible. There are two possible forms in which it may be
specified:
@@ -234,10 +234,10 @@ specified:
The ``EXACT`` option requests that the version be matched exactly. This option
is incompatible with the specification of a version range.
If no ``[version]`` and/or component list is given to a recursive invocation
If no ``<version>`` and/or component list is given to a recursive invocation
inside a find-module, the corresponding arguments are forwarded
automatically from the outer call (including the ``EXACT`` flag for
``[version]``).
``<version>``).
See the :command:`cmake_policy` command documentation for discussion
of the ``NO_POLICY_SCOPE`` option.
@@ -273,18 +273,18 @@ Full Signature
.. code-block:: cmake
find_package(<PackageName> [version] [EXACT] [QUIET]
[REQUIRED|OPTIONAL] [[COMPONENTS] [components...]]
[OPTIONAL_COMPONENTS components...]
[REQUIRED|OPTIONAL] [[COMPONENTS] <component>...]
[OPTIONAL_COMPONENTS <component>...]
[CONFIG|NO_MODULE]
[GLOBAL]
[NO_POLICY_SCOPE]
[BYPASS_PROVIDER]
[NAMES name1 [name2 ...]]
[CONFIGS config1 [config2 ...]]
[HINTS path1 [path2 ...]]
[PATHS path1 [path2 ...]]
[REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[NAMES <name>...]
[CONFIGS <config>...]
[HINTS <path>...]
[PATHS <path>...]
[REGISTRY_VIEW {64|32|64_32|32_64|HOST|TARGET|BOTH}]
[PATH_SUFFIXES <suffix>...]
[NO_DEFAULT_PATH]
[NO_PACKAGE_ROOT_PATH]
[NO_CMAKE_PATH]
@@ -683,7 +683,7 @@ Config Mode Version Selection
regardless of whether the :ref:`full <full signature>` or
:ref:`basic <basic signature>` signature was given.
When the ``[version]`` argument is given, Config mode will only find a
When the ``<version>`` argument is given, Config mode will only find a
version of the package that claims compatibility with the requested
version (see :ref:`format specification <FIND_PACKAGE_VERSION_FORMAT>`). If
the ``EXACT`` option is given, only a version of the package claiming an exact
@@ -980,7 +980,7 @@ the full requested version string as specified.
In Module mode the loaded find module is responsible to honor the
request detailed by these variables; see the find module for details.
In Config mode ``find_package`` handles ``REQUIRED``, ``QUIET``, and
``[version]`` options automatically but leaves it to the package
``<version>`` options automatically but leaves it to the package
configuration file to handle components in a way that makes sense
for the package. The package configuration file may set
``<PackageName>_FOUND`` to false to tell ``find_package`` that component

2
Help/command/find_path.rst
View File

@@ -2,7 +2,7 @@ find_path
---------
.. |FIND_XXX| replace:: find_path
.. |NAMES| replace:: NAMES name1 [name2 ...]
.. |NAMES| replace:: NAMES <name>...
.. |SEARCH_XXX| replace:: file in a directory
.. |SEARCH_XXX_DESC| replace:: directory containing the named file
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include``

2
Help/command/find_program.rst
View File

@@ -2,7 +2,7 @@ find_program
------------
.. |FIND_XXX| replace:: find_program
.. |NAMES| replace:: NAMES name1 [name2 ...] [NAMES_PER_DIR]
.. |NAMES| replace:: NAMES <name>... [NAMES_PER_DIR]
.. |SEARCH_XXX| replace:: program
.. |SEARCH_XXX_DESC| replace:: program
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/[s]bin``

14
Help/command/include/FIND_XXX.rst
View File

@@ -2,7 +2,7 @@ A short-hand signature is:
.. parsed-literal::
|FIND_XXX| (<VAR> name1 [path1 path2 ...])
|FIND_XXX| (<VAR> <name> [<path>...])
The general signature is:
@@ -10,12 +10,12 @@ The general signature is:
|FIND_XXX| (
<VAR>
name | |NAMES|
[HINTS [path | ENV var]...]
[PATHS [path | ENV var]...]
[REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[VALIDATOR function]
{<name> | |NAMES|}
[HINTS {<path> | ENV <var>}...]
[PATHS {<path> | ENV <var>}...]
[REGISTRY_VIEW {64|32|64_32|32_64|HOST|TARGET|BOTH}]
[PATH_SUFFIXES <suffix>...]
[VALIDATOR <function>]
[DOC "cache documentation string"]
[NO_CACHE]
[REQUIRED|OPTIONAL]

2
Help/command/include/FIND_XXX_ORDER.rst
View File

@@ -5,7 +5,7 @@ multiple times and using the ``NO_*`` options:
.. parsed-literal::
|FIND_XXX| (|FIND_ARGS_XXX| PATHS paths... NO_DEFAULT_PATH)
|FIND_XXX| (|FIND_ARGS_XXX| PATHS <paths>... NO_DEFAULT_PATH)
|FIND_XXX| (|FIND_ARGS_XXX|)
Once one of the calls succeeds the result variable will be set

2
Help/command/install.rst
View File

@@ -551,7 +551,7 @@ Signatures
programs that are not targets, such as shell scripts. Use the ``TARGETS``
form to install targets built within the project.
The list of ``files...`` given to ``FILES`` or ``PROGRAMS`` may use
The list of files given to ``FILES`` or ``PROGRAMS`` may use
"generator expressions" with the syntax ``$<...>``. See the
:manual:`cmake-generator-expressions(7)` manual for available expressions.
However, if any item begins in a generator expression it must evaluate

22
Help/command/set_property.rst
View File

@@ -5,19 +5,19 @@ Set a named property in a given scope.
.. code-block:: cmake
set_property(<GLOBAL |
DIRECTORY [<dir>] |
TARGET [<target1> ...] |
FILE_SET [<file_set> ...] TARGET <target> |
SOURCE [<src1> ...]
set_property({GLOBAL |
DIRECTORY [<dir>] |
TARGET <target>... |
FILE_SET <file_set>... TARGET <target> |
SOURCE <source>...
[DIRECTORY <dirs> ...]
[TARGET_DIRECTORY <targets> ...] |
INSTALL [<file1> ...] |
TEST [<test1> ...]
[DIRECTORY <dir>] |
CACHE [<entry1> ...]>
[TARGET_DIRECTORY <targets>...] |
INSTALL <file>... |
TEST <test>...
[DIRECTORY <dir>] |
CACHE <entry>...}
[APPEND] [APPEND_STRING]
PROPERTY <name> [<value1> ...])
PROPERTY <name> [<value>...])
Sets one property on zero or more objects of a scope.

4
Help/command/target_compile_definitions.rst
View File

@@ -6,8 +6,8 @@ Add compile definitions to a target.
.. code-block:: cmake
target_compile_definitions(<target>
<INTERFACE|PUBLIC|PRIVATE> [items1...]
[<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
<INTERFACE|PUBLIC|PRIVATE> <definition>...
[<INTERFACE|PUBLIC|PRIVATE> <definition>... ...])
Specifies compile definitions to use when compiling a given ``<target>``. The
named ``<target>`` must have been created by a command such as

4
Help/command/target_compile_features.rst
View File

@@ -7,7 +7,9 @@ Add expected compiler features to a target.
.. code-block:: cmake
target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])
target_compile_features(<target>
{INTERFACE|PUBLIC|PRIVATE} <feature>...
[{INTERFACE|PUBLIC|PRIVATE} <feature>...]...)
Specifies compiler features required when compiling a given target. If the
feature is not listed in the :variable:`CMAKE_C_COMPILE_FEATURES`,

4
Help/command/target_compile_options.rst
View File

@@ -6,8 +6,8 @@ Add compile options to a target.
.. code-block:: cmake
target_compile_options(<target> [BEFORE]
<INTERFACE|PUBLIC|PRIVATE> [items1...]
[<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
{INTERFACE|PUBLIC|PRIVATE} <item>...
[{INTERFACE|PUBLIC|PRIVATE} <item>...]...)
Adds options to the :prop_tgt:`COMPILE_OPTIONS` or
:prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties. These options

4
Help/command/target_include_directories.rst
View File

@@ -6,8 +6,8 @@ Add include directories to a target.
.. code-block:: cmake
target_include_directories(<target> [SYSTEM] [AFTER|BEFORE]
<INTERFACE|PUBLIC|PRIVATE> [items1...]
[<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
{INTERFACE|PUBLIC|PRIVATE} <dir...
[{INTERFACE|PUBLIC|PRIVATE} <dir>...]...)
Specifies include directories to use when compiling a given target.
The named ``<target>`` must have been created by a command such

4
Help/command/target_link_directories.rst
View File

@@ -8,8 +8,8 @@ Add link directories to a target.
.. code-block:: cmake
target_link_directories(<target> [BEFORE]
<INTERFACE|PUBLIC|PRIVATE> [items1...]
[<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
{INTERFACE|PUBLIC|PRIVATE} <dir>...
[{INTERFACE|PUBLIC|PRIVATE} <dir>...]...)
Specifies the paths in which the linker should search for libraries when
linking a given target. Each item can be an absolute or relative path,

4
Help/command/target_link_libraries.rst
View File

@@ -158,8 +158,8 @@ Libraries for a Target and/or its Dependents
.. code-block:: cmake
target_link_libraries(<target>
<PRIVATE|PUBLIC|INTERFACE> <item>...
[<PRIVATE|PUBLIC|INTERFACE> <item>...]...)
{INTERFACE|PUBLIC|PRIVATE} <item>...
[{INTERFACE|PUBLIC|PRIVATE} <item>...]...)
The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE``
:ref:`scope <Target Command Scope>` keywords can be used to

4
Help/command/target_link_options.rst
View File

@@ -9,8 +9,8 @@ library target.
.. code-block:: cmake
target_link_options(<target> [BEFORE]
<INTERFACE|PUBLIC|PRIVATE> [items1...]
[<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
{INTERFACE|PUBLIC|PRIVATE} <item>...
[{INTERFACE|PUBLIC|PRIVATE} <item>...]...)
The named ``<target>`` must have been created by a command such as
:command:`add_executable` or :command:`add_library` and must not be an

4
Help/command/target_precompile_headers.rst
View File

@@ -15,8 +15,8 @@ Main Form
.. code-block:: cmake
target_precompile_headers(<target>
<INTERFACE|PUBLIC|PRIVATE> [header1...]
[<INTERFACE|PUBLIC|PRIVATE> [header2...] ...])
{INTERFACE|PUBLIC|PRIVATE} <header>...
[{INTERFACE|PUBLIC|PRIVATE} <header>...]...)
The command adds header files to the :prop_tgt:`PRECOMPILE_HEADERS` and/or
:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` target properties of ``<target>``.

6
Help/command/target_sources.rst
View File

@@ -8,8 +8,8 @@ Add sources to a target.
.. code-block:: cmake
target_sources(<target>
<INTERFACE|PUBLIC|PRIVATE> [items1...]
[<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
{INTERFACE|PUBLIC|PRIVATE} <source>...
[{INTERFACE|PUBLIC|PRIVATE} <source>...]...)
Specifies sources to use when building a target and/or its dependents.
The named ``<target>`` must have been created by a command such as
@@ -70,7 +70,7 @@ File Sets
.. code-block:: cmake
target_sources(<target>
[<INTERFACE|PUBLIC|PRIVATE>
[{INTERFACE|PUBLIC|PRIVATE}
[FILE_SET <set> [TYPE <type>] [BASE_DIRS <dirs>...] [FILES <files>...]]...
]...)

6
Help/command/try_compile.rst
View File

@@ -71,10 +71,10 @@ Try Compiling Source Files
try_compile(<compileResultVar>
[SOURCES_TYPE <type>]
<SOURCES <srcfile...> |
{SOURCES <srcfile>... |
SOURCE_FROM_CONTENT <name> <content> |
SOURCE_FROM_VAR <name> <var> |
SOURCE_FROM_FILE <name> <path> >...
SOURCE_FROM_FILE <name> <path> }...
[LOG_DESCRIPTION <text>]
[NO_CACHE]
[NO_LOG]
@@ -130,7 +130,7 @@ The signature above is recommended for clarity.
.. code-block:: cmake
try_compile(<compileResultVar> <bindir> <srcfile|SOURCES srcfile...>
try_compile(<compileResultVar> <bindir> {<srcfile>|SOURCES <srcfile>...}
[CMAKE_FLAGS <flags>...]
[COMPILE_DEFINITIONS <defs>...]
[LINK_OPTIONS <options>...]

6
Help/command/try_run.rst
View File

@@ -14,10 +14,10 @@ Try Compiling and Running Source Files
try_run(<runResultVar> <compileResultVar>
[SOURCES_TYPE <type>]
<SOURCES <srcfile...> |
{SOURCES <srcfile>... |
SOURCE_FROM_CONTENT <name> <content> |
SOURCE_FROM_VAR <name> <var> |
SOURCE_FROM_FILE <name> <path> >...
SOURCE_FROM_FILE <name> <path> }...
[LOG_DESCRIPTION <text>]
[NO_CACHE]
[NO_LOG]
@@ -63,7 +63,7 @@ The signature above is recommended for clarity.
.. code-block:: cmake
try_run(<runResultVar> <compileResultVar>
<bindir> <srcfile|SOURCES srcfile...>
<bindir> {<srcfile>|SOURCES <srcfile>...}
[CMAKE_FLAGS <flags>...]
[COMPILE_DEFINITIONS <defs>...]
[LINK_OPTIONS <options>...]

8
Utilities/Sphinx/cmake.py
View File

@@ -101,8 +101,12 @@ CMakeLexer.tokens["root"] = [
(r'(?s)"(\\"|[^"])*"', String),
(r'\.\.\.', Name.Variable),
# <..|..> is different from <expr>
(r'<', Operator, '#push'),
(r'>', Operator, '#pop'),
# TODO: <..|..> should be {..|..}; remove when all instances are converted?
(r'<', Punctuation, '#push'),
(r'>', Punctuation, '#pop'),
# {..|..}
(r'\{', Punctuation, '#push'),
(r'\}', Punctuation, '#pop'),
(r'\n', Whitespace),
(r'[ \t]+', Whitespace),
(r'#.*\n', Comment),