diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index 8d66752274..9bd4d723df 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -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 [ ...] + COMMAND [ARGS] [...] + [COMMAND [ARGS] [...]] ... [MAIN_DEPENDENCY depend] - [DEPENDS [depends...]] - [BYPRODUCTS [files...]] - [IMPLICIT_DEPENDS depend1 - [ depend2] ...] - [WORKING_DIRECTORY dir] - [COMMENT comment] - [DEPFILE depfile] - [JOB_POOL job_pool] + [DEPENDS ...] + [BYPRODUCTS ...] + [IMPLICIT_DEPENDS + [ ] ...] + [WORKING_DIRECTORY ] + [COMMENT ] + [DEPFILE ] + [JOB_POOL ] [JOB_SERVER_AWARE ] [VERBATIM] [APPEND] [USES_TERMINAL] [CODEGEN] @@ -593,11 +593,11 @@ target is already built, the command will not execute. add_custom_command(TARGET PRE_BUILD | PRE_LINK | POST_BUILD - COMMAND command1 [ARGS] [args1...] - [COMMAND command2 [ARGS] [args2...] ...] - [BYPRODUCTS [files...]] - [WORKING_DIRECTORY dir] - [COMMENT comment] + COMMAND [ARGS] [...] + [COMMAND [ARGS] [...]] ... + [BYPRODUCTS ...] + [WORKING_DIRECTORY ] + [COMMENT ] [VERBATIM] [COMMAND_EXPAND_LISTS] [USES_TERMINAL]) diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst index 83fe6b49a8..fd38729fd4 100644 --- a/Help/command/add_custom_target.rst +++ b/Help/command/add_custom_target.rst @@ -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 [...]] + [COMMAND command2 [...]] ... + [DEPENDS ...] + [BYPRODUCTS ...] + [WORKING_DIRECTORY ] + [COMMENT ] + [JOB_POOL ] [JOB_SERVER_AWARE ] [VERBATIM] [USES_TERMINAL] [COMMAND_EXPAND_LISTS] - [SOURCES src1 [src2...]]) + [SOURCES ...]) 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* diff --git a/Help/command/configure_file.rst b/Help/command/configure_file.rst index 546f9cee69..956400c40c 100644 --- a/Help/command/configure_file.rst +++ b/Help/command/configure_file.rst @@ -193,7 +193,7 @@ specify the output directory as an include directory: .. code-block:: cmake - target_include_directories( [SYSTEM] "${CMAKE_CURRENT_BINARY_DIR}") + target_include_directories( [SYSTEM] {INTERFACE|PUBLIC|PRIVATE} "${CMAKE_CURRENT_BINARY_DIR}") so that sources may include the header as ``#include ``. diff --git a/Help/command/define_property.rst b/Help/command/define_property.rst index 3dccca9544..8952f1f76d 100644 --- a/Help/command/define_property.rst +++ b/Help/command/define_property.rst @@ -8,8 +8,8 @@ Define and document custom properties. define_property( PROPERTY [INHERITED] - [BRIEF_DOCS [docs...]] - [FULL_DOCS [docs...]] + [BRIEF_DOCS [...]] + [FULL_DOCS [...]] [INITIALIZE_FROM_VARIABLE ]) Defines one property in a scope for use with the :command:`set_property` and diff --git a/Help/command/find_file.rst b/Help/command/find_file.rst index a1dc5f9d46..13aae97924 100644 --- a/Help/command/find_file.rst +++ b/Help/command/find_file.rst @@ -2,7 +2,7 @@ find_file --------- .. |FIND_XXX| replace:: find_file -.. |NAMES| replace:: NAMES name1 [name2 ...] +.. |NAMES| replace:: NAMES ... .. |SEARCH_XXX| replace:: full path to a file .. |SEARCH_XXX_DESC| replace:: full path to a named file .. |prefix_XXX_SUBDIR| replace:: ``/include`` diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst index b150818a89..54f7a8e4cd 100644 --- a/Help/command/find_library.rst +++ b/Help/command/find_library.rst @@ -2,7 +2,7 @@ find_library ------------ .. |FIND_XXX| replace:: find_library -.. |NAMES| replace:: NAMES name1 [name2 ...] [NAMES_PER_DIR] +.. |NAMES| replace:: NAMES ... [NAMES_PER_DIR] .. |SEARCH_XXX| replace:: library .. |SEARCH_XXX_DESC| replace:: library .. |prefix_XXX_SUBDIR| replace:: ``/lib`` diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 2665534c10..24324340b2 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -137,10 +137,10 @@ Basic Signature .. code-block:: cmake - find_package( [version] [EXACT] [QUIET] [MODULE] - [REQUIRED|OPTIONAL] [[COMPONENTS] [components...]] - [OPTIONAL_COMPONENTS components...] - [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)] + find_package( [] [EXACT] [QUIET] [MODULE] + [REQUIRED|OPTIONAL] [[COMPONENTS] ...] + [OPTIONAL_COMPONENTS ...] + [REGISTRY_VIEW {64|32|64_32|32_64|HOST|TARGET|BOTH}] [GLOBAL] [NO_POLICY_SCOPE] [BYPASS_PROVIDER] @@ -211,7 +211,7 @@ target package: .. _FIND_PACKAGE_VERSION_FORMAT: -The ``[version]`` argument requests a version with which the package found +The ```` argument requests a version with which the package found should be compatible. There are two possible forms in which it may be specified: @@ -236,10 +236,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 ```` 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]``). +````). See the :command:`cmake_policy` command documentation for discussion of the ``NO_POLICY_SCOPE`` option. @@ -275,18 +275,18 @@ Full Signature .. code-block:: cmake find_package( [version] [EXACT] [QUIET] - [REQUIRED|OPTIONAL] [[COMPONENTS] [components...]] - [OPTIONAL_COMPONENTS components...] + [REQUIRED|OPTIONAL] [[COMPONENTS] ...] + [OPTIONAL_COMPONENTS ...] [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 ...] + [CONFIGS ...] + [HINTS ...] + [PATHS ...] + [REGISTRY_VIEW {64|32|64_32|32_64|HOST|TARGET|BOTH}] + [PATH_SUFFIXES ...] [NO_DEFAULT_PATH] [NO_PACKAGE_ROOT_PATH] [NO_CMAKE_PATH] @@ -690,7 +690,7 @@ Config Mode Version Selection regardless of whether the :ref:`full ` or :ref:`basic ` signature was given. -When the ``[version]`` argument is given, Config mode will only find a +When the ```` argument is given, Config mode will only find a version of the package that claims compatibility with the requested version (see :ref:`format specification `). If the ``EXACT`` option is given, only a version of the package claiming an exact @@ -987,7 +987,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 +```` 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 ``_FOUND`` to false to tell ``find_package`` that component diff --git a/Help/command/find_path.rst b/Help/command/find_path.rst index ab44e32185..7ac9024c52 100644 --- a/Help/command/find_path.rst +++ b/Help/command/find_path.rst @@ -2,7 +2,7 @@ find_path --------- .. |FIND_XXX| replace:: find_path -.. |NAMES| replace:: NAMES name1 [name2 ...] +.. |NAMES| replace:: NAMES ... .. |SEARCH_XXX| replace:: file in a directory .. |SEARCH_XXX_DESC| replace:: directory containing the named file .. |prefix_XXX_SUBDIR| replace:: ``/include`` diff --git a/Help/command/find_program.rst b/Help/command/find_program.rst index bde5289315..e314f9e2d2 100644 --- a/Help/command/find_program.rst +++ b/Help/command/find_program.rst @@ -2,7 +2,7 @@ find_program ------------ .. |FIND_XXX| replace:: find_program -.. |NAMES| replace:: NAMES name1 [name2 ...] [NAMES_PER_DIR] +.. |NAMES| replace:: NAMES ... [NAMES_PER_DIR] .. |SEARCH_XXX| replace:: program .. |SEARCH_XXX_DESC| replace:: program .. |prefix_XXX_SUBDIR| replace:: ``/[s]bin`` diff --git a/Help/command/include/FIND_XXX.rst b/Help/command/include/FIND_XXX.rst index 194b6f8e41..ce3ed641b7 100644 --- a/Help/command/include/FIND_XXX.rst +++ b/Help/command/include/FIND_XXX.rst @@ -2,7 +2,7 @@ A short-hand signature is: .. parsed-literal:: - |FIND_XXX| ( name1 [path1 path2 ...]) + |FIND_XXX| ( [...]) The general signature is: @@ -10,12 +10,12 @@ The general signature is: |FIND_XXX| ( - 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] + { | |NAMES|} + [HINTS { | ENV }...] + [PATHS { | ENV }...] + [REGISTRY_VIEW {64|32|64_32|32_64|HOST|TARGET|BOTH}] + [PATH_SUFFIXES ...] + [VALIDATOR ] [DOC "cache documentation string"] [NO_CACHE] [REQUIRED|OPTIONAL] diff --git a/Help/command/include/FIND_XXX_ORDER.rst b/Help/command/include/FIND_XXX_ORDER.rst index bac2419645..6dfae5497a 100644 --- a/Help/command/include/FIND_XXX_ORDER.rst +++ b/Help/command/include/FIND_XXX_ORDER.rst @@ -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 ... NO_DEFAULT_PATH) |FIND_XXX| (|FIND_ARGS_XXX|) Once one of the calls succeeds the result variable will be set diff --git a/Help/command/install.rst b/Help/command/install.rst index 2668fb8585..68fda6c027 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -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 diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst index e28edf24a7..e560f1843a 100644 --- a/Help/command/set_property.rst +++ b/Help/command/set_property.rst @@ -5,19 +5,19 @@ Set a named property in a given scope. .. code-block:: cmake - set_property(] | - TARGET [ ...] | - FILE_SET [ ...] TARGET | - SOURCE [ ...] + set_property({GLOBAL | + DIRECTORY [] | + TARGET ... | + FILE_SET ... TARGET | + SOURCE ... [DIRECTORY ...] - [TARGET_DIRECTORY ...] | - INSTALL [ ...] | - TEST [ ...] - [DIRECTORY ] | - CACHE [ ...]> + [TARGET_DIRECTORY ...] | + INSTALL ... | + TEST ... + [DIRECTORY ] | + CACHE ...} [APPEND] [APPEND_STRING] - PROPERTY [ ...]) + PROPERTY [...]) Sets one property on zero or more objects of a scope. diff --git a/Help/command/target_compile_definitions.rst b/Help/command/target_compile_definitions.rst index 61cfb1982b..cb2629ee65 100644 --- a/Help/command/target_compile_definitions.rst +++ b/Help/command/target_compile_definitions.rst @@ -6,8 +6,8 @@ Add compile definitions to a target. .. code-block:: cmake target_compile_definitions( - [items1...] - [ [items2...] ...]) + ... + [ ... ...]) Specifies compile definitions to use when compiling a given ````. The named ```` must have been created by a command such as diff --git a/Help/command/target_compile_features.rst b/Help/command/target_compile_features.rst index 2d569e96c3..f63a56c06f 100644 --- a/Help/command/target_compile_features.rst +++ b/Help/command/target_compile_features.rst @@ -7,7 +7,9 @@ Add expected compiler features to a target. .. code-block:: cmake - target_compile_features( [...]) + target_compile_features( + {INTERFACE|PUBLIC|PRIVATE} ... + [{INTERFACE|PUBLIC|PRIVATE} ...]...) Specifies compiler features required when compiling a given target. If the feature is not listed in the :variable:`CMAKE_C_COMPILE_FEATURES`, diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst index 6fb86cd569..a16e55b460 100644 --- a/Help/command/target_compile_options.rst +++ b/Help/command/target_compile_options.rst @@ -6,8 +6,8 @@ Add compile options to a target. .. code-block:: cmake target_compile_options( [BEFORE] - [items1...] - [ [items2...] ...]) + {INTERFACE|PUBLIC|PRIVATE} ... + [{INTERFACE|PUBLIC|PRIVATE} ...]...) Adds options to the :prop_tgt:`COMPILE_OPTIONS` or :prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties. These options diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst index 38bf581a2e..59d0cd5350 100644 --- a/Help/command/target_include_directories.rst +++ b/Help/command/target_include_directories.rst @@ -6,8 +6,8 @@ Add include directories to a target. .. code-block:: cmake target_include_directories( [SYSTEM] [AFTER|BEFORE] - [items1...] - [ [items2...] ...]) + {INTERFACE|PUBLIC|PRIVATE} ...]...) Specifies include directories to use when compiling a given target. The named ```` must have been created by a command such diff --git a/Help/command/target_link_directories.rst b/Help/command/target_link_directories.rst index af7a5065c0..91c1feb6cf 100644 --- a/Help/command/target_link_directories.rst +++ b/Help/command/target_link_directories.rst @@ -8,8 +8,8 @@ Add link directories to a target. .. code-block:: cmake target_link_directories( [BEFORE] - [items1...] - [ [items2...] ...]) + {INTERFACE|PUBLIC|PRIVATE} ... + [{INTERFACE|PUBLIC|PRIVATE} ...]...) 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, diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index a8ba92ca48..4d964f4b00 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -158,8 +158,8 @@ Libraries for a Target and/or its Dependents .. code-block:: cmake target_link_libraries( - ... - [ ...]...) + {INTERFACE|PUBLIC|PRIVATE} ... + [{INTERFACE|PUBLIC|PRIVATE} ...]...) The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` :ref:`scope ` keywords can be used to diff --git a/Help/command/target_link_options.rst b/Help/command/target_link_options.rst index cbbd7201fb..10c8cf923f 100644 --- a/Help/command/target_link_options.rst +++ b/Help/command/target_link_options.rst @@ -9,8 +9,8 @@ library target. .. code-block:: cmake target_link_options( [BEFORE] - [items1...] - [ [items2...] ...]) + {INTERFACE|PUBLIC|PRIVATE} ... + [{INTERFACE|PUBLIC|PRIVATE} ...]...) The named ```` must have been created by a command such as :command:`add_executable` or :command:`add_library` and must not be an diff --git a/Help/command/target_precompile_headers.rst b/Help/command/target_precompile_headers.rst index acd83a8a8c..7089582f4a 100644 --- a/Help/command/target_precompile_headers.rst +++ b/Help/command/target_precompile_headers.rst @@ -15,8 +15,8 @@ Main Form .. code-block:: cmake target_precompile_headers( - [header1...] - [ [header2...] ...]) + {INTERFACE|PUBLIC|PRIVATE}
... + [{INTERFACE|PUBLIC|PRIVATE}
...]...) The command adds header files to the :prop_tgt:`PRECOMPILE_HEADERS` and/or :prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` target properties of ````. diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst index 0d31f8ccbe..5fa4ef1988 100644 --- a/Help/command/target_sources.rst +++ b/Help/command/target_sources.rst @@ -8,8 +8,8 @@ Add sources to a target. .. code-block:: cmake target_sources( - [items1...] - [ [items2...] ...]) + {INTERFACE|PUBLIC|PRIVATE} ... + [{INTERFACE|PUBLIC|PRIVATE} ...]...) Specifies sources to use when building a target and/or its dependents. The named ```` must have been created by a command such as @@ -70,7 +70,7 @@ File Sets .. code-block:: cmake target_sources( - [ + [{INTERFACE|PUBLIC|PRIVATE} [FILE_SET [TYPE ] [BASE_DIRS ...] [FILES ...]]... ]...) diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index a2f7cef261..dc6ec44f90 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -71,10 +71,10 @@ Try Compiling Source Files try_compile( [SOURCES_TYPE ] - | + {SOURCES ... | SOURCE_FROM_CONTENT | SOURCE_FROM_VAR | - SOURCE_FROM_FILE >... + SOURCE_FROM_FILE }... [LOG_DESCRIPTION ] [NO_CACHE] [NO_LOG] @@ -130,7 +130,7 @@ The signature above is recommended for clarity. .. code-block:: cmake - try_compile( + try_compile( {|SOURCES ...} [CMAKE_FLAGS ...] [COMPILE_DEFINITIONS ...] [LINK_OPTIONS ...] diff --git a/Help/command/try_run.rst b/Help/command/try_run.rst index 7973e1b69b..2cae17bbe0 100644 --- a/Help/command/try_run.rst +++ b/Help/command/try_run.rst @@ -14,10 +14,10 @@ Try Compiling and Running Source Files try_run( [SOURCES_TYPE ] - | + {SOURCES ... | SOURCE_FROM_CONTENT | SOURCE_FROM_VAR | - SOURCE_FROM_FILE >... + SOURCE_FROM_FILE }... [LOG_DESCRIPTION ] [NO_CACHE] [NO_LOG] @@ -63,7 +63,7 @@ The signature above is recommended for clarity. .. code-block:: cmake try_run( - + {|SOURCES ...} [CMAKE_FLAGS ...] [COMPILE_DEFINITIONS ...] [LINK_OPTIONS ...] diff --git a/Utilities/Sphinx/cmake.py b/Utilities/Sphinx/cmake.py index cfe114a355..fc59742efd 100644 --- a/Utilities/Sphinx/cmake.py +++ b/Utilities/Sphinx/cmake.py @@ -101,8 +101,12 @@ CMakeLexer.tokens["root"] = [ (r'(?s)"(\\"|[^"])*"', String), (r'\.\.\.', Name.Variable), # <..|..> is different from - (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),