diff options
| author | Brad King <brad.king@kitware.com> | 2022-08-08 13:39:28 (GMT) |
|---|---|---|
| committer | Kitware Robot <kwrobot@kitware.com> | 2022-08-08 13:39:41 (GMT) |
| commit | ed86192cd8f9edee1abdcd5de48089ad9f3b140b (patch) | |
| tree | d65d4687f417526faffb62fe7e7460d1ee18136b | |
| parent | 33d2491449bfbcee19e1c5d6d181b26f041cbd02 (diff) | |
| parent | a6abdf6c8fdb8edf240198724a3191296f05a292 (diff) | |
| download | CMake-ed86192cd8f9edee1abdcd5de48089ad9f3b140b.zip CMake-ed86192cd8f9edee1abdcd5de48089ad9f3b140b.tar.gz CMake-ed86192cd8f9edee1abdcd5de48089ad9f3b140b.tar.bz2 | |
Merge topic 'doc-markup-program-options'
a6abdf6c8f Help: Consistent options declaration -- short first, then long
f4563f05db Help: Value for `--graphviz=` option actually is mandatory
04843d743e Help: Replace a bunch of more ``--option`` to `:option:` role
09446266ee Help: Replace mentions of ``-D`` option with :option:`-D` role
b57f27b087 Help: Replace mentions of ``-T`` and ``-A`` options with role
d25b232dee Help: Replace mentions of ``-G`` option with :option:`-G` role
63940e1cab Help: Replace mentions of ``-C`` option with :option:`-C` role
183a49cbfe Help: Replace mentions of ``-S`` option with :option:`-S` role
...
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !7544
61 files changed, 842 insertions, 542 deletions
diff --git a/Help/command/cmake_language.rst b/Help/command/cmake_language.rst index 377e42d..d0c7c19 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_run_script.rst b/Help/command/ctest_run_script.rst index 5ec543e..a2b348f 100644 --- a/Help/command/ctest_run_script.rst +++ b/Help/command/ctest_run_script.rst @@ -1,15 +1,15 @@ ctest_run_script ---------------- -runs a ctest -S script +runs a :option:`ctest -S` script :: ctest_run_script([NEW_PROCESS] script_file_name script_file_name1 script_file_name2 ... [RETURN_VALUE var]) -Runs a script or scripts much like if it was run from ctest -S. If no -argument is provided then the current script is run using the current +Runs a script or scripts much like if it was run from :option:`ctest -S`. +If no argument is provided then the current script is run using the current settings of the variables. If ``NEW_PROCESS`` is specified then each script will be run in a separate process.If ``RETURN_VALUE`` is specified the return value of the last script run will be put into ``var``. diff --git a/Help/command/ctest_start.rst b/Help/command/ctest_start.rst index c0f3c6d..921279a 100644 --- a/Help/command/ctest_start.rst +++ b/Help/command/ctest_start.rst @@ -45,7 +45,7 @@ The parameters are as follows: ctest_start(Experimental GROUP GroupExperimental) - Later, in another ``ctest -S`` script: + Later, in another :option:`ctest -S` script: .. code-block:: cmake diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst index 11ebdbd..f058150 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 d6c5105..717f822 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -369,7 +369,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 e02b9bc..6bcc1ef 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 5aa3a4b..e2aeaad 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 ca4f5c1..77d21c8 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 806a98d..e03ab80 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 125b0ac..938869b 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/cpack_gen/external.rst b/Help/cpack_gen/external.rst index 4c083f0..b511319 100644 --- a/Help/cpack_gen/external.rst +++ b/Help/cpack_gen/external.rst @@ -207,8 +207,8 @@ following fields in the root: set. ``buildConfig`` - The build configuration given to CPack with the ``-C`` option. Only present - if this option is set. + The build configuration given to CPack with the :option:`cpack -C` option. + Only present if this option is set. ``defaultDirectoryPermissions`` The default directory permissions given in diff --git a/Help/cpack_gen/rpm.rst b/Help/cpack_gen/rpm.rst index 0d287fc..13b7255 100644 --- a/Help/cpack_gen/rpm.rst +++ b/Help/cpack_gen/rpm.rst @@ -972,7 +972,7 @@ For CMake projects SRPM package would be produced by executing:: Produced SRPM package is expected to be built with :manual:`cmake(1)` executable and packaged with :manual:`cpack(1)` executable so CMakeLists.txt has to be located in root source directory and must be able to generate binary rpm - packages by executing ``cpack -G`` command. The two executables as well as + packages by executing :option:`cpack -G` command. The two executables as well as rpmbuild must also be present when generating binary rpm packages from the produced SRPM package. diff --git a/Help/envvar/CMAKE_GENERATOR.rst b/Help/envvar/CMAKE_GENERATOR.rst index 3488b04..596e8f3 100644 --- a/Help/envvar/CMAKE_GENERATOR.rst +++ b/Help/envvar/CMAKE_GENERATOR.rst @@ -6,9 +6,9 @@ CMAKE_GENERATOR .. include:: ENV_VAR.txt Specifies the CMake default generator to use when no generator is supplied -with ``-G``. If the provided value doesn't name a generator known by CMake, -the internal default is used. Either way the resulting generator selection -is stored in the :variable:`CMAKE_GENERATOR` variable. +with :option:`-G <cmake -G>`. If the provided value doesn't name a generator +known by CMake, the internal default is used. Either way the resulting +generator selection is stored in the :variable:`CMAKE_GENERATOR` variable. Some generators may be additionally configured using the environment variables: diff --git a/Help/envvar/CMAKE_GENERATOR_PLATFORM.rst b/Help/envvar/CMAKE_GENERATOR_PLATFORM.rst index b039845..e657904 100644 --- a/Help/envvar/CMAKE_GENERATOR_PLATFORM.rst +++ b/Help/envvar/CMAKE_GENERATOR_PLATFORM.rst @@ -6,5 +6,5 @@ CMAKE_GENERATOR_PLATFORM .. include:: ENV_VAR.txt Default value for :variable:`CMAKE_GENERATOR_PLATFORM` if no Cache entry -is present and no value is specified by :manual:`cmake(1)` ``-A`` option. +is present and no value is specified by :option:`cmake -A` option. This value is only applied if :envvar:`CMAKE_GENERATOR` is set. diff --git a/Help/envvar/CMAKE_GENERATOR_TOOLSET.rst b/Help/envvar/CMAKE_GENERATOR_TOOLSET.rst index 394dd88..03208e7 100644 --- a/Help/envvar/CMAKE_GENERATOR_TOOLSET.rst +++ b/Help/envvar/CMAKE_GENERATOR_TOOLSET.rst @@ -6,5 +6,5 @@ CMAKE_GENERATOR_TOOLSET .. include:: ENV_VAR.txt Default value for :variable:`CMAKE_GENERATOR_TOOLSET` if no Cache entry -is present and no value is specified by :manual:`cmake(1)` ``-T`` option. +is present and no value is specified by :option:`cmake -T` option. This value is only applied if :envvar:`CMAKE_GENERATOR` is set. diff --git a/Help/envvar/CTEST_PROGRESS_OUTPUT.rst b/Help/envvar/CTEST_PROGRESS_OUTPUT.rst index 8c29d7d..348acc6 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 94cae4a..414db12 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/Green Hills MULTI.rst b/Help/generator/Green Hills MULTI.rst index 1b4739b..7a5993a 100644 --- a/Help/generator/Green Hills MULTI.rst +++ b/Help/generator/Green Hills MULTI.rst @@ -28,12 +28,12 @@ Otherwise the ``primaryTarget`` will be composed from the values of :variable:`C and ``GHS_TARGET_PLATFORM``. Defaulting to the value of ``arm_integrity.tgt`` * The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps - via the :manual:`cmake(1)` ``-A`` option. + via the :option:`cmake -A` option. | Typical values of ``arm``, ``ppc``, ``86``, etcetera, are used. -* The variable ``GHS_TARGET_PLATFORM`` may be set, perhaps via the :manual:`cmake(1)` - ``-D`` option. +* The variable ``GHS_TARGET_PLATFORM`` may be set, perhaps via the :option:`cmake -D` + option. | Defaults to ``integrity``. | Usual values are ``integrity``, ``threadx``, ``uvelosity``, ``velosity``, @@ -55,11 +55,11 @@ The generator searches for the latest compiler or can be given a location to use ``GHS_TOOLSET_ROOT`` is the directory that is checked for the latest compiler. * The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps - via the :manual:`cmake(1)` ``-T`` option, to specify the location of the toolset. + via the :option:`cmake -T` option, to specify the location of the toolset. Both absolute and relative paths are valid. Paths are relative to ``GHS_TOOLSET_ROOT``. -* The variable ``GHS_TOOLSET_ROOT`` may be set, perhaps via the :manual:`cmake(1)` - ``-D`` option. +* The variable ``GHS_TOOLSET_ROOT`` may be set, perhaps via the :option:`cmake -D` + option. | Root path for toolset searches and relative paths. | Defaults to ``C:/ghs`` in Windows or ``/usr/ghs`` in Linux. diff --git a/Help/generator/Ninja Multi-Config.rst b/Help/generator/Ninja Multi-Config.rst index e5ce4f5..ae075ed 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/generator/Visual Studio 10 2010.rst b/Help/generator/Visual Studio 10 2010.rst index 9ec33c3..66cd25f 100644 --- a/Help/generator/Visual Studio 10 2010.rst +++ b/Help/generator/Visual Studio 10 2010.rst @@ -27,7 +27,7 @@ The default target platform name (architecture) is ``Win32``. .. versionadded:: 3.1 The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps - via the :manual:`cmake(1)` ``-A`` option, to specify a target platform + via the :option:`cmake -A` option, to specify a target platform name (architecture). For example: * ``cmake -G "Visual Studio 10 2010" -A Win32`` @@ -49,4 +49,4 @@ Toolset Selection The ``v100`` toolset that comes with Visual Studio 10 2010 is selected by default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps -via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. +via the :option:`cmake -T` option, to specify another toolset. diff --git a/Help/generator/Visual Studio 11 2012.rst b/Help/generator/Visual Studio 11 2012.rst index 3952228..adbd1af 100644 --- a/Help/generator/Visual Studio 11 2012.rst +++ b/Help/generator/Visual Studio 11 2012.rst @@ -20,7 +20,7 @@ The default target platform name (architecture) is ``Win32``. .. versionadded:: 3.1 The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps - via the :manual:`cmake(1)` ``-A`` option, to specify a target platform + via the :option:`cmake -A` option, to specify a target platform name (architecture). For example: * ``cmake -G "Visual Studio 11 2012" -A Win32`` @@ -47,4 +47,4 @@ Toolset Selection The ``v110`` toolset that comes with Visual Studio 11 2012 is selected by default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps -via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. +via the :option:`cmake -T` option, to specify another toolset. diff --git a/Help/generator/Visual Studio 12 2013.rst b/Help/generator/Visual Studio 12 2013.rst index 54a4d7e..3dbcfe6 100644 --- a/Help/generator/Visual Studio 12 2013.rst +++ b/Help/generator/Visual Studio 12 2013.rst @@ -20,7 +20,7 @@ The default target platform name (architecture) is ``Win32``. .. versionadded:: 3.1 The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps - via the :manual:`cmake(1)` ``-A`` option, to specify a target platform + via the :option:`cmake -A` option, to specify a target platform name (architecture). For example: * ``cmake -G "Visual Studio 12 2013" -A Win32`` @@ -42,7 +42,7 @@ Toolset Selection The ``v120`` toolset that comes with Visual Studio 12 2013 is selected by default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps -via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. +via the :option:`cmake -T` option, to specify another toolset. .. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace:: By default this generator uses the 32-bit variant even on a 64-bit host. diff --git a/Help/generator/Visual Studio 14 2015.rst b/Help/generator/Visual Studio 14 2015.rst index d704ab2..af7dfaa 100644 --- a/Help/generator/Visual Studio 14 2015.rst +++ b/Help/generator/Visual Studio 14 2015.rst @@ -18,7 +18,7 @@ Platform Selection The default target platform name (architecture) is ``Win32``. The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps -via the :manual:`cmake(1)` ``-A`` option, to specify a target platform +via the :option:`cmake -A` option, to specify a target platform name (architecture). For example: * ``cmake -G "Visual Studio 14 2015" -A Win32`` @@ -40,7 +40,7 @@ Toolset Selection The ``v140`` toolset that comes with Visual Studio 14 2015 is selected by default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps -via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. +via the :option:`cmake -T` option, to specify another toolset. .. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace:: By default this generator uses the 32-bit variant even on a 64-bit host. diff --git a/Help/generator/Visual Studio 15 2017.rst b/Help/generator/Visual Studio 15 2017.rst index 912afad..6bcc033 100644 --- a/Help/generator/Visual Studio 15 2017.rst +++ b/Help/generator/Visual Studio 15 2017.rst @@ -26,7 +26,7 @@ Platform Selection The default target platform name (architecture) is ``Win32``. The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps -via the :manual:`cmake(1)` ``-A`` option, to specify a target platform +via the :option:`cmake -A` option, to specify a target platform name (architecture). For example: * ``cmake -G "Visual Studio 15 2017" -A Win32`` @@ -49,7 +49,7 @@ Toolset Selection The ``v141`` toolset that comes with Visual Studio 15 2017 is selected by default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps -via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. +via the :option:`cmake -T` option, to specify another toolset. .. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace:: By default this generator uses the 32-bit variant even on a 64-bit host. diff --git a/Help/generator/Visual Studio 16 2019.rst b/Help/generator/Visual Studio 16 2019.rst index 6cefe6d..2918a6e 100644 --- a/Help/generator/Visual Studio 16 2019.rst +++ b/Help/generator/Visual Studio 16 2019.rst @@ -25,7 +25,7 @@ The default target platform name (architecture) is that of the host and is provided in the :variable:`CMAKE_VS_PLATFORM_NAME_DEFAULT` variable. The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps -via the :manual:`cmake(1)` ``-A`` option, to specify a target platform +via the :option:`cmake -A` option, to specify a target platform name (architecture). For example: * ``cmake -G "Visual Studio 16 2019" -A Win32`` @@ -38,7 +38,7 @@ Toolset Selection The ``v142`` toolset that comes with Visual Studio 16 2019 is selected by default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps -via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. +via the :option:`cmake -T` option, to specify another toolset. .. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace:: By default this generator uses the 64-bit variant on x64 hosts and diff --git a/Help/generator/Visual Studio 17 2022.rst b/Help/generator/Visual Studio 17 2022.rst index edf9d60..ab101ac 100644 --- a/Help/generator/Visual Studio 17 2022.rst +++ b/Help/generator/Visual Studio 17 2022.rst @@ -25,7 +25,7 @@ The default target platform name (architecture) is that of the host and is provided in the :variable:`CMAKE_VS_PLATFORM_NAME_DEFAULT` variable. The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps -via the :manual:`cmake(1)` ``-A`` option, to specify a target platform +via the :option:`cmake -A` option, to specify a target platform name (architecture). For example: * ``cmake -G "Visual Studio 17 2022" -A Win32`` @@ -38,7 +38,7 @@ Toolset Selection The ``v143`` toolset that comes with VS 17 2022 is selected by default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps -via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. +via the :option:`cmake -T` option, to specify another toolset. .. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace:: By default this generator uses the 64-bit variant on x64 hosts and diff --git a/Help/generator/Visual Studio 9 2008.rst b/Help/generator/Visual Studio 9 2008.rst index 644f936..3434956 100644 --- a/Help/generator/Visual Studio 9 2008.rst +++ b/Help/generator/Visual Studio 9 2008.rst @@ -10,7 +10,7 @@ The default target platform name (architecture) is ``Win32``. .. versionadded:: 3.1 The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps - via the :manual:`cmake(1)` ``-A`` option, to specify a target platform + via the :option:`cmake -A` option, to specify a target platform name (architecture). For example: * ``cmake -G "Visual Studio 9 2008" -A Win32`` diff --git a/Help/generator/Xcode.rst b/Help/generator/Xcode.rst index e4900a1..fc7eea1 100644 --- a/Help/generator/Xcode.rst +++ b/Help/generator/Xcode.rst @@ -13,7 +13,7 @@ Toolset and Build System Selection By default Xcode is allowed to select its own default toolchain. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps -via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. +via the :option:`cmake -T` option, to specify another toolset. .. versionadded:: 3.19 This generator supports toolset specification using one of these forms: diff --git a/Help/guide/ide-integration/index.rst b/Help/guide/ide-integration/index.rst index 8473481..e198789 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 @@ -66,10 +67,9 @@ run: cmake -S /path/to/source -B /path/to/source/build -G Ninja In cases where a preset contains lots of cache variables, and passing all of -them as ``-D`` flags would cause the command line length limit of the platform -to be exceeded, the IDE should instead construct a temporary cache script and -pass it with the ``-C`` flag. See :ref:`CMake Options` for details on how the -``-C`` flag is used. +them as :option:`-D <cmake -D>` flags would cause the command line length limit +of the platform to be exceeded, the IDE should instead construct a temporary +cache script and pass it with the :option:`-C <cmake -C>` flag. While reading, parsing, and evaluating the contents of ``CMakePresets.json`` is straightforward, it is not trivial. In addition to the documentation, IDE @@ -110,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 5f0b27a..e3d8de0 100644 --- a/Help/guide/tutorial/Packaging an Installer.rst +++ b/Help/guide/tutorial/Packaging an Installer.rst @@ -38,15 +38,15 @@ binary directory run: cpack -To specify the generator, use the ``-G`` option. For multi-config builds, use -``-C`` to specify the configuration. For example: +To specify the generator, use the :option:`-G <cpack -G>` option. For multi-config builds, +use :option:`-C <cpack -C>` to specify the configuration. For example: .. code-block:: console 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 ba8196b..1c60d2d 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 -------------- @@ -153,13 +153,13 @@ platform. Usually, the default generator is sufficient to allow the user to proceed to build the software. The user may override the default generator with -the ``-G`` option: +the :option:`-G <cmake -G>` option: .. code-block:: console $ 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. @@ -196,7 +196,8 @@ VisualC++ compiler, or a combination of the two: $ cmake .. -G "Visual Studio 16 2019" Visual Studio generators can target different architectures. -One can specify the target architecture using the `-A` option: +One can specify the target architecture using the +:option:`-A <cmake -A>` option: .. code-block:: console @@ -214,8 +215,8 @@ generator to use, typically a choice between a ``Makefile`` or a ``Ninja`` based generator. Note that it is not possible to change the generator -with ``-G`` after the first invocation of CMake. To -change the generator, the build directory must be +with :option:`-G <cmake -G>` after the first invocation of CMake. +To change the generator, the build directory must be deleted and the build must be started from scratch. When generating Visual Studio project and solutions @@ -223,7 +224,7 @@ files several other options are available to use when initially running :manual:`cmake(1)`. The Visual Studio toolset can be specified with the -``-T`` option: +:option:`cmake -T` option: .. code-block:: console @@ -232,9 +233,9 @@ The Visual Studio toolset can be specified with the $ # Build targeting Windows XP $ cmake.exe .. -G "Visual Studio 16 2019" -A x64 -T v120_xp -Whereas the ``-A`` option specifies the _target_ -architecture, the ``-T`` option can be used to specify -details of the toolchain used. For example, `-Thost=x64` +Whereas the :option:`-A <cmake -A>` option specifies the _target_ +architecture, the :option:`-T <cmake -T>` option can be used to specify +details of the toolchain used. For example, ``-Thost=x64`` can be given to select the 64-bit version of the host tools. The following demonstrates how to use 64-bit tools and also build for a 64-bit target architecture: @@ -337,7 +338,7 @@ or later on a subsequent invocation of $ cd build $ cmake . -DCMAKE_BUILD_TYPE=Debug -The ``-U`` flag may be used to unset variables +The :option:`-U <cmake -U>` flag may be used to unset variables on the :manual:`cmake(1)` command line: .. code-block:: console @@ -351,7 +352,7 @@ on the command line can be modified using the The :manual:`cmake(1)` tool allows specifying a file to use to populate the initial cache using -the ``-C`` option. This can be useful to simplify +the :option:`-C <cmake -C>` option. This can be useful to simplify commands and scripts which repeatedly require the same cache entries. @@ -427,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 @@ -502,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: @@ -526,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. @@ -638,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. ===================== =========================== =========================== @@ -661,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 @@ -745,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 @@ -754,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/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt index 8e23b77..3868276 100644 --- a/Help/manual/OPTIONS_BUILD.txt +++ b/Help/manual/OPTIONS_BUILD.txt @@ -1,12 +1,15 @@ -``-S <path-to-source>`` +.. option:: -S <path-to-source> + Path to root directory of the CMake project to build. -``-B <path-to-build>`` +.. option:: -B <path-to-build> + Path to directory which CMake will use as the root of build directory. If the directory doesn't already exist CMake will make it. -``-C <initial-cache>`` +.. option:: -C <initial-cache> + Pre-load a script to populate the cache. When CMake is first run in an empty build tree, it creates a @@ -21,7 +24,8 @@ References to :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR` within the script evaluate to the top-level source and build tree. -``-D <var>:<type>=<value>, -D <var>=<value>`` +.. option:: -D <var>:<type>=<value>, -D <var>=<value> + Create or update a CMake ``CACHE`` entry. When CMake is first run in an empty build tree, it creates a @@ -41,7 +45,8 @@ This option may also be given as a single argument: ``-D<var>:<type>=<value>`` or ``-D<var>=<value>``. -``-U <globbing_expr>`` +.. option:: -U <globbing_expr> + Remove matching entries from CMake ``CACHE``. This option may be used to remove one or more variables from the @@ -51,7 +56,8 @@ Use with care, you can make your ``CMakeCache.txt`` non-working. -``-G <generator-name>`` +.. option:: -G <generator-name> + Specify a build system generator. CMake may support multiple native build systems on certain @@ -62,72 +68,84 @@ If not specified, CMake checks the :envvar:`CMAKE_GENERATOR` environment variable and otherwise falls back to a builtin default selection. -``-T <toolset-spec>`` +.. option:: -T <toolset-spec> + Toolset specification for the generator, if supported. Some CMake generators support a toolset specification to tell the native build system how to choose a compiler. See the :variable:`CMAKE_GENERATOR_TOOLSET` variable for details. -``-A <platform-name>`` +.. option:: -A <platform-name> + Specify platform name if supported by generator. Some CMake generators support a platform name to be given to the native build system to choose a compiler or SDK. See the :variable:`CMAKE_GENERATOR_PLATFORM` variable for details. -``--toolchain <path-to-file>`` +.. option:: --toolchain <path-to-file> + Specify the cross compiling toolchain file, equivalent to setting :variable:`CMAKE_TOOLCHAIN_FILE` variable. -``--install-prefix <directory>`` +.. option:: --install-prefix <directory> + Specify the installation directory, used by the :variable:`CMAKE_INSTALL_PREFIX` variable. Must be an absolute path. -``-Wno-dev`` +.. option:: -Wno-dev + Suppress developer warnings. Suppress warnings that are meant for the author of the ``CMakeLists.txt`` files. By default this will also turn off deprecation warnings. -``-Wdev`` +.. option:: -Wdev + Enable developer warnings. Enable warnings that are meant for the author of the ``CMakeLists.txt`` files. By default this will also turn on deprecation warnings. -``-Werror=dev`` +.. option:: -Werror=dev + Make developer warnings errors. Make warnings that are meant for the author of the ``CMakeLists.txt`` files errors. By default this will also turn on deprecated warnings as errors. -``-Wno-error=dev`` +.. option:: -Wno-error=dev + Make developer warnings not errors. Make warnings that are meant for the author of the ``CMakeLists.txt`` files not errors. By default this will also turn off deprecated warnings as errors. -``-Wdeprecated`` +.. option:: -Wdeprecated + Enable deprecated functionality warnings. Enable warnings for usage of deprecated functionality, that are meant for the author of the ``CMakeLists.txt`` files. -``-Wno-deprecated`` +.. option:: -Wno-deprecated + Suppress deprecated functionality warnings. Suppress warnings for usage of deprecated functionality, that are meant for the author of the ``CMakeLists.txt`` files. -``-Werror=deprecated`` +.. option:: -Werror=deprecated + Make deprecated macro and function warnings errors. Make warnings for usage of deprecated macros and functions, that are meant for the author of the ``CMakeLists.txt`` files, errors. -``-Wno-error=deprecated`` +.. option:: -Wno-error=deprecated + Make deprecated macro and function warnings not errors. Make warnings for usage of deprecated macros and functions, that are meant diff --git a/Help/manual/OPTIONS_HELP.txt b/Help/manual/OPTIONS_HELP.txt index feeca7d..92bdf1e 100644 --- a/Help/manual/OPTIONS_HELP.txt +++ b/Help/manual/OPTIONS_HELP.txt @@ -1,134 +1,154 @@ .. |file| replace:: The help is printed to a named <f>ile if given. -``--help,-help,-usage,-h,-H,/?`` +.. option:: --help, -help, -usage, -h, -H, /? + Print usage information and exit. Usage describes the basic command line interface and its options. -``--version,-version,/V [<f>]`` +.. option:: --version, -version, /V [<f>] + Show program name/version banner and exit. If a file is specified, the version is written into it. |file| -``--help-full [<f>]`` +.. option:: --help-full [<f>] + Print all help manuals and exit. All manuals are printed in a human-readable text format. |file| -``--help-manual <man> [<f>]`` +.. option:: --help-manual <man> [<f>] + Print one help manual and exit. The specified manual is printed in a human-readable text format. |file| -``--help-manual-list [<f>]`` +.. option:: --help-manual-list [<f>] + List help manuals available and exit. The list contains all manuals for which help may be obtained by using the ``--help-manual`` option followed by a manual name. |file| -``--help-command <cmd> [<f>]`` +.. option:: --help-command <cmd> [<f>] + Print help for one command and exit. The :manual:`cmake-commands(7)` manual entry for ``<cmd>`` is printed in a human-readable text format. |file| -``--help-command-list [<f>]`` +.. option:: --help-command-list [<f>] + List commands with help available and exit. The list contains all commands for which help may be obtained by using the ``--help-command`` option followed by a command name. |file| -``--help-commands [<f>]`` +.. option:: --help-commands [<f>] + Print cmake-commands manual and exit. The :manual:`cmake-commands(7)` manual is printed in a human-readable text format. |file| -``--help-module <mod> [<f>]`` +.. option:: --help-module <mod> [<f>] + Print help for one module and exit. The :manual:`cmake-modules(7)` manual entry for ``<mod>`` is printed in a human-readable text format. |file| -``--help-module-list [<f>]`` +.. option:: --help-module-list [<f>] + List modules with help available and exit. The list contains all modules for which help may be obtained by using the ``--help-module`` option followed by a module name. |file| -``--help-modules [<f>]`` +.. option:: --help-modules [<f>] + Print cmake-modules manual and exit. The :manual:`cmake-modules(7)` manual is printed in a human-readable text format. |file| -``--help-policy <cmp> [<f>]`` +.. option:: --help-policy <cmp> [<f>] + Print help for one policy and exit. The :manual:`cmake-policies(7)` manual entry for ``<cmp>`` is printed in a human-readable text format. |file| -``--help-policy-list [<f>]`` +.. option:: --help-policy-list [<f>] + List policies with help available and exit. The list contains all policies for which help may be obtained by using the ``--help-policy`` option followed by a policy name. |file| -``--help-policies [<f>]`` +.. option:: --help-policies [<f>] + Print cmake-policies manual and exit. The :manual:`cmake-policies(7)` manual is printed in a human-readable text format. |file| -``--help-property <prop> [<f>]`` +.. option:: --help-property <prop> [<f>] + Print help for one property and exit. The :manual:`cmake-properties(7)` manual entries for ``<prop>`` are printed in a human-readable text format. |file| -``--help-property-list [<f>]`` +.. option:: --help-property-list [<f>] + List properties with help available and exit. The list contains all properties for which help may be obtained by using the ``--help-property`` option followed by a property name. |file| -``--help-properties [<f>]`` +.. option:: --help-properties [<f>] + Print cmake-properties manual and exit. The :manual:`cmake-properties(7)` manual is printed in a human-readable text format. |file| -``--help-variable <var> [<f>]`` +.. option:: --help-variable <var> [<f>] + Print help for one variable and exit. The :manual:`cmake-variables(7)` manual entry for ``<var>`` is printed in a human-readable text format. |file| -``--help-variable-list [<f>]`` +.. option:: --help-variable-list [<f>] + List variables with help available and exit. The list contains all variables for which help may be obtained by using the ``--help-variable`` option followed by a variable name. |file| -``--help-variables [<f>]`` +.. option:: --help-variables [<f>] + Print cmake-variables manual and exit. The :manual:`cmake-variables(7)` manual is printed in a diff --git a/Help/manual/ccmake.1.rst b/Help/manual/ccmake.1.rst index 60d45a3..bc411a4 100644 --- a/Help/manual/ccmake.1.rst +++ b/Help/manual/ccmake.1.rst @@ -27,6 +27,8 @@ native tool on their platform. Options ======= +.. program:: ccmake + .. include:: OPTIONS_BUILD.txt .. include:: OPTIONS_HELP.txt diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index 034e218..ed5bbbf 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 ``-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-gui.1.rst b/Help/manual/cmake-gui.1.rst index 281986f..493b625 100644 --- a/Help/manual/cmake-gui.1.rst +++ b/Help/manual/cmake-gui.1.rst @@ -29,19 +29,25 @@ native tool on their platform. Options ======= -``-S <path-to-source>`` +.. program:: cmake-gui + +.. option:: -S <path-to-source> + Path to root directory of the CMake project to build. -``-B <path-to-build>`` +.. option:: -B <path-to-build> + Path to directory which CMake will use as the root of build directory. If the directory doesn't already exist CMake will make it. -``--preset=<preset-name>`` +.. option:: --preset=<preset-name> + Name of the preset to use from the project's :manual:`presets <cmake-presets(7)>` files, if it has them. -``--browse-manual`` +.. option:: --browse-manual + Open the CMake reference manual in a browser and immediately exit. .. include:: OPTIONS_HELP.txt diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst index a96c704..290c2ba 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 @@ -198,9 +198,9 @@ that may contain the following fields: or above, this field may be omitted to fall back to regular generator discovery procedure. - Note that for Visual Studio generators, unlike in the command line ``-G`` - argument, you cannot include the platform name in the generator name. Use - the ``architecture`` field instead. + Note that for Visual Studio generators, unlike in the command line + :option:`-G <cmake -G>` argument, you cannot include the platform name + in the generator name. Use the ``architecture`` field instead. ``architecture``, ``toolset`` @@ -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 2726f13..ff6ae80 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -96,9 +96,10 @@ 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. - Optionally use the ``-G`` option below to specify a generator, or simply - accept the default CMake chooses for the current platform. + 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. When using one of the :ref:`Command-Line Build Tool Generators` CMake expects that the environment needed by the compiler toolchain @@ -152,11 +153,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 ``-S`` or ``-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 :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: ============================== ============ =========== Command Line Source Dir Build Dir @@ -195,47 +196,55 @@ automatically choosing and invoking the appropriate native build tool. Options ------- +.. program:: cmake + .. include:: OPTIONS_BUILD.txt -``--fresh`` +.. option:: --fresh + .. versionadded:: 3.24 Perform a fresh configuration of the build tree. This removes any existing ``CMakeCache.txt`` file and associated ``CMakeFiles/`` directory, and recreates them from scratch. -``-L[A][H]`` +.. option:: -L[A][H] + 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 ``-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 + 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. -``-N`` +.. option:: -N + View mode only. Only load the cache. Do not actually run configure and generate steps. -``--graphviz=[file]`` +.. option:: --graphviz=<file> + Generate graphviz of dependencies, see :module:`CMakeGraphVizOptions` for more. Generate a graphviz input file that will contain all the library and executable dependencies in the project. See the documentation for :module:`CMakeGraphVizOptions` for more details. -``--system-information [file]`` +.. option:: --system-information [file] + Dump information about this system. Dump a wide range of information about the current system. If run from the top of a binary tree for a CMake project it will dump additional information such as the cache, log files etc. -``--log-level=<ERROR|WARNING|NOTICE|STATUS|VERBOSE|DEBUG|TRACE>`` +.. option:: --log-level=<ERROR|WARNING|NOTICE|STATUS|VERBOSE|DEBUG|TRACE> + Set the log level. The :command:`message` command will only output messages of the specified @@ -250,11 +259,11 @@ Options synonym for this option. .. versionadded:: 3.25 - See the :command:`cmake_language` - :ref:`cmake_language <query_message_log_level>` command for a way to query - the current message logging level. + See the :command:`cmake_language` command for a way to + :ref:`query the current message logging level <query_message_log_level>`. + +.. option:: --log-context -``--log-context`` Enable the :command:`message` command outputting context attached to each message. @@ -264,7 +273,8 @@ Options When this command line option is given, :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` is ignored. -``--debug-trycompile`` +.. option:: --debug-trycompile + Do not delete the :command:`try_compile` build tree. Only useful on one :command:`try_compile` at a time. @@ -275,13 +285,15 @@ Options fail incorrectly. This option is best used for one try-compile at a time, and only when debugging. -``--debug-output`` +.. option:: --debug-output + Put cmake in a debug mode. Print extra information during the cmake run like stack traces with :command:`message(SEND_ERROR)` calls. -``--debug-find`` +.. option:: --debug-find + Put cmake find commands in a debug mode. Print extra find call information during the cmake run to standard @@ -289,32 +301,39 @@ Options See also the :variable:`CMAKE_FIND_DEBUG_MODE` variable for debugging a more local part of the project. -``--debug-find-pkg=<pkg>[,...]`` +.. option:: --debug-find-pkg=<pkg>[,...] + Put cmake find commands in a debug mode when running under calls to :command:`find_package(\<pkg\>) <find_package>`, where ``<pkg>`` is an entry in the given comma-separated list of case-sensitive package names. - Like ``--debug-find``, but limiting scope to the specified packages. + Like :option:`--debug-find <cmake --debug-find>`, but limiting scope + to the specified packages. + +.. option:: --debug-find-var=<var>[,...] -``--debug-find-var=<var>[,...]`` Put cmake find commands in a debug mode when called with ``<var>`` as the result variable, where ``<var>`` is an entry in the given comma-separated list. - Like ``--debug-find``, but limiting scope to the specified variable names. + Like :option:`--debug-find <cmake --debug-find>`, but limiting scope + to the specified variable names. + +.. option:: --trace -``--trace`` Put cmake in trace mode. Print a trace of all calls made and from where. -``--trace-expand`` +.. option:: --trace-expand + Put cmake in trace mode. - Like ``--trace``, but with variables expanded. + Like :option:`--trace <cmake --trace>`, but with variables expanded. + +.. option:: --trace-format=<format> -``--trace-format=<format>`` Put cmake in trace mode and sets the trace output format. ``<format>`` can be one of the following values. @@ -400,46 +419,57 @@ Options Indicates the version of the JSON format. The version has a major and minor components following semantic version conventions. -``--trace-source=<file>`` +.. option:: --trace-source=<file> + Put cmake in trace mode, but output only lines of a specified file. Multiple options are allowed. -``--trace-redirect=<file>`` +.. option:: --trace-redirect=<file> + Put cmake in trace mode and redirect trace output to a file instead of stderr. -``--warn-uninitialized`` +.. option:: --warn-uninitialized + Warn about uninitialized values. Print a warning when an uninitialized variable is used. -``--warn-unused-vars`` +.. option:: --warn-unused-vars + Does nothing. In CMake versions 3.2 and below this enabled warnings about unused variables. In CMake versions 3.3 through 3.18 the option was broken. In CMake 3.19 and above the option has been removed. -``--no-warn-unused-cli`` +.. option:: --no-warn-unused-cli + Don't warn about command line options. Don't find variables that are declared on the command line, but not used. -``--check-system-vars`` +.. option:: --check-system-vars + Find problems with variable usage in system files. Normally, unused and uninitialized variables are searched for only in :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR`. This flag tells CMake to warn about other files as well. -``--compile-no-warning-as-error`` +.. option:: --compile-no-warning-as-error + Ignore target property :prop_tgt:`COMPILE_WARNING_AS_ERROR` and variable :variable:`CMAKE_COMPILE_WARNING_AS_ERROR`, preventing warnings from being treated as errors on compile. -``--profiling-output=<path>`` - Used in conjunction with ``--profiling-format`` to output to a given path. +.. option:: --profiling-output=<path> + + Used in conjunction with + :option:`--profiling-format <cmake --profiling-format>` to output to a + given path. + +.. option:: --profiling-format=<file> -``--profiling-format=<file>`` Enable the output of profiling data of CMake script in the given format. This can aid performance analysis of CMake scripts executed. Third party @@ -450,7 +480,8 @@ Options about:tracing tab of Google Chrome or using a plugin for a tool like Trace Compass. -``--preset <preset>``, ``--preset=<preset>`` +.. option:: --preset <preset>, --preset=<preset> + Reads a :manual:`preset <cmake-presets(7)>` from ``<path-to-source>/CMakePresets.json`` and ``<path-to-source>/CMakeUserPresets.json``. The preset may specify the @@ -466,7 +497,8 @@ Options a variable called ``MYVAR`` to ``1``, but the user sets it to ``2`` with a ``-D`` argument, the value ``2`` is preferred. -``--list-presets, --list-presets=<[configure | build | test | all]>`` +.. option:: --list-presets, --list-presets=<[configure | build | test | all]> + Lists the available presets. If no option is specified only configure presets will be listed. The current working directory must contain CMake preset files. @@ -486,21 +518,25 @@ project binary tree: This abstracts a native build tool's command-line interface with the following options: -``--build <dir>`` +.. option:: --build <dir> + Project binary directory to be built. This is required (unless a preset is specified) and must be first. -``--preset <preset>``, ``--preset=<preset>`` +.. option:: --preset <preset>, --preset=<preset> + Use a build preset to specify build options. The project binary directory is inferred from the ``configurePreset`` key. The current working directory must contain CMake preset files. See :manual:`preset <cmake-presets(7)>` for more details. -``--list-presets`` +.. option:: --list-presets + Lists the available build presets. The current working directory must contain CMake preset files. -``--parallel [<jobs>], -j [<jobs>]`` +.. option:: --parallel [<jobs>], -j [<jobs>] + The maximum number of concurrent processes to use when building. If ``<jobs>`` is omitted the native build tool's default number is used. @@ -510,18 +546,22 @@ following options: Some native build tools always build in parallel. The use of ``<jobs>`` value of ``1`` can be used to limit to a single job. -``--target <tgt>..., -t <tgt>...`` +.. option:: --target <tgt>..., -t <tgt>... + Build ``<tgt>`` instead of the default target. Multiple targets may be given, separated by spaces. -``--config <cfg>`` +.. option:: --config <cfg> + For multi-configuration tools, choose configuration ``<cfg>``. -``--clean-first`` +.. 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> -``--resolve-package-references=<on|off|only>`` .. versionadded:: 3.23 Resolve remote package references from external package managers (e.g. NuGet) @@ -544,10 +584,12 @@ following options: are restored using NuGet. It can be disabled by setting the ``CMAKE_VS_NUGET_PACKAGE_RESTORE`` variable to ``OFF``. -``--use-stderr`` +.. option:: --use-stderr + Ignored. Behavior is default in CMake >= 3.0. -``--verbose, -v`` +.. option:: -v, --verbose + Enable verbose output - if supported - including the build commands to be executed. @@ -555,10 +597,11 @@ following options: :variable:`CMAKE_VERBOSE_MAKEFILE` cached variable is set. -``--`` +.. option:: -- + 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 ================= @@ -574,30 +617,37 @@ This may be used after building a project to run installation without using the generated build system or the native build tool. The options are: -``--install <dir>`` +.. option:: --install <dir> + Project binary directory to install. This is required and must be first. -``--config <cfg>`` +.. option:: --config <cfg> + For multi-configuration generators, choose configuration ``<cfg>``. -``--component <comp>`` +.. option:: --component <comp> + Component-based install. Only install component ``<comp>``. -``--default-directory-permissions <permissions>`` +.. option:: --default-directory-permissions <permissions> + Default directory install permissions. Permissions in format ``<u=rwx,g=rx,o=rx>``. -``--prefix <prefix>`` +.. option:: --prefix <prefix> + Override the installation prefix, :variable:`CMAKE_INSTALL_PREFIX`. -``--strip`` +.. option:: --strip + Strip before installing. -``-v, --verbose`` +.. option:: -v, --verbose + Enable verbose output. 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 ============== @@ -615,14 +665,22 @@ supported by some generators. Run a Script ============ +.. program:: cmake_P + .. code-block:: shell cmake [{-D <var>=<value>}...] -P <cmake-script-file> [-- <unparsed-options>...] -Process the given cmake file as a script written in the CMake -language. No configure or generate step is performed and the cache -is not modified. If variables are defined using ``-D``, this must be -done before the ``-P`` argument. +.. option:: -D <var>=<value> + + Define a variable for script mode. + +.. option:: -P <cmake-script-file> + + Process the given cmake file as a script written in the CMake + language. No configure or generate step is performed and the cache + is not modified. If variables are defined using ``-D``, this must be + done before the ``-P`` argument. Any options after ``--`` are not parsed by CMake, but they are still included in the set of :variable:`CMAKE_ARGV<n> <CMAKE_ARGV0>` variables passed to the @@ -634,16 +692,22 @@ script (including the ``--`` itself). Run a Command-Line Tool ======================= +.. program:: cmake_E + CMake provides builtin command-line tools through the signature .. code-block:: shell 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: -``capabilities`` +.. option:: capabilities + .. versionadded:: 3.7 Report cmake capabilities in JSON format. The output is a JSON object @@ -653,7 +717,7 @@ Available commands are: A JSON object with version information. Keys are: ``string`` - The full version string as displayed by cmake ``--version``. + The full version string as displayed by cmake :option:`--version <cmake --version>`. ``major`` The major version number in integer form. ``minor`` @@ -680,7 +744,8 @@ Available commands are: Optional member that may be present when the generator supports platform specification via :variable:`CMAKE_GENERATOR_PLATFORM` - (``-A ...``). The value is a list of platforms known to be supported. + (:option:`-A ... <cmake -A>`). The value is a list of platforms known to + be supported. ``extraGenerators`` A list of strings with all the extra generators compatible with the generator. @@ -705,7 +770,8 @@ Available commands are: ``true`` if cmake supports server-mode and ``false`` otherwise. Always false since CMake 3.20. -``cat [--] <files>...`` +.. option:: cat [--] <files>... + .. versionadded:: 3.18 Concatenate files and print on the standard output. @@ -716,10 +782,12 @@ Available commands are: ``-`` will result in an error. Use ``--`` to indicate the end of options, in case a file starts with ``-``. -``chdir <dir> <cmd> [<arg>...]`` +.. option:: chdir <dir> <cmd> [<arg>...] + Change the current working directory and run a command. -``compare_files [--ignore-eol] <file1> <file2>`` +.. option:: compare_files [--ignore-eol] <file1> <file2> + Check if ``<file1>`` is same as ``<file2>``. If files are the same, then returns ``0``, if not it returns ``1``. In case of invalid arguments, it returns 2. @@ -728,7 +796,8 @@ Available commands are: The ``--ignore-eol`` option implies line-wise comparison and ignores LF/CRLF differences. -``copy <file>... <destination>`` +.. option:: copy <file>... <destination> + Copy files to ``<destination>`` (either file or directory). If multiple files are specified, the ``<destination>`` must be directory and it must exist. Wildcards are not supported. @@ -738,7 +807,8 @@ Available commands are: .. versionadded:: 3.5 Support for multiple input files. -``copy_directory <dir>... <destination>`` +.. option:: copy_directory <dir>... <destination> + Copy content of ``<dir>...`` directories to ``<destination>`` directory. If ``<destination>`` directory does not exist it will be created. ``copy_directory`` does follow symlinks. @@ -750,7 +820,8 @@ Available commands are: The command now fails when the source directory does not exist. Previously it succeeded by creating an empty destination directory. -``copy_if_different <file>... <destination>`` +.. option:: copy_if_different <file>... <destination> + Copy files to ``<destination>`` (either file or directory) if they have changed. If multiple files are specified, the ``<destination>`` must be @@ -760,7 +831,8 @@ Available commands are: .. versionadded:: 3.5 Support for multiple input files. -``create_symlink <old> <new>`` +.. option:: create_symlink <old> <new> + Create a symbolic link ``<new>`` naming ``<old>``. .. versionadded:: 3.13 @@ -769,7 +841,8 @@ Available commands are: .. note:: Path to where ``<new>`` symbolic link will be created has to exist beforehand. -``create_hardlink <old> <new>`` +.. option:: create_hardlink <old> <new> + .. versionadded:: 3.19 Create a hard link ``<new>`` naming ``<old>``. @@ -778,13 +851,16 @@ Available commands are: Path to where ``<new>`` hard link will be created has to exist beforehand. ``<old>`` has to exist beforehand. -``echo [<string>...]`` +.. option:: echo [<string>...] + Displays arguments as text. -``echo_append [<string>...]`` +.. option:: echo_append [<string>...] + Displays arguments as text but no new line. -``env [--unset=NAME ...] [NAME=VALUE ...] [--] <command> [<arg>...]`` +.. option:: env [--unset=NAME ...] [NAME=VALUE ...] [--] <command> [<arg>...] + .. versionadded:: 3.1 Run command in a modified environment. @@ -794,15 +870,18 @@ Available commands are: interpreting options/environment variables and treat the next argument as the command, even if it start with ``-`` or contains a ``=``. -``environment`` +.. option:: environment + Display the current environment variables. -``false`` +.. option:: false + .. versionadded:: 3.16 Do nothing, with an exit code of 1. -``make_directory <dir>...`` +.. option:: make_directory <dir>... + Create ``<dir>`` directories. If necessary, create parent directories too. If a directory already exists it will be silently ignored. @@ -810,13 +889,15 @@ Available commands are: .. versionadded:: 3.5 Support for multiple input directories. -``md5sum <file>...`` +.. option:: md5sum <file>... + Create MD5 checksum of files in ``md5sum`` compatible format:: 351abe79cd3800b38cdfb25d45015a15 file1.txt 052f86c15bbde68af55c7f7b340ab639 file2.txt -``sha1sum <file>...`` +.. option:: sha1sum <file>... + .. versionadded:: 3.10 Create SHA1 checksum of files in ``sha1sum`` compatible format:: @@ -824,7 +905,8 @@ Available commands are: 4bb7932a29e6f73c97bb9272f2bdc393122f86e0 file1.txt 1df4c8f318665f9a5f2ed38f55adadb7ef9f559c file2.txt -``sha224sum <file>...`` +.. option:: sha224sum <file>... + .. versionadded:: 3.10 Create SHA224 checksum of files in ``sha224sum`` compatible format:: @@ -832,7 +914,8 @@ Available commands are: b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930 file1.txt 6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24 file2.txt -``sha256sum <file>...`` +.. option:: sha256sum <file>... + .. versionadded:: 3.10 Create SHA256 checksum of files in ``sha256sum`` compatible format:: @@ -840,7 +923,8 @@ Available commands are: 76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc file1.txt 15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea file2.txt -``sha384sum <file>...`` +.. option:: sha384sum <file>... + .. versionadded:: 3.10 Create SHA384 checksum of files in ``sha384sum`` compatible format:: @@ -848,7 +932,8 @@ Available commands are: acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434 file1.txt 668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d file2.txt -``sha512sum <file>...`` +.. option:: sha512sum <file>... + .. versionadded:: 3.10 Create SHA512 checksum of files in ``sha512sum`` compatible format:: @@ -856,7 +941,8 @@ Available commands are: 2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89 file1.txt 7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d file2.txt -``remove [-f] <file>...`` +.. option:: remove [-f] <file>... + .. deprecated:: 3.17 Remove the file(s). The planned behavior was that if any of the @@ -869,7 +955,8 @@ Available commands are: The implementation was buggy and always returned 0. It cannot be fixed without breaking backwards compatibility. Use ``rm`` instead. -``remove_directory <dir>...`` +.. option:: remove_directory <dir>... + .. deprecated:: 3.17 Remove ``<dir>`` directories and their contents. If a directory does @@ -882,11 +969,13 @@ Available commands are: .. versionadded:: 3.16 If ``<dir>`` is a symlink to a directory, just the symlink will be removed. -``rename <oldname> <newname>`` +.. option:: rename <oldname> <newname> + Rename a file or directory (on one volume). If file with the ``<newname>`` name already exists, then it will be silently replaced. -``rm [-rRf] [--] <file|dir>...`` +.. option:: rm [-rRf] [--] <file|dir>... + .. versionadded:: 3.17 Remove the files ``<file>`` or directories ``<dir>``. @@ -897,15 +986,18 @@ Available commands are: situations instead. Use ``--`` to stop interpreting options and treat all remaining arguments as paths, even if they start with ``-``. -``server`` +.. option:: server + Launch :manual:`cmake-server(7)` mode. -``sleep <number>...`` +.. option:: sleep <number>... + .. versionadded:: 3.0 Sleep for given number of seconds. -``tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]`` +.. option:: tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...] + Create or extract a tar or zip archive. Options are: ``c`` @@ -988,7 +1080,8 @@ Available commands are: ``tar`` tool. The command now also parses all flags, and if an invalid flag was provided, a warning is issued. -``time <command> [<args>...]`` +.. option:: time <command> [<args>...] + Run command and display elapsed time. .. versionadded:: 3.5 @@ -996,15 +1089,18 @@ Available commands are: through to the child process. This may break scripts that worked around the bug with their own extra quoting or escaping. -``touch <file>...`` +.. option:: touch <file>... + Creates ``<file>`` if file do not exist. If ``<file>`` exists, it is changing ``<file>`` access and modification times. -``touch_nocreate <file>...`` +.. option:: touch_nocreate <file>... + Touch a file if it exists but do not create it. If a file does not exist it will be silently ignored. -``true`` +.. option:: true + .. versionadded:: 3.16 Do nothing, with an exit code of 0. @@ -1014,22 +1110,26 @@ Windows-specific Command-Line Tools The following ``cmake -E`` commands are available only on Windows: -``delete_regv <key>`` +.. option:: delete_regv <key> + Delete Windows registry value. -``env_vs8_wince <sdkname>`` +.. option:: env_vs8_wince <sdkname> + .. versionadded:: 3.2 Displays a batch file which sets the environment for the provided Windows CE SDK installed in VS2005. -``env_vs9_wince <sdkname>`` +.. option:: env_vs9_wince <sdkname> + .. versionadded:: 3.2 Displays a batch file which sets the environment for the provided Windows CE SDK installed in VS2008. -``write_regv <key> <value>`` +.. option:: write_regv <key> <value> + Write Windows registry value. @@ -1063,6 +1163,8 @@ To print selected pages from the CMake documentation, use with one of the following options: +.. program:: cmake + .. include:: OPTIONS_HELP.txt To view the presets available for a project, use diff --git a/Help/manual/cpack.1.rst b/Help/manual/cpack.1.rst index 395cd41..4861e95 100644 --- a/Help/manual/cpack.1.rst +++ b/Help/manual/cpack.1.rst @@ -26,12 +26,12 @@ 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 ``-G``. +or through the command-line option :option:`-G <cpack -G>`. The **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 ``--config``, the file ``CPackConfig.cmake`` -in the current directory is used. +through the command-line option :option:`--config <cpack --config>`, the +file ``CPackConfig.cmake`` in the current directory is used. In the standard CMake workflow, the file ``CPackConfig.cmake`` is generated by the :manual:`cmake <cmake(1)>` executable, provided the :module:`CPack` @@ -40,7 +40,10 @@ module is included by the project's ``CMakeLists.txt`` file. Options ======= -``-G <generators>`` +.. program:: cpack + +.. option:: -G <generators> + ``<generators>`` is a :ref:`semicolon-separated list <CMake Language Lists>` of generator names. ``cpack`` will iterate through this list and produce package(s) in that generator's format according to the details provided in @@ -48,7 +51,8 @@ Options the :variable:`CPACK_GENERATOR` variable determines the default set of generators that will be used. -``-C <configs>`` +.. option:: -C <configs> + Specify the project configuration(s) to be packaged (e.g. ``Debug``, ``Release``, etc.), where ``<configs>`` is a :ref:`semicolon-separated list <CMake Language Lists>`. @@ -58,36 +62,44 @@ Options The user is responsible for ensuring that the configuration(s) listed have already been built before invoking ``cpack``. -``-D <var>=<value>`` +.. option:: -D <var>=<value> + Set a CPack variable. This will override any value set for ``<var>`` in the input file read by ``cpack``. -``--config <configFile>`` +.. option:: --config <configFile> + Specify the configuration file read by ``cpack`` to provide the packaging details. By default, ``CPackConfig.cmake`` in the current directory will be used. -``--verbose, -V`` +.. option:: --verbose, -V + Run ``cpack`` with verbose output. This can be used to show more details from the package generation tools and is suitable for project developers. -``--debug`` +.. option:: --debug + Run ``cpack`` with debug output. This option is intended mainly for the developers of ``cpack`` itself and is not normally needed by project developers. -``--trace`` +.. option:: --trace + Put the underlying cmake scripts in trace mode. -``--trace-expand`` +.. option:: --trace-expand + Put the underlying cmake scripts in expanded trace mode. -``-P <packageName>`` +.. option:: -P <packageName> + Override/define the value of the :variable:`CPACK_PACKAGE_NAME` variable used for packaging. Any value set for this variable in the ``CPackConfig.cmake`` file will then be ignored. -``-R <packageVersion>`` +.. option:: -R <packageVersion> + Override/define the value of the :variable:`CPACK_PACKAGE_VERSION` variable used for packaging. It will override a value set in the ``CPackConfig.cmake`` file or one automatically computed from @@ -95,14 +107,16 @@ Options :variable:`CPACK_PACKAGE_VERSION_MINOR` and :variable:`CPACK_PACKAGE_VERSION_PATCH`. -``-B <packageDirectory>`` +.. option:: -B <packageDirectory> + Override/define :variable:`CPACK_PACKAGE_DIRECTORY`, which controls the directory where CPack will perform its packaging work. The resultant package(s) will be created at this location by default and a ``_CPack_Packages`` subdirectory will also be created below this directory to use as a working area during package creation. -``--vendor <vendorName>`` +.. option:: --vendor <vendorName> + Override/define :variable:`CPACK_PACKAGE_VENDOR`. .. include:: OPTIONS_HELP.txt diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 06f0d4e..c85982c 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -30,17 +30,23 @@ This program will run the tests and report results. Options ======= -``--preset <preset>``, ``--preset=<preset>`` +.. program:: ctest + + +.. option:: --preset <preset>, --preset=<preset> + Use a test preset to specify test options. The project binary directory is inferred from the ``configurePreset`` key. The current working directory must contain CMake preset files. See :manual:`preset <cmake-presets(7)>` for more details. -``--list-presets`` +.. option:: --list-presets + Lists the available test presets. The current working directory must contain CMake preset files. -``-C <cfg>, --build-config <cfg>`` +.. option:: -C <cfg>, --build-config <cfg> + Choose configuration to test. Some CMake-generated build trees can have multiple build @@ -48,7 +54,8 @@ Options which one should be tested. Example configurations are ``Debug`` and ``Release``. -``--progress`` +.. option:: --progress + Enable short progress output from tests. When the output of **ctest** is being sent directly to a terminal, the @@ -61,40 +68,46 @@ Options This option can also be enabled by setting the environment variable :envvar:`CTEST_PROGRESS_OUTPUT`. -``-V,--verbose`` +.. option:: -V, --verbose + Enable verbose output from tests. Test output is normally suppressed and only summary information is displayed. This option will show all test output. -``-VV,--extra-verbose`` +.. option:: -VV, --extra-verbose Enable more verbose output from tests. Test output is normally suppressed and only summary information is displayed. This option will show even more test output. -``--debug`` +.. option:: --debug + Displaying more verbose internals of CTest. This feature will result in a large number of output that is mostly useful for debugging dashboard problems. -``--output-on-failure`` +.. option:: --output-on-failure + Output anything outputted by the test program if the test should fail. This option can also be enabled by setting the :envvar:`CTEST_OUTPUT_ON_FAILURE` environment variable -``--stop-on-failure`` +.. option:: --stop-on-failure + Stop running the tests when the first failure happens. -``-F`` +.. option:: -F + Enable failover. This option allows CTest to resume a test set execution that was previously interrupted. If no interruption occurred, the ``-F`` option will have no effect. -``-j <jobs>, --parallel <jobs>`` +.. option:: -j <jobs>, --parallel <jobs> + Run the tests in parallel using the given number of jobs. This option tells CTest to run the tests in parallel using given @@ -105,7 +118,8 @@ Options See `Label and Subproject Summary`_. -``--resource-spec-file <file>`` +.. option:: --resource-spec-file <file> + Run CTest with :ref:`resource allocation <ctest-resource-allocation>` enabled, using the :ref:`resource specification file <ctest-resource-specification-file>` @@ -114,40 +128,47 @@ Options When ``ctest`` is run as a `Dashboard Client`_ this sets the ``ResourceSpecFile`` option of the `CTest Test Step`_. -``--test-load <level>`` - While running tests in parallel (e.g. with ``-j``), try not to start - tests when they may cause the CPU load to pass above a given threshold. +.. 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. When ``ctest`` is run as a `Dashboard Client`_ this sets the ``TestLoad`` option of the `CTest Test Step`_. -``-Q,--quiet`` +.. option:: -Q, --quiet Make CTest quiet. This option will suppress all the output. The output log file will - still be generated if the ``--output-log`` is specified. Options such - as ``--verbose``, ``--extra-verbose``, and ``--debug`` are ignored + 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 if ``--quiet`` is specified. -``-O <file>, --output-log <file>`` +.. option:: -O <file>, --output-log <file> + Output to log file. This option tells CTest to write all its output to a ``<file>`` log file. -``--output-junit <file>`` +.. option:: --output-junit <file> + Write test results in JUnit format. 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 - ``-S`` option to run a dashboard script, use the ``OUTPUT_JUNIT`` keyword - with the :command:`ctest_test` command instead. + :option:`-S <ctest -S>` option to run a dashboard script, use the + ``OUTPUT_JUNIT`` keyword with the :command:`ctest_test` command instead. + +.. option:: -N, --show-only[=<format>] -``-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 ``-R`` and ``-E`` - options. + actually run them. Useful in conjunction with the :option:`-R <ctest -R>` + and :option:`-E <ctest -E>` options. ``<format>`` can be one of the following values. @@ -159,7 +180,8 @@ Options Dump the test information in JSON format. See `Show as JSON Object Model`_. -``-L <regex>, --label-regex <regex>`` +.. option:: -L <regex>, --label-regex <regex> + Run tests with labels matching regular expression as described under :ref:`string(REGEX) <Regex Specification>`. @@ -169,19 +191,22 @@ Options of the test's labels (i.e. the multiple ``-L`` labels form an ``AND`` relationship). See `Label Matching`_. -``-R <regex>, --tests-regex <regex>`` +.. option:: -R <regex>, --tests-regex <regex> + Run tests matching regular expression. This option tells CTest to run only the tests whose names match the given regular expression. -``-E <regex>, --exclude-regex <regex>`` +.. option:: -E <regex>, --exclude-regex <regex> + Exclude tests matching regular expression. This option tells CTest to NOT run the tests whose names match the given regular expression. -``-LE <regex>, --label-exclude <regex>`` +.. option:: -LE <regex>, --label-exclude <regex> + Exclude tests with labels matching regular expression. This option tells CTest to NOT run the tests whose labels match the @@ -190,7 +215,8 @@ Options of the test's labels (i.e. the multiple ``-LE`` labels form an ``AND`` relationship). See `Label Matching`_. -``-FA <regex>, --fixture-exclude-any <regex>`` +.. option:: -FA <regex>, --fixture-exclude-any <regex> + Exclude fixtures matching ``<regex>`` from automatically adding any tests to the test set. @@ -201,13 +227,18 @@ Options including test dependencies and skipping tests that have fixture setup tests that fail. -``-FS <regex>, --fixture-exclude-setup <regex>`` - Same as ``-FA`` except only matching setup tests are excluded. +.. option:: -FS <regex>, --fixture-exclude-setup <regex> + + Same as :option:`-FA <ctest -FA>` except only matching setup tests are + excluded. + +.. option:: -FC <regex>, --fixture-exclude-cleanup <regex> -``-FC <regex>, --fixture-exclude-cleanup <regex>`` - Same as ``-FA`` except only matching cleanup tests are excluded. + Same as :option:`-FA <ctest -FA>` except only matching cleanup tests are + excluded. + +.. option:: -D <dashboard>, --dashboard <dashboard> -``-D <dashboard>, --dashboard <dashboard>`` Execute dashboard test. This option tells CTest to act as a CDash client and perform a @@ -218,55 +249,63 @@ Options See `Dashboard Client`_. -``-D <var>:<type>=<value>`` +.. option:: -D <var>:<type>=<value> + Define a variable for script mode. Pass in variable values on the command line. Use in conjunction - with ``-S`` to pass variable values to a dashboard script. Parsing ``-D`` - arguments as variable values is only attempted if the value + with :option:`-S <ctest -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. -``-M <model>, --test-model <model>`` +.. option:: -M <model>, --test-model <model> + Sets the model for a dashboard. This option tells CTest to act as a CDash client where the ``<model>`` can be ``Experimental``, ``Nightly``, and ``Continuous``. - Combining ``-M`` and ``-T`` is similar to ``-D``. + Combining ``-M`` and :option:`-T <ctest -T>` is similar to + :option:`-D <ctest -D>`. See `Dashboard Client`_. -``-T <action>, --test-action <action>`` +.. option:: -T <action>, --test-action <action> + Sets the dashboard action to perform. 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 ``-M`` and ``-T`` is similar to ``-D``. + Combining :option:`-M <ctest -M>` and ``-T`` is similar to + :option:`-D <ctest -D>`. See `Dashboard Client`_. -``-S <script>, --script <script>`` +.. option:: -S <script>, --script <script> + Execute a dashboard for a configuration. This option tells CTest to load in a configuration script which sets a number of parameters such as the binary and source directories. Then CTest will do what is required to create and run a dashboard. - This option basically sets up a dashboard and then runs ``ctest -D`` + This option basically sets up a dashboard and then runs :option:`ctest -D` with the appropriate options. See `Dashboard Client`_. -``-SP <script>, --script-new-process <script>`` +.. option:: -SP <script>, --script-new-process <script> + Execute a dashboard for a configuration. - This option does the same operations as ``-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 ``-S`` scripts. + 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. See `Dashboard Client`_. -``-I [Start,End,Stride,test#,test#|Test file], --tests-information`` +.. option:: -I [Start,End,Stride,test#,test#|Test file], --tests-information + Run a specific number of tests by number. This option causes CTest to run tests starting at number ``Start``, @@ -275,23 +314,29 @@ Options ``End``, or ``Stride`` can be empty. Optionally a file can be given that contains the same syntax as the command line. -``-U, --union`` - Take the Union of ``-I`` and ``-R``. +.. option:: -U, --union + + Take the Union of :option:`-I <ctest -I>` and :option:`-R <ctest -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 ``-R`` and ``-I`` are specified by default the intersection of - tests are run. By specifying ``-U`` the union of tests is run instead. +.. option:: --rerun-failed -``--rerun-failed`` Run only the tests that failed previously. 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 (``-L``, ``-R``, - ``-E``, ``-LE``, ``-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). + 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 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). + +.. option:: --repeat <mode>:<n> -``--repeat <mode>:<n>`` Run tests repeatedly based on the given ``<mode>`` up to ``<n>`` times. The modes are: @@ -310,17 +355,20 @@ Options This is useful in tolerating sporadic timeouts in test cases on busy machines. -``--repeat-until-fail <n>`` - Equivalent to ``--repeat until-fail:<n>``. +.. option:: --repeat-until-fail <n> + + Equivalent to :option:`--repeat until-fail:\<n\> <ctest --repeat>`. + +.. option:: --max-width <width> -``--max-width <width>`` Set the max width for a test name to output. Set the maximum width for each test name to show in the output. This allows the user to widen the output to avoid clipping the test name which can be very annoying. -``--interactive-debug-mode [0|1]`` +.. option:: --interactive-debug-mode [0|1] + Set the interactive mode to ``0`` or ``1``. This option causes CTest to run tests in either an interactive mode @@ -332,7 +380,8 @@ Options popup windows to appear. Now, due to CTest's use of ``libuv`` to launch test processes, all system debug popup windows are always blocked. -``--no-label-summary`` +.. option:: --no-label-summary + Disable timing summary information for labels. This option tells CTest not to print summary information for each @@ -341,7 +390,8 @@ Options See `Label and Subproject Summary`_. -``--no-subproject-summary`` +.. option:: --no-subproject-summary + Disable timing summary information for subprojects. This option tells CTest not to print summary information for each @@ -350,72 +400,85 @@ Options See `Label and Subproject Summary`_. -``--build-and-test`` -See `Build and Test Mode`_. +.. option:: --build-and-test + + See `Build and Test Mode`_. + +.. option:: --test-dir <dir> -``--test-dir <dir>`` Specify the directory in which to look for tests. -``--test-output-size-passed <size>`` +.. option:: --test-output-size-passed <size> + .. versionadded:: 3.4 Limit the output for passed tests to ``<size>`` bytes. -``--test-output-size-failed <size>`` +.. option:: --test-output-size-failed <size> + .. versionadded:: 3.4 Limit the output for failed tests to ``<size>`` bytes. -``--test-output-truncation <mode>`` +.. option:: --test-output-truncation <mode> + .. versionadded:: 3.24 Truncate ``tail`` (default), ``middle`` or ``head`` of test output once maximum output size is reached. -``--overwrite`` +.. option:: --overwrite + Overwrite CTest configuration option. By default CTest uses configuration options from configuration file. This option will overwrite the configuration option. -``--force-new-ctest-process`` +.. option:: --force-new-ctest-process + Run child CTest instances as new processes. By default CTest will run child CTest instances within the same process. If this behavior is not desired, this argument will enforce new processes for child CTest processes. -``--schedule-random`` +.. option:: --schedule-random + Use a random order for scheduling tests. This option will run the tests in a random order. It is commonly used to detect implicit dependencies in a test suite. -``--submit-index`` +.. option:: --submit-index + Legacy option for old Dart2 dashboard server feature. Do not use. -``--timeout <seconds>`` +.. option:: --timeout <seconds> + Set the default test timeout. This option effectively sets a timeout on all tests that do not already have a timeout set on them via the :prop_test:`TIMEOUT` property. -``--stop-time <time>`` +.. option:: --stop-time <time> + Set a time at which all tests should stop running. Set a real time of day at which all tests should timeout. Example: ``7:00:00 -0400``. Any time format understood by the curl date parser is accepted. Local time is assumed if no timezone is specified. -``--print-labels`` +.. option:: --print-labels + Print all available test labels. This option will not run any tests, it will simply print the list of all labels associated with the test set. -``--no-tests=<[error|ignore]>`` +.. option:: --no-tests=<[error|ignore]> + Regard no tests found either as error or ignore it. If no tests were found, the default behavior of CTest is to always log an @@ -435,17 +498,17 @@ 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 ``-L`` is used, in order for a test to be included in a +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 ``-L`` option means "match **all** +label. Using more than one :option:`-L <ctest -L>` option means "match **all** of these". -The ``-LE`` option works just like ``-L``, but excludes tests -rather than including them. A test is excluded if each regular -expression matches at least one label. +The :option:`-LE <ctest -LE>` option works just like :option:`-L <ctest -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 ``-L`` will never -include that test, and ``-LE`` will never exclude that test. +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. As an example of tests with labels, consider five tests, with the following labels: @@ -532,62 +595,78 @@ be provided to use ``--build-and-test``. If ``--test-command`` is specified then that will be run after the build is complete. Other options that affect this mode include: -``--build-target`` +.. option:: --build-target + Specify a specific target to build. If left out the ``all`` target is built. -``--build-nocmake`` +.. option:: --build-nocmake + Run the build without running cmake first. Skip the cmake step. -``--build-run-dir`` +.. option:: --build-run-dir + Specify directory to run programs from. Directory where programs will be after it has been compiled. -``--build-two-config`` +.. option:: --build-two-config + Run CMake twice. -``--build-exe-dir`` +.. option:: --build-exe-dir + Specify the directory for the executable. -``--build-generator`` +.. option:: --build-generator + Specify the generator to use. See the :manual:`cmake-generators(7)` manual. -``--build-generator-platform`` +.. option:: --build-generator-platform + Specify the generator-specific platform. -``--build-generator-toolset`` +.. option:: --build-generator-toolset + Specify the generator-specific toolset. -``--build-project`` +.. option:: --build-project + Specify the name of the project to build. -``--build-makeprogram`` +.. option:: --build-makeprogram + Specify the explicit make program to be used by CMake when configuring and building the project. Only applicable for Make and Ninja based generators. -``--build-noclean`` +.. option:: --build-noclean + Skip the make clean step. -``--build-config-sample`` +.. option:: --build-config-sample + A sample executable to use to determine the configuration that should be used. e.g. ``Debug``, ``Release`` etc. -``--build-options`` +.. option:: --build-options + Additional options for configuring the build (i.e. for CMake, not for the build tool). Note that if this is specified, the ``--build-options`` keyword and its arguments must be the last option given on the command line, with the possible exception of ``--test-command``. -``--test-command`` - The command to run as the test step with the ``--build-and-test`` option. +.. option:: --test-command + + The command to run as the test step with the + :option:`--build-and-test <ctest --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. -``--test-timeout`` +.. option:: --test-timeout + The time limit in seconds .. _`Dashboard Client`: @@ -605,7 +684,8 @@ a `CDash`_ server. The command-line signature used to submit to `CDash`_ is:: Options for Dashboard Client include: -``--group <group>`` +.. option:: --group <group> + Specify what group you'd like to submit results to Submit dashboard to specified group instead of default one. By @@ -616,29 +696,34 @@ Options for Dashboard Client include: This replaces the deprecated option ``--track``. Despite the name change its behavior is unchanged. -``-A <file>, --add-notes <file>`` +.. option:: -A <file>, --add-notes <file> + Add a notes file with submission. This option tells CTest to include a notes file when submitting dashboard. -``--tomorrow-tag`` +.. option:: --tomorrow-tag + ``Nightly`` or ``Experimental`` starts with next day tag. This is useful if the build will not finish in one day. -``--extra-submit <file>[;<file>]`` +.. option:: --extra-submit <file>[;<file>] + Submit extra files to the dashboard. This option will submit extra files to the dashboard. -``--http1.0`` +.. option:: --http1.0 + Submit using `HTTP 1.0`. This option will force CTest to use `HTTP 1.0` to submit files to the dashboard, instead of `HTTP 1.1`. -``--no-compress-output`` +.. option:: --no-compress-output + Do not compress test output when submitting. This flag will turn off automatic compression of test output. Use @@ -1027,9 +1112,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 ``-C`` option is - given to the ``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 :option:`-C <ctest -C>` + option is given to the ``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` @@ -1101,8 +1186,9 @@ Configuration settings include: See `Label and Subproject Summary`_. ``TestLoad`` - While running tests in parallel (e.g. with ``-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 :option:`-j <ctest -j>`), + try not to start tests when they may cause the CPU load to pass above + a given threshold. * `CTest Script`_ variable: :variable:`CTEST_TEST_LOAD` * :module:`CTest` module variable: ``CTEST_TEST_LOAD`` diff --git a/Help/variable/CMAKE_CPACK_COMMAND.rst b/Help/variable/CMAKE_CPACK_COMMAND.rst index 3a81d68..94f1891 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 b2942e2..7287998 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 8f2a82f..48b0dce 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 ec52cd4..0e249eb 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_GENERATOR_PLATFORM.rst b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst index b17d83a..acb7b2e 100644 --- a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst +++ b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst @@ -7,7 +7,7 @@ Generator-specific target platform specification provided by user. Some CMake generators support a target platform name to be given to the native build system to choose a compiler toolchain. -If the user specifies a platform name (e.g. via the :manual:`cmake(1)` ``-A`` +If the user specifies a platform name (e.g. via the :option:`cmake -A` option or via the :envvar:`CMAKE_GENERATOR_PLATFORM` environment variable) the value will be available in this variable. diff --git a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst index 45f2d32..4855477 100644 --- a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst +++ b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst @@ -5,7 +5,7 @@ Native build system toolset specification provided by user. Some CMake generators support a toolset specification to tell the native build system how to choose a compiler. If the user specifies -a toolset (e.g. via the :manual:`cmake(1)` ``-T`` option or via +a toolset (e.g. via the :option:`cmake -T` option or via the :envvar:`CMAKE_GENERATOR_TOOLSET` environment variable) the value will be available in this variable. diff --git a/Help/variable/CMAKE_INSTALL_PREFIX.rst b/Help/variable/CMAKE_INSTALL_PREFIX.rst index 6d42ea8..1636739 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_LANG_COMPILER.rst b/Help/variable/CMAKE_LANG_COMPILER.rst index e694b33..db8f4e1 100644 --- a/Help/variable/CMAKE_LANG_COMPILER.rst +++ b/Help/variable/CMAKE_LANG_COMPILER.rst @@ -14,7 +14,8 @@ This variable can be set by the user during the first time a build tree is confi If a non-full path value is supplied then CMake will resolve the full path of the compiler. -The variable could be set in a user supplied toolchain file or via `-D` on the command line. +The variable could be set in a user supplied toolchain file or via +:option:`-D <cmake -D>` on the command line. .. note:: Options that are required to make the compiler work correctly can be included diff --git a/Help/variable/CMAKE_MAKE_PROGRAM.rst b/Help/variable/CMAKE_MAKE_PROGRAM.rst index a3c8b7c..9769c7a 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 41ace43..7274b7b 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 54ea6a4..4539c90 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 9dce760..f844105 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 981af60..104f4ac 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 4a224fa..c7b6159 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/CMAKE_XCODE_PLATFORM_TOOLSET.rst b/Help/variable/CMAKE_XCODE_PLATFORM_TOOLSET.rst index 210da52..6d72d14 100644 --- a/Help/variable/CMAKE_XCODE_PLATFORM_TOOLSET.rst +++ b/Help/variable/CMAKE_XCODE_PLATFORM_TOOLSET.rst @@ -5,5 +5,5 @@ Xcode compiler selection. :generator:`Xcode` supports selection of a compiler from one of the installed toolsets. CMake provides the name of the chosen toolset in this -variable, if any is explicitly selected (e.g. via the :manual:`cmake(1)` -``-T`` option). +variable, if any is explicitly selected (e.g. via the :option:`cmake -T` +option). diff --git a/Help/variable/CPACK_CUSTOM_INSTALL_VARIABLES.rst b/Help/variable/CPACK_CUSTOM_INSTALL_VARIABLES.rst index 1c070b8..9bd50db 100644 --- a/Help/variable/CPACK_CUSTOM_INSTALL_VARIABLES.rst +++ b/Help/variable/CPACK_CUSTOM_INSTALL_VARIABLES.rst @@ -3,7 +3,7 @@ CPACK_CUSTOM_INSTALL_VARIABLES .. versionadded:: 3.21 -CPack variables (set via e.g. ``cpack -D``, ``CPackConfig.cmake`` or +CPack variables (set via e.g. :option:`cpack -D`, ``CPackConfig.cmake`` or :variable:`CPACK_PROJECT_CONFIG_FILE` scripts) are not directly visible in installation scripts. Instead, one can pass a list of ``varName=value`` pairs in the ``CPACK_CUSTOM_INSTALL_VARIABLES`` variable. At install time, diff --git a/Help/variable/CTEST_CONFIGURATION_TYPE.rst b/Help/variable/CTEST_CONFIGURATION_TYPE.rst index 392845e..932f81d 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. diff --git a/Help/variable/CTEST_RUN_CURRENT_SCRIPT.rst b/Help/variable/CTEST_RUN_CURRENT_SCRIPT.rst index 32c85ad..8cb6eaa 100644 --- a/Help/variable/CTEST_RUN_CURRENT_SCRIPT.rst +++ b/Help/variable/CTEST_RUN_CURRENT_SCRIPT.rst @@ -4,4 +4,4 @@ CTEST_RUN_CURRENT_SCRIPT .. versionadded:: 3.11 Setting this to 0 prevents :manual:`ctest(1)` from being run again when it -reaches the end of a script run by calling ``ctest -S``. +reaches the end of a script run by calling :option:`ctest -S`. diff --git a/Modules/CPack.cmake b/Modules/CPack.cmake index 4934934..07280e0 100644 --- a/Modules/CPack.cmake +++ b/Modules/CPack.cmake @@ -53,9 +53,9 @@ Here's how it works: * :manual:`cpack <cpack(1)>` runs * it includes ``CPackConfig.cmake`` -* it iterates over the generators given by the ``-G`` command line option, - or if no such option was specified, over the list of generators given by - the :variable:`CPACK_GENERATOR` variable set in the ``CPackConfig.cmake`` +* it iterates over the generators given by the :option:`-G <cpack -G>` command + line option, or if no such option was specified, over the list of generators + given by the :variable:`CPACK_GENERATOR` variable set in the ``CPackConfig.cmake`` input file. * foreach generator, it then @@ -246,9 +246,9 @@ installers. The most commonly-used variables are: List of CPack generators to use. If not specified, CPack will create a set of options following the naming pattern :variable:`CPACK_BINARY_<GENNAME>` (e.g. ``CPACK_BINARY_NSIS``) allowing - the user to enable/disable individual generators. If the ``-G`` option is - given on the :manual:`cpack <cpack(1)>` command line, it will override this - variable and any ``CPACK_BINARY_<GENNAME>`` options. + the user to enable/disable individual generators. If the :option:`-G <cpack -G>` + option is given on the :manual:`cpack <cpack(1)>` command line, it will override + this variable and any ``CPACK_BINARY_<GENNAME>`` options. .. variable:: CPACK_OUTPUT_CONFIG_FILE @@ -469,7 +469,8 @@ The following variables are for advanced uses of CPack: generates (when :variable:`CPACK_GENERATOR` is not set) a set of CMake options (see CMake :command:`option` command) which may then be used to select the CPack generator(s) to be used when building the ``package`` - target or when running :manual:`cpack <cpack(1)>` without the ``-G`` option. + target or when running :manual:`cpack <cpack(1)>` without the + :option:`-G <cpack -G>` option. #]=======================================================================] diff --git a/Modules/CTestUseLaunchers.cmake b/Modules/CTestUseLaunchers.cmake index 23a206b..5c544f8 100644 --- a/Modules/CTestUseLaunchers.cmake +++ b/Modules/CTestUseLaunchers.cmake @@ -11,7 +11,7 @@ CTestUseLaunchers is automatically included when you include(CTest). However, it is split out into its own module file so projects can use the CTEST_USE_LAUNCHERS functionality independently. -To use launchers, set CTEST_USE_LAUNCHERS to ON in a ctest -S +To use launchers, set CTEST_USE_LAUNCHERS to ON in a :option:`ctest -S` dashboard script, and then also set it in the cache of the configured project. Both cmake and ctest need to know the value of it for the launchers to work properly. CMake needs to know in order to generate @@ -27,9 +27,12 @@ variable initialization only occurs if CTEST_USE_LAUNCHERS is not already defined. .. versionadded:: 3.8 - If CTEST_USE_LAUNCHERS is on in a ctest -S script + If CTEST_USE_LAUNCHERS is on in a :option:`ctest -S` script the ctest_configure command will add -DCTEST_USE_LAUNCHERS:BOOL=TRUE to the cmake command used to configure the project. + +.. TODO Use RST markup + #]=======================================================================] if(NOT DEFINED CTEST_USE_LAUNCHERS AND DEFINED ENV{CTEST_USE_LAUNCHERS_DEFAULT}) diff --git a/Source/cmakemain.cxx b/Source/cmakemain.cxx index f931e9d..c83508b 100644 --- a/Source/cmakemain.cxx +++ b/Source/cmakemain.cxx @@ -82,7 +82,7 @@ const char* cmDocumentationOptions[][2] = { { "-N", "View mode only." }, { "-P <file>", "Process script mode." }, { "--find-package", "Legacy pkg-config like mode. Do not use." }, - { "--graphviz=[file]", + { "--graphviz=<file>", "Generate graphviz of dependencies, see " "CMakeGraphVizOptions.cmake for more." }, { "--system-information [file]", "Dump information about this system." }, |