diff options
29 files changed, 248 insertions, 198 deletions
diff --git a/Help/command/cmake_language.rst b/Help/command/cmake_language.rst index 377e42d5f8..d0c7c1960b 100644 --- a/Help/command/cmake_language.rst +++ b/Help/command/cmake_language.rst @@ -510,7 +510,8 @@ into the given ``<output_variable>``. See :command:`message` for the possible logging levels. -The current message logging level can be set either using the ``--log-level`` +The current message logging level can be set either using the +:option:`--log-level <cmake --log-level>` command line option of the :manual:`cmake(1)` program or using the :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable. diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst index 11ebdbd3d9..f058150739 100644 --- a/Help/command/ctest_test.rst +++ b/Help/command/ctest_test.rst @@ -109,8 +109,9 @@ The options are: While running tests in parallel, try not to start tests when they may cause the CPU load to pass above a given threshold. If not specified the :variable:`CTEST_TEST_LOAD` variable will be checked, - and then the ``--test-load`` command-line argument to :manual:`ctest(1)`. - See also the ``TestLoad`` setting in the :ref:`CTest Test Step`. + and then the :option:`--test-load <ctest --test-load>` command-line + argument to :manual:`ctest(1)`. See also the ``TestLoad`` setting + in the :ref:`CTest Test Step`. ``REPEAT <mode>:<n>`` .. versionadded:: 3.17 diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index ee52c4189c..e1759bf415 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -368,7 +368,7 @@ enabled. See policy :policy:`CMP0074`. 2. Search paths specified in cmake-specific cache variables. These - are intended to be used on the command line with a ``-DVAR=value``. + are intended to be used on the command line with a :option:`-DVAR=VALUE <cmake -D>`. The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`. This can be skipped if ``NO_CMAKE_PATH`` is passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``: diff --git a/Help/command/get_test_property.rst b/Help/command/get_test_property.rst index e02b9bc770..6bcc1ef2ad 100644 --- a/Help/command/get_test_property.rst +++ b/Help/command/get_test_property.rst @@ -16,6 +16,7 @@ relevant parent scope as described for the :command:`define_property` command and if still unable to find the property, ``VAR`` will be set to an empty string. -For a list of standard properties you can type ``cmake --help-property-list``. +For a list of standard properties you can type +:option:`cmake --help-property-list`. See also the more general :command:`get_property` command. diff --git a/Help/command/install.rst b/Help/command/install.rst index 5aa3a4be9d..e2aeaadd6e 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -963,12 +963,12 @@ Generated Installation Script .. note:: Use of this feature is not recommended. Please consider using the - ``--install`` argument of :manual:`cmake(1)` instead. + :option:`cmake --install` instead. The ``install()`` command generates a file, ``cmake_install.cmake``, inside the build directory, which is used internally by the generated install target -and by CPack. You can also invoke this script manually with ``cmake -P``. This -script accepts several variables: +and by CPack. You can also invoke this script manually with +:option:`cmake -P <cmake_P -P>`. This script accepts several variables: ``COMPONENT`` Set this variable to install only a single CPack component as opposed to all diff --git a/Help/command/message.rst b/Help/command/message.rst index ca4f5c1faa..77d21c83c5 100644 --- a/Help/command/message.rst +++ b/Help/command/message.rst @@ -83,8 +83,9 @@ are sent to stderr and are not prefixed with hyphens. The :manual:`CMake GUI <cmake-gui(1)>` displays all messages in its log area. The :manual:`curses interface <ccmake(1)>` shows ``STATUS`` to ``TRACE`` messages one at a time on a status line and other messages in an -interactive pop-up box. The ``--log-level`` command-line option to each of -these tools can be used to control which messages will be shown. +interactive pop-up box. The :option:`--log-level <cmake --log-level>` +command-line option to each of these tools can be used to control which +messages will be shown. .. versionadded:: 3.17 To make a log level persist between CMake runs, the @@ -104,7 +105,7 @@ these tools can be used to control which messages will be shown. list variable to a dot-separated string. The message context will always appear before any indenting content but after any automatically added leading hyphens. By default, message context is not shown, it has to be explicitly - enabled by giving the :manual:`cmake <cmake(1)>` ``--log-context`` + enabled by giving the :option:`cmake --log-context` command-line option or by setting the :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` variable to true. See the :variable:`CMAKE_MESSAGE_CONTEXT` documentation for usage examples. diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index 806a98d4b2..e03ab80fb0 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -79,8 +79,8 @@ contain something like the following: The options are: ``CMAKE_FLAGS <flags>...`` - Specify flags of the form ``-DVAR:TYPE=VALUE`` to be passed to - the ``cmake`` command-line used to drive the test build. + Specify flags of the form :option:`-DVAR:TYPE=VALUE <cmake -D>` to be passed + to the :manual:`cmake(1)` command-line used to drive the test build. The above example shows how values for variables ``INCLUDE_DIRECTORIES``, ``LINK_DIRECTORIES``, and ``LINK_LIBRARIES`` are used. @@ -137,15 +137,16 @@ The options are: or :prop_tgt:`CUDA_EXTENSIONS` target property of the generated project. In this version all files in ``<bindir>/CMakeFiles/CMakeTmp`` will be -cleaned automatically. For debugging, ``--debug-trycompile`` can be +cleaned automatically. For debugging, +:option:`--debug-trycompile <cmake --debug-trycompile>` can be passed to ``cmake`` to avoid this clean. However, multiple sequential ``try_compile`` operations reuse this single output directory. If you use -``--debug-trycompile``, you can only debug one ``try_compile`` call at a time. -The recommended procedure is to protect all ``try_compile`` calls in your -project by ``if(NOT DEFINED <resultVar>)`` logic, configure with cmake -all the way through once, then delete the cache entry associated with -the try_compile call of interest, and then re-run cmake again with -``--debug-trycompile``. +:option:`--debug-trycompile <cmake --debug-trycompile>`, you can only debug +one ``try_compile`` call at a time. The recommended procedure is to protect +all ``try_compile`` calls in your project by ``if(NOT DEFINED <resultVar>)`` +logic, configure with cmake all the way through once, then delete the cache +entry associated with the try_compile call of interest, and then re-run cmake +again with :option:`--debug-trycompile <cmake --debug-trycompile>`. Other Behavior Settings ^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/command/try_run.rst b/Help/command/try_run.rst index 125b0acb32..938869bb9c 100644 --- a/Help/command/try_run.rst +++ b/Help/command/try_run.rst @@ -35,8 +35,8 @@ information on how the test project is constructed to build the source file. The options are: ``CMAKE_FLAGS <flags>...`` - Specify flags of the form ``-DVAR:TYPE=VALUE`` to be passed to - the ``cmake`` command-line used to drive the test build. + Specify flags of the form :option:`-DVAR:TYPE=VALUE <cmake -D>` to be passed + to the :manual:`cmake(1)` command-line used to drive the test build. The example in :command:`try_compile` shows how values for variables ``INCLUDE_DIRECTORIES``, ``LINK_DIRECTORIES``, and ``LINK_LIBRARIES`` are used. diff --git a/Help/envvar/CTEST_PROGRESS_OUTPUT.rst b/Help/envvar/CTEST_PROGRESS_OUTPUT.rst index 8c29d7d16d..348acc6899 100644 --- a/Help/envvar/CTEST_PROGRESS_OUTPUT.rst +++ b/Help/envvar/CTEST_PROGRESS_OUTPUT.rst @@ -14,5 +14,5 @@ variable is not set or has a value that evaluates to false, output is reported normally with each test having its own start and end lines logged to the output. -The ``--progress`` option to :manual:`ctest <ctest(1)>` overrides this -environment variable if both are given. +The :option:`--progress <ctest --progress>` option to :manual:`ctest <ctest(1)>` +overrides this environment variable if both are given. diff --git a/Help/envvar/DESTDIR.rst b/Help/envvar/DESTDIR.rst index 94cae4a819..414db12d95 100644 --- a/Help/envvar/DESTDIR.rst +++ b/Help/envvar/DESTDIR.rst @@ -20,8 +20,9 @@ The packaging tool may then construct the package from the content of the See the :variable:`CMAKE_INSTALL_PREFIX` variable to control the installation prefix when configuring a build tree. Or, when using -the :manual:`cmake(1)` command-line tool's ``--install`` mode, -one may specify a different prefix using the ``--prefix`` option. +the :manual:`cmake(1)` command-line tool's :option:`--install <cmake --install>` +mode, one may specify a different prefix using the +:option:`--prefix <cmake --prefix>` option. .. note:: diff --git a/Help/generator/Ninja Multi-Config.rst b/Help/generator/Ninja Multi-Config.rst index e5ce4f5cd4..ae075ed5a4 100644 --- a/Help/generator/Ninja Multi-Config.rst +++ b/Help/generator/Ninja Multi-Config.rst @@ -20,8 +20,8 @@ are intended to be run with ``ninja -f build-<Config>.ninja``. A :variable:`CMAKE_CONFIGURATION_TYPES`. ``cmake --build . --config <Config>`` will always use ``build-<Config>.ninja`` -to build. If no ``--config`` argument is specified, ``cmake --build .`` will -use ``build.ninja``. +to build. If no :option:`--config <cmake --config>` argument is specified, +:option:`cmake --build .<cmake --build>` will use ``build.ninja``. Each ``build-<Config>.ninja`` file contains ``<target>`` targets as well as ``<target>:<Config>`` targets, where ``<Config>`` is the same as the diff --git a/Help/guide/ide-integration/index.rst b/Help/guide/ide-integration/index.rst index 7b786dd5f1..e198789c79 100644 --- a/Help/guide/ide-integration/index.rst +++ b/Help/guide/ide-integration/index.rst @@ -47,8 +47,9 @@ does, and present the user with the presets listed in the file. Users should be able to see (and possibly edit) the CMake cache variables, environment variables, and command line options that are defined for a given preset. The IDE should then construct the list of appropriate :manual:`cmake(1)` command -line arguments based on these settings, rather than using the ``--preset=`` -option directly. The ``--preset=`` option is intended only as a convenient +line arguments based on these settings, rather than using the +:option:`--preset= <cmake --preset>` option directly. The +:option:`--preset= <cmake --preset>` option is intended only as a convenient frontend for command line users, and should not be used by the IDE. For example, if a preset named ``ninja`` specifies ``Ninja`` as the generator @@ -109,8 +110,9 @@ Building If a Makefile or Ninja generator is used to generate the build tree, it is not recommended to invoke ``make`` or ``ninja`` directly. Instead, it is -recommended that the IDE invoke :manual:`cmake(1)` with the ``--build`` -argument, which will in turn invoke the appropriate build tool. +recommended that the IDE invoke :manual:`cmake(1)` with the +:option:`--build <cmake --build>` argument, which will in turn invoke the +appropriate build tool. If an IDE project generator is used, such as :generator:`Xcode` or one of the Visual Studio generators, and the IDE understands the project format used, the diff --git a/Help/guide/tutorial/Packaging an Installer.rst b/Help/guide/tutorial/Packaging an Installer.rst index 328bf1b4e4..e3d8de0c64 100644 --- a/Help/guide/tutorial/Packaging an Installer.rst +++ b/Help/guide/tutorial/Packaging an Installer.rst @@ -46,7 +46,7 @@ use :option:`-C <cpack -C>` to specify the configuration. For example: cpack -G ZIP -C Debug For a list of available generators, see :manual:`cpack-generators(7)` or call -``cpack --help``. An :cpack_gen:`archive generator <CPack Archive Generator>` +:option:`cpack --help`. An :cpack_gen:`archive generator <CPack Archive Generator>` like ZIP creates a compressed archive of all *installed* files. To create an archive of the *full* source tree you would type: diff --git a/Help/guide/user-interaction/index.rst b/Help/guide/user-interaction/index.rst index 7339b7970e..1c60d2d636 100644 --- a/Help/guide/user-interaction/index.rst +++ b/Help/guide/user-interaction/index.rst @@ -71,8 +71,8 @@ The CMake tooling may report warnings which are intended for the provider of the software, not intended for the consumer of the software. Such warnings end with "This warning is for project developers". Users may disable -such warnings by passing the ``-Wno-dev`` flag to -:manual:`cmake(1)`. +such warnings by passing the :option:`-Wno-dev <cmake -Wno-dev>` +flag to :manual:`cmake(1)`. cmake-gui tool -------------- @@ -159,7 +159,7 @@ the :option:`-G <cmake -G>` option: $ cmake .. -G Ninja -The output of ``cmake --help`` includes a list of +The output of :option:`cmake --help` includes a list of :manual:`generators <cmake-generators(7)>` available for the user to choose from. Note that generator names are case sensitive. @@ -428,10 +428,10 @@ Using presets on the command-line --------------------------------- When using the :manual:`cmake(1)` command line tool, a -preset can be invoked by using the ``--preset`` option. If -``--preset`` is specified, the generator and build -directory are not required, but can be specified to -override them. For example, if you have the following +preset can be invoked by using the :option:`--preset <cmake --preset>` +option. If :option:`--preset <cmake --preset>` is specified, +the generator and build directory are not required, but can be +specified to override them. For example, if you have the following ``CMakePresets.json`` file: .. code-block:: json @@ -503,23 +503,25 @@ command may be invoked in the build directory: $ cmake --build . -The ``--build`` flag enables a particular mode of -operation for the :manual:`cmake(1)` tool. It invokes -the :variable:`CMAKE_MAKE_PROGRAM` command associated -with the :manual:`generator <cmake-generators(7)>`, or +The :option:`--build <cmake --build>` flag enables a +particular mode of operation for the :manual:`cmake(1)` +tool. It invokes the :variable:`CMAKE_MAKE_PROGRAM` +command associated with the +:manual:`generator <cmake-generators(7)>`, or the build tool configured by the user. -The ``--build`` mode also accepts the parameter -``--target`` to specify a particular target to build, -for example a particular library, executable or -custom target, or a particular special target like -``install``: +The :option:`--build <cmake --build>` mode also accepts +the parameter :option:`--target <cmake --target>` to +specify a particular target to build, for example a +particular library, executable or custom target, or a +particular special target like ``install``: .. code-block:: console $ cmake --build . --target myexe -The ``--build`` mode also accepts a ``--config`` parameter +The :option:`--build <cmake --build>` mode also accepts a +:option:`--config <cmake --config>` parameter in the case of multi-config generators to specify which particular configuration to build: @@ -527,23 +529,23 @@ particular configuration to build: $ cmake --build . --target myexe --config Release -The ``--config`` option has no effect if the generator -generates a buildsystem specific to a configuration which -is chosen when invoking cmake with the -:variable:`CMAKE_BUILD_TYPE` variable. +The :option:`--config <cmake --config>` option has no +effect if the generator generates a buildsystem specific +to a configuration which is chosen when invoking cmake +with the :variable:`CMAKE_BUILD_TYPE` variable. Some buildsystems omit details of command lines invoked -during the build. The ``--verbose`` flag can be used to -cause those command lines to be shown: +during the build. The :option:`-verbose <cmake --verbose>` +flag can be used to cause those command lines to be shown: .. code-block:: console $ cmake --build . --target myexe --verbose -The ``--build`` mode can also pass particular command -line options to the underlying build tool by listing -them after ``--``. This can be useful to specify -options to the build tool, such as to continue the +The :option:`--build <cmake --build>` mode can also pass +particular command line options to the underlying build +tool by listing them after ``--``. This can be useful +to specify options to the build tool, such as to continue the build after a failed job, where CMake does not provide a high-level user interface. @@ -639,9 +641,9 @@ building the ``foo.i`` target will preprocess both files. Specifying a Build Program -------------------------- -The program invoked by the ``--build`` mode is determined -by the :variable:`CMAKE_MAKE_PROGRAM` variable. For most -generators, the particular program does not need to be +The program invoked by the :option:`--build <cmake --build>` +mode is determined by the :variable:`CMAKE_MAKE_PROGRAM` variable. +For most generators, the particular program does not need to be configured. ===================== =========================== =========================== @@ -662,7 +664,8 @@ The ``jom`` tool is capable of reading makefiles of the ``NMake`` flavor and building in parallel, while the ``nmake`` tool always builds serially. After generating with the :generator:`NMake Makefiles` generator a user -can run ``jom`` instead of ``nmake``. The ``--build`` +can run ``jom`` instead of ``nmake``. The +:option:`--build <cmake --build>` mode would also use ``jom`` if the :variable:`CMAKE_MAKE_PROGRAM` was set to ``jom`` while using the :generator:`NMake Makefiles` generator, and @@ -746,8 +749,8 @@ run only tests without ``Qt`` in their name: $ ctest -E Qt -Tests can be run in parallel by passing ``-j`` arguments -to :manual:`ctest(1)`: +Tests can be run in parallel by passing :option:`-j <ctest -j>` +arguments to :manual:`ctest(1)`: .. code-block:: console @@ -755,14 +758,15 @@ to :manual:`ctest(1)`: The environment variable :envvar:`CTEST_PARALLEL_LEVEL` can alternatively be set to avoid the need to pass -``-j``. +:option:`-j <ctest -j>`. By default :manual:`ctest(1)` does not print the output -from the tests. The command line argument ``-V`` (or -``--verbose``) enables verbose mode to print the +from the tests. The command line argument :option:`-V <ctest -V>` +(or ``--verbose``) enables verbose mode to print the output from all tests. -The ``--output-on-failure`` option prints the test -output for failing tests only. The environment variable -:envvar:`CTEST_OUTPUT_ON_FAILURE` +The :option:`--output-on-failure <ctest --output-on-failure>` +option prints the test output for failing tests only. +The environment variable :envvar:`CTEST_OUTPUT_ON_FAILURE` can be set to ``1`` as an alternative to passing the -``--output-on-failure`` option to :manual:`ctest(1)`. +:option:`--output-on-failure <ctest --output-on-failure>` +option to :manual:`ctest(1)`. diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index 326dc71c3b..ed5bbbf6cb 100644 --- a/Help/manual/cmake-generators.7.rst +++ b/Help/manual/cmake-generators.7.rst @@ -18,11 +18,11 @@ as a variant of some of the `Command-Line Build Tool Generators`_ to produce project files for an auxiliary IDE. CMake Generators are platform-specific so each may be available only -on certain platforms. The :manual:`cmake(1)` command-line tool ``--help`` -output lists available generators on the current platform. Use its -:option:`-G <cmake -G>` option to specify the generator for a new build tree. -The :manual:`cmake-gui(1)` offers interactive selection of a generator -when creating a new build tree. +on certain platforms. The :manual:`cmake(1)` command-line tool +:option:`--help <cmake --help>` output lists available generators on the +current platform. Use its :option:`-G <cmake -G>` option to specify the +generator for a new build tree. The :manual:`cmake-gui(1)` offers +interactive selection of a generator when creating a new build tree. CMake Generators ================ @@ -108,9 +108,9 @@ Extra Generators ================ Some of the `CMake Generators`_ listed in the :manual:`cmake(1)` -command-line tool ``--help`` output may have variants that specify -an extra generator for an auxiliary IDE tool. Such generator -names have the form ``<extra-generator> - <main-generator>``. +command-line tool :option:`--help <cmake --help>` output may have +variants that specify an extra generator for an auxiliary IDE tool. +Such generator names have the form ``<extra-generator> - <main-generator>``. The following extra generators are known to CMake. .. toctree:: diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst index c834eda70d..290c2ba52e 100644 --- a/Help/manual/cmake-presets.7.rst +++ b/Help/manual/cmake-presets.7.rst @@ -19,10 +19,10 @@ supports files included with the ``include`` field. ``CMakePresets.json`` and ``CMakeUserPresets.json`` live in the project's root directory. They both have exactly the same format, and both are optional -(though at least one must be present if ``--preset`` is specified). -``CMakePresets.json`` is meant to specify project-wide build details, while -``CMakeUserPresets.json`` is meant for developers to specify their own local -build details. +(though at least one must be present if :option:`--preset <cmake --preset>` +is specified). ``CMakePresets.json`` is meant to specify project-wide build +details, while ``CMakeUserPresets.json`` is meant for developers to specify +their own local build details. ``CMakePresets.json`` may be checked into a version control system, and ``CMakeUserPresets.json`` should NOT be checked in. For example, if a @@ -312,30 +312,35 @@ that may contain the following fields: ``dev`` - An optional boolean. Equivalent to passing ``-Wdev`` or ``-Wno-dev`` - on the command line. This may not be set to ``false`` if ``errors.dev`` - is set to ``true``. + An optional boolean. Equivalent to passing :option:`-Wdev <cmake -Wdev>` + or :option:`-Wno-dev <cmake -Wno-dev>` on the command line. This may not + be set to ``false`` if ``errors.dev`` is set to ``true``. ``deprecated`` - An optional boolean. Equivalent to passing ``-Wdeprecated`` or - ``-Wno-deprecated`` on the command line. This may not be set to - ``false`` if ``errors.deprecated`` is set to ``true``. + An optional boolean. Equivalent to passing + :option:`-Wdeprecated <cmake -Wdeprecated>` or + :option:`-Wno-deprecated <cmake -Wno-deprecated>` on the command line. + This may not be set to ``false`` if ``errors.deprecated`` is set to + ``true``. ``uninitialized`` An optional boolean. Setting this to ``true`` is equivalent to passing - ``--warn-uninitialized`` on the command line. + :option:`--warn-uninitialized <cmake --warn-uninitialized>` on the command + line. ``unusedCli`` An optional boolean. Setting this to ``false`` is equivalent to passing - ``--no-warn-unused-cli`` on the command line. + :option:`--no-warn-unused-cli <cmake --no-warn-unused-cli>` on the command + line. ``systemVars`` An optional boolean. Setting this to ``true`` is equivalent to passing - ``--check-system-vars`` on the command line. + :option:`--check-system-vars <cmake --check-system-vars>` on the command + line. ``errors`` @@ -362,17 +367,18 @@ that may contain the following fields: ``output`` An optional boolean. Setting this to ``true`` is equivalent to passing - ``--debug-output`` on the command line. + :option:`--debug-output <cmake --debug-output>` on the command line. ``tryCompile`` An optional boolean. Setting this to ``true`` is equivalent to passing - ``--debug-trycompile`` on the command line. + :option:`--debug-trycompile <cmake --debug-trycompile>` on the command + line. ``find`` An optional boolean. Setting this to ``true`` is equivalent to passing - ``--debug-find`` on the command line. + :option:`--debug-find <cmake --debug-find>` on the command line. Build Preset ^^^^^^^^^^^^ @@ -392,7 +398,8 @@ that may contain the following fields: ``hidden`` An optional boolean specifying whether or not a preset should be hidden. - If a preset is hidden, it cannot be used in the ``--preset`` argument + If a preset is hidden, it cannot be used in the + :option:`--preset <cmake --preset>` argument and does not have to have a valid ``configurePreset``, even from inheritance. ``hidden`` presets are intended to be used as a base for other presets to inherit via the ``inherits`` field. @@ -486,25 +493,25 @@ that may contain the following fields: ``jobs`` - An optional integer. Equivalent to passing ``--parallel`` or ``-j`` on - the command line. + An optional integer. Equivalent to passing + :option:`--parallel <cmake --parallel>` or ``-j`` on the command line. ``targets`` An optional string or array of strings. Equivalent to passing - ``--target`` or ``-t`` on the command line. Vendors may ignore the - targets property or hide build presets that explicitly specify targets. - This field supports macro expansion. + :option:`--target <cmake --target>` or ``-t`` on the command line. + Vendors may ignore the targets property or hide build presets that + explicitly specify targets. This field supports macro expansion. ``configuration`` - An optional string. Equivalent to passing ``--config`` on the command - line. + An optional string. Equivalent to passing :option:`--config <cmake --config>` + on the command line. ``cleanFirst`` - An optional bool. If true, equivalent to passing ``--clean-first`` on - the command line. + An optional bool. If true, equivalent to passing + :option:`--clean-first <cmake --clean-first>` on the command line. ``resolvePackageReferences`` @@ -531,10 +538,12 @@ that may contain the following fields: .. note:: - The command line parameter ``--resolve-package-references`` will take - priority over this setting. If the command line parameter is not provided - and this setting is not specified, an environment-specific cache variable - will be evaluated to decide, if package restoration should be performed. + The command line parameter + :option:`--resolve-package-references <cmake --resolve-package-references>` + will take priority over this setting. If the command line parameter is not + provided and this setting is not specified, an environment-specific cache + variable will be evaluated to decide, if package restoration should be + performed. When using the Visual Studio generator, package references are defined using the :prop_tgt:`VS_PACKAGE_REFERENCES` property. Package references @@ -544,8 +553,8 @@ that may contain the following fields: ``verbose`` - An optional bool. If true, equivalent to passing ``--verbose`` on the - command line. + An optional bool. If true, equivalent to passing + :option:`--verbose <cmake --verbose>` on the command line. ``nativeToolOptions`` @@ -569,7 +578,8 @@ that may contain the following fields: ``hidden`` An optional boolean specifying whether or not a preset should be hidden. - If a preset is hidden, it cannot be used in the ``--preset`` argument + If a preset is hidden, it cannot be used in the + :option:`--preset <ctest --preset>` argument and does not have to have a valid ``configurePreset``, even from inheritance. ``hidden`` presets are intended to be used as a base for other presets to inherit via the ``inherits`` field. @@ -650,15 +660,15 @@ that may contain the following fields: ``configuration`` - An optional string. Equivalent to passing ``--build-config`` on the - command line. + An optional string. Equivalent to passing + :option:`--build-config <ctest --build-config>` on the command line. ``overwriteConfigurationFile`` An optional array of configuration options to overwrite options specified in the CTest configuration file. Equivalent to passing - ``--overwrite`` for each value in the array. The array values - support macro expansion. + :option:`--overwrite <ctest --overwrite>` for each value in the array. + The array values support macro expansion. ``output`` @@ -667,8 +677,8 @@ that may contain the following fields: ``shortProgress`` - An optional bool. If true, equivalent to passing ``--progress`` on the - command line. + An optional bool. If true, equivalent to passing + :option:`--progress <ctest --progress>` on the command line. ``verbosity`` @@ -681,65 +691,75 @@ that may contain the following fields: ``verbose`` - Equivalent to passing ``--verbose`` on the command line. + Equivalent to passing :option:`--verbose <ctest --verbose>` on + the command line. ``extra`` - Equivalent to passing ``--extra-verbose`` on the command line. + Equivalent to passing :option:`--extra-verbose <ctest --extra-verbose>` + on the command line. ``debug`` - An optional bool. If true, equivalent to passing ``--debug`` on the - command line. + An optional bool. If true, equivalent to passing + :option:`--debug <ctest --debug>` on the command line. ``outputOnFailure`` An optional bool. If true, equivalent to passing - ``--output-on-failure`` on the command line. + :option:`--output-on-failure <ctest --output-on-failure>` on the command + line. ``quiet`` - An optional bool. If true, equivalent to passing ``--quiet`` on the - command line. + An optional bool. If true, equivalent to passing + :option:`--quiet <ctest --quiet>` on the command line. ``outputLogFile`` An optional string specifying a path to a log file. Equivalent to - passing ``--output-log`` on the command line. This field supports - macro expansion. + passing :option:`--output-log <ctest --output-log>` on the command line. + This field supports macro expansion. ``labelSummary`` An optional bool. If false, equivalent to passing - ``--no-label-summary`` on the command line. + :option:`--no-label-summary <ctest --no-label-summary>` on the command + line. ``subprojectSummary`` An optional bool. If false, equivalent to passing - ``--no-subproject-summary`` on the command line. + :option:`--no-subproject-summary <ctest --no-subproject-summary>` + on the command line. ``maxPassedTestOutputSize`` An optional integer specifying the maximum output for passed tests in - bytes. Equivalent to passing ``--test-output-size-passed`` on the - command line. + bytes. Equivalent to passing + :option:`--test-output-size-passed <ctest --test-output-size-passed>` + on the command line. ``maxFailedTestOutputSize`` An optional integer specifying the maximum output for failed tests in - bytes. Equivalent to passing ``--test-output-size-failed`` on the - command line. + bytes. Equivalent to passing + :option:`--test-output-size-failed <ctest --test-output-size-failed>` + on the command line. ``testOutputTruncation`` An optional string specifying the test output truncation mode. Equivalent - to passing ``--test-output-truncation`` on the command line." - This is allowed in preset files specifying version ``5`` or above. + to passing + :option:`--test-output-truncation <ctest --test-output-truncation>` on + the command line. This is allowed in preset files specifying version + ``5`` or above. ``maxTestNameWidth`` An optional integer specifying the maximum width of a test name to - output. Equivalent to passing ``--max-width`` on the command line. + output. Equivalent to passing :option:`--max-width <ctest --max-width>` + on the command line. ``filter`` @@ -754,29 +774,29 @@ that may contain the following fields: ``name`` An optional string specifying a regex for test names. Equivalent to - passing ``--tests-regex`` on the command line. This field supports - macro expansion. CMake regex syntax is described under - :ref:`string(REGEX) <Regex Specification>`. + passing :option:`--tests-regex <ctest --tests-regex>` on the command + line. This field supports macro expansion. CMake regex syntax is + described under :ref:`string(REGEX) <Regex Specification>`. ``label`` An optional string specifying a regex for test labels. Equivalent to - passing ``--label-regex`` on the command line. This field supports - macro expansion. + passing :option:`--label-regex <ctest --label-regex>` on the command + line. This field supports macro expansion. ``useUnion`` - An optional bool. Equivalent to passing ``--union`` on the command - line. + An optional bool. Equivalent to passing :option:`--union <ctest --union>` + on the command line. ``index`` An optional object specifying tests to include by test index. The object may contain the following fields. Can also be an optional string specifying a file with the command line syntax for - ``--tests-information``. If specified as a string, this field - supports macro expansion. + :option:`--tests-information <ctest --tests-information>`. + If specified as a string, this field supports macro expansion. ``start`` @@ -803,14 +823,14 @@ that may contain the following fields: ``name`` An optional string specifying a regex for test names. Equivalent to - passing ``--exclude-regex`` on the command line. This field supports - macro expansion. + passing :option:`--exclude-regex <ctest --exclude-regex>` on the + command line. This field supports macro expansion. ``label`` An optional string specifying a regex for test labels. Equivalent to - passing ``--label-exclude`` on the command line. This field supports - macro expansion. + passing :option:`--label-exclude <ctest --label-exclude>` on the + command line. This field supports macro expansion. ``fixtures`` @@ -820,21 +840,23 @@ that may contain the following fields: ``any`` An optional string specifying a regex for text fixtures to exclude - from adding any tests. Equivalent to ``--fixture-exclude-any`` on + from adding any tests. Equivalent to + :option:`--fixture-exclude-any <ctest --fixture-exclude-any>` on the command line. This field supports macro expansion. ``setup`` An optional string specifying a regex for text fixtures to exclude - from adding setup tests. Equivalent to ``--fixture-exclude-setup`` + from adding setup tests. Equivalent to + :option:`--fixture-exclude-setup <ctest --fixture-exclude-setup>` on the command line. This field supports macro expansion. ``cleanup`` An optional string specifying a regex for text fixtures to exclude from adding cleanup tests. Equivalent to - ``--fixture-exclude-cleanup`` on the command line. This field - supports macro expansion. + :option:`--fixture-exclude-cleanup <ctest --fixture-exclude-cleanup>` + on the command line. This field supports macro expansion. ``execution`` @@ -843,32 +865,35 @@ that may contain the following fields: ``stopOnFailure`` - An optional bool. If true, equivalent to passing ``--stop-on-failure`` - on the command line. + An optional bool. If true, equivalent to passing + :option:`--stop-on-failure <ctest --stop-on-failure>` on the command + line. ``enableFailover`` - An optional bool. If true, equivalent to passing ``-F`` on the command - line. + An optional bool. If true, equivalent to passing :option:`-F <ctest -F>` + on the command line. ``jobs`` - An optional integer. Equivalent to passing ``--parallel`` on the - command line. + An optional integer. Equivalent to passing + :option:`--parallel <ctest --parallel>` on the command line. ``resourceSpecFile`` - An optional string. Equivalent to passing ``--resource-spec-file`` on + An optional string. Equivalent to passing + :option:`--resource-spec-file <ctest --resource-spec-file>` on the command line. This field supports macro expansion. ``testLoad`` - An optional integer. Equivalent to passing ``--test-load`` on the - command line. + An optional integer. Equivalent to passing + :option:`--test-load <ctest --test-load>` on the command line. ``showOnly`` - An optional string. Equivalent to passing ``--show-only`` on the + An optional string. Equivalent to passing + :option:`--show-only <ctest --show-only>` on the command line. The string must be one of the following values: ``human`` @@ -878,8 +903,8 @@ that may contain the following fields: ``repeat`` An optional object specifying how to repeat tests. Equivalent to - passing ``--repeat`` on the command line. The object must have the - following fields. + passing :option:`--repeat <ctest --repeat>` on the command line. + The object must have the following fields. ``mode`` @@ -898,19 +923,21 @@ that may contain the following fields: ``interactiveDebugging`` An optional bool. If true, equivalent to passing - ``--interactive-debug-mode 1`` on the command line. If false, - equivalent to passing ``--interactive-debug-mode 0`` on the command - line. + :option:`--interactive-debug-mode 1 <ctest --interactive-debug-mode>` + on the command line. If false, equivalent to passing + :option:`--interactive-debug-mode 0 <ctest --interactive-debug-mode>` + on the command line. ``scheduleRandom`` - An optional bool. If true, equivalent to passing ``--schedule-random`` - on the command line. + An optional bool. If true, equivalent to passing + :option:`--schedule-random <ctest --schedule-random>` on the command + line. ``timeout`` - An optional integer. Equivalent to passing ``--timeout`` on the - command line. + An optional integer. Equivalent to passing + :option:`--timeout <ctest --timeout>` on the command line. ``noTestsAction`` @@ -923,11 +950,13 @@ that may contain the following fields: ``error`` - Equivalent to passing ``--no-tests=error`` on the command line. + Equivalent to passing :option:`--no-tests=error <ctest --no-tests>` + on the command line. ``ignore`` - Equivalent to passing ``--no-tests=ignore`` on the command line. + Equivalent to passing :option:`--no-tests=ignore <ctest --no-tests>` + on the command line. Condition ^^^^^^^^^ diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 2c2ff5fac6..13ae21ce33 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -96,7 +96,7 @@ Build Tree Generator This chooses the kind of buildsystem to generate. See the :manual:`cmake-generators(7)` manual for documentation of all generators. - Run ``cmake --help`` to see a list of generators available locally. + 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. @@ -558,7 +558,7 @@ following options: .. option:: --clean-first Build target ``clean`` first, then build. - (To clean only, use ``--target clean``.) + (To clean only, use :option:`--target clean <cmake --target>`.) .. option:: --resolve-package-references=<on|off|only> @@ -601,7 +601,7 @@ following options: Pass remaining options to the native tool. -Run ``cmake --build`` with no options for quick help. +Run :option:`cmake --build` with no options for quick help. Install a Project ================= @@ -647,7 +647,7 @@ The options are: This option can be omitted if :envvar:`VERBOSE` environment variable is set. -Run ``cmake --install`` with no options for quick help. +Run :option:`cmake --install` with no options for quick help. Open a Project ============== @@ -700,7 +700,10 @@ CMake provides builtin command-line tools through the signature cmake -E <command> [<options>] -Run ``cmake -E`` or ``cmake -E help`` for a summary of commands. +.. option:: -E [help] + + Run ``cmake -E`` or ``cmake -E help`` for a summary of commands. + Available commands are: .. option:: capabilities diff --git a/Help/variable/CMAKE_CPACK_COMMAND.rst b/Help/variable/CMAKE_CPACK_COMMAND.rst index 3a81d68167..94f1891200 100644 --- a/Help/variable/CMAKE_CPACK_COMMAND.rst +++ b/Help/variable/CMAKE_CPACK_COMMAND.rst @@ -6,5 +6,5 @@ CMAKE_CPACK_COMMAND Full path to :manual:`cpack(1)` command installed with CMake. This is the full path to the CPack executable :manual:`cpack(1)` which is -useful from custom commands that want to use the :manual:`cmake(1)` ``-E`` +useful from custom commands that want to use the :option:`cmake -E <cmake_E -E>` option for portable system commands. diff --git a/Help/variable/CMAKE_CTEST_COMMAND.rst b/Help/variable/CMAKE_CTEST_COMMAND.rst index b2942e2a8b..7287998bb4 100644 --- a/Help/variable/CMAKE_CTEST_COMMAND.rst +++ b/Help/variable/CMAKE_CTEST_COMMAND.rst @@ -4,5 +4,5 @@ CMAKE_CTEST_COMMAND Full path to :manual:`ctest(1)` command installed with CMake. This is the full path to the CTest executable :manual:`ctest(1)` which is -useful from custom commands that want to use the :manual:`cmake(1)` ``-E`` +useful from custom commands that want to use the :option:`cmake -E <cmake_E -E>` option for portable system commands. diff --git a/Help/variable/CMAKE_FIND_DEBUG_MODE.rst b/Help/variable/CMAKE_FIND_DEBUG_MODE.rst index 8f2a82f24d..48b0dce655 100644 --- a/Help/variable/CMAKE_FIND_DEBUG_MODE.rst +++ b/Help/variable/CMAKE_FIND_DEBUG_MODE.rst @@ -13,7 +13,7 @@ error: * :command:`find_package` Output is designed for human consumption and not for parsing. -Enabling this variable is equivalent to using :manual:`cmake <cmake(1)>` ``--debug-find`` +Enabling this variable is equivalent to using :option:`cmake --debug-find` with the added ability to enable debugging for a subset of find calls. .. code-block:: cmake diff --git a/Help/variable/CMAKE_GENERATOR.rst b/Help/variable/CMAKE_GENERATOR.rst index ec52cd4d86..0e249eb51e 100644 --- a/Help/variable/CMAKE_GENERATOR.rst +++ b/Help/variable/CMAKE_GENERATOR.rst @@ -7,6 +7,6 @@ The name of the generator that is being used to generate the build files. (e.g. ``Unix Makefiles``, ``Ninja``, etc.) The value of this variable should never be modified by project code. -A generator may be selected via the :manual:`cmake(1)` ``-G`` option, +A generator may be selected via the :option:`cmake -G` option, interactively in :manual:`cmake-gui(1)`, or via the :envvar:`CMAKE_GENERATOR` environment variable. diff --git a/Help/variable/CMAKE_INSTALL_PREFIX.rst b/Help/variable/CMAKE_INSTALL_PREFIX.rst index 6d42ea8f05..1636739be8 100644 --- a/Help/variable/CMAKE_INSTALL_PREFIX.rst +++ b/Help/variable/CMAKE_INSTALL_PREFIX.rst @@ -27,8 +27,9 @@ first :command:`project` invocation. The ``CMAKE_INSTALL_PREFIX`` may be defined when configuring a build tree to set its installation prefix. Or, when using the :manual:`cmake(1)` -command-line tool's ``--install`` mode, one may specify a different prefix -using the ``--prefix`` option: +command-line tool's :option:`--install <cmake --install>` mode, one may +specify a different prefix using the :option:`--prefix <cmake --prefix>` +option: .. code-block:: shell diff --git a/Help/variable/CMAKE_MAKE_PROGRAM.rst b/Help/variable/CMAKE_MAKE_PROGRAM.rst index a3c8b7c8a5..9769c7ae78 100644 --- a/Help/variable/CMAKE_MAKE_PROGRAM.rst +++ b/Help/variable/CMAKE_MAKE_PROGRAM.rst @@ -59,6 +59,6 @@ to configure the project: variable, changing the value has undefined behavior. The ``CMAKE_MAKE_PROGRAM`` variable is set for use by project code. -The value is also used by the :manual:`cmake(1)` ``--build`` and -:manual:`ctest(1)` ``--build-and-test`` tools to launch the native +The value is also used by the :option:`cmake --build` and +:option:`ctest --build-and-test` tools to launch the native build process. diff --git a/Help/variable/CMAKE_MESSAGE_CONTEXT.rst b/Help/variable/CMAKE_MESSAGE_CONTEXT.rst index 41ace436fc..7274b7b684 100644 --- a/Help/variable/CMAKE_MESSAGE_CONTEXT.rst +++ b/Help/variable/CMAKE_MESSAGE_CONTEXT.rst @@ -3,7 +3,7 @@ CMAKE_MESSAGE_CONTEXT .. versionadded:: 3.17 -When enabled by the :manual:`cmake <cmake(1)>` ``--log-context`` command line +When enabled by the :option:`cmake --log-context` command line option or the :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` variable, the :command:`message` command converts the ``CMAKE_MESSAGE_CONTEXT`` list into a dot-separated string surrounded by square brackets and prepends it to each line diff --git a/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst b/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst index 54ea6a4822..4539c90ac1 100644 --- a/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst +++ b/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst @@ -5,8 +5,9 @@ CMAKE_MESSAGE_LOG_LEVEL When set, this variable specifies the logging level used by the :command:`message` command. Valid values are the same as those for the -``--log-level`` command line option of the :manual:`cmake(1)` program. -If this variable is set and the ``--log-level`` command line option is +:option:`--log-level <cmake --log-level>` command line option of the +:manual:`cmake(1)` program. If this variable is set and the +:option:`--log-level <cmake --log-level>` command line option is given, the command line option takes precedence. The main advantage to using this variable is to make a log level persist diff --git a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst index 9dce7600a1..f844105e43 100644 --- a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst @@ -42,5 +42,8 @@ only for the policies that do not warn by default: This variable should not be set by a project in CMake code. Project developers running CMake may set this variable in their cache to enable the warning (e.g. ``-DCMAKE_POLICY_WARNING_CMP<NNNN>=ON``). -Alternatively, running :manual:`cmake(1)` with the ``--debug-output``, -``--trace``, or ``--trace-expand`` option will also enable the warning. +Alternatively, running :manual:`cmake(1)` with the +:option:`--debug-output <cmake --debug-output>`, +:option:`--trace <cmake --trace>`, or +:option:`--trace-expand <cmake --trace-expand>` option will also +enable the warning. diff --git a/Help/variable/CMAKE_SCRIPT_MODE_FILE.rst b/Help/variable/CMAKE_SCRIPT_MODE_FILE.rst index 981af60cf1..104f4ac1ab 100644 --- a/Help/variable/CMAKE_SCRIPT_MODE_FILE.rst +++ b/Help/variable/CMAKE_SCRIPT_MODE_FILE.rst @@ -1,9 +1,9 @@ CMAKE_SCRIPT_MODE_FILE ---------------------- -Full path to the :manual:`cmake(1)` ``-P`` script file currently being +Full path to the :option:`cmake -P <cmake_P -P>` script file currently being processed. -When run in :manual:`cmake(1)` ``-P`` script mode, CMake sets this variable to +When run in :option:`cmake -P <cmake_P -P>` script mode, CMake sets this variable to the full path of the script file. When run to configure a ``CMakeLists.txt`` file, this variable is not set. diff --git a/Help/variable/CMAKE_WARN_DEPRECATED.rst b/Help/variable/CMAKE_WARN_DEPRECATED.rst index 4a224fa5cf..c7b615938e 100644 --- a/Help/variable/CMAKE_WARN_DEPRECATED.rst +++ b/Help/variable/CMAKE_WARN_DEPRECATED.rst @@ -7,4 +7,5 @@ If not ``FALSE``, use of deprecated functionality will issue warnings. If this variable is not set, CMake behaves as if it were set to ``TRUE``. When running :manual:`cmake(1)`, this option can be enabled with the -``-Wdeprecated`` option, or disabled with the ``-Wno-deprecated`` option. +:option:`-Wdeprecated <cmake -Wdeprecated>` option, or disabled with the +:option:`-Wno-deprecated <cmake -Wno-deprecated>` option. diff --git a/Help/variable/CTEST_CONFIGURATION_TYPE.rst b/Help/variable/CTEST_CONFIGURATION_TYPE.rst index 392845e29b..932f81d1e3 100644 --- a/Help/variable/CTEST_CONFIGURATION_TYPE.rst +++ b/Help/variable/CTEST_CONFIGURATION_TYPE.rst @@ -6,5 +6,5 @@ CTEST_CONFIGURATION_TYPE Specify the CTest ``DefaultCTestConfigurationType`` setting in a :manual:`ctest(1)` dashboard client script. -If the configuration type is set via ``-C <cfg>`` from the command line +If the configuration type is set via :option:`-C \<cfg\> <ctest -C>` from the command line then this variable is populated accordingly. |