echo/CMake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Help: Disambiguate cmake(1) program modes in Sphinx option references

Browse Source 
Define the entry point to each mode as an option for the `cmake`
program, but reference the options for that mode as part of stand-in
`cmake-<mode>` programs.
This commit is contained in:
Brad King 2022-10-05 14:33:10 -04:00
parent 6ace9562e7
commit b768a5e23b
13 changed files with 64 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Help/command/install.rst
View File

@ -968,7 +968,7 @@ Generated Installation Script
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
:option:`cmake -P <cmake_P -P>`. This script accepts several variables:
:option:`cmake -P`. This script accepts several variables:
``COMPONENT``
Set this variable to install only a single CPack component as opposed to all

2
Help/envvar/DESTDIR.rst
View File

@ -22,7 +22,7 @@ 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 :option:`--install <cmake --install>`
mode, one may specify a different prefix using the
:option:`--prefix <cmake --prefix>` option.
:option:`--prefix <cmake--install --prefix>` option.
.. note::

4
Help/generator/Ninja Multi-Config.rst
View File

@ -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 :option:`--config <cmake --config>` argument is specified,
:option:`cmake --build .<cmake --build>` will use ``build.ninja``.
to build. If no :option:`--config <cmake--build --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

8
Help/guide/user-interaction/index.rst
View File

@ -511,7 +511,7 @@ command associated with the
the build tool configured by the user.
The :option:`--build <cmake --build>` mode also accepts
the parameter :option:`--target <cmake --target>` to
the parameter :option:`--target <cmake--build --target>` to
specify a particular target to build, for example a
particular library, executable or custom target, or a
particular special target like ``install``:
@ -521,7 +521,7 @@ particular special target like ``install``:
$ cmake --build . --target myexe
The :option:`--build <cmake --build>` mode also accepts a
:option:`--config <cmake --config>` parameter
:option:`--config <cmake--build --config>` parameter
in the case of multi-config generators to specify which
particular configuration to build:
@ -529,13 +529,13 @@ particular configuration to build:
$ cmake --build . --target myexe --config Release
The :option:`--config <cmake --config>` option has no
The :option:`--config <cmake--build --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 :option:`-verbose <cmake --verbose>`
during the build. The :option:`--verbose <cmake--build --verbose>`
flag can be used to cause those command lines to be shown:
.. code-block:: console

16
Help/manual/cmake-presets.7.rst
View File

@ -460,21 +460,21 @@ that may contain the following fields:
``jobs``
An optional integer. Equivalent to passing
:option:`--parallel <cmake --parallel>` or ``-j`` on the command line.
:option:`--parallel <cmake--build --parallel>` or ``-j`` on the command line.
``targets``
An optional string or array of strings. Equivalent to passing
:option:`--target <cmake --target>` or ``-t`` on the command line.
:option:`--target <cmake--build --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 :option:`--config <cmake --config>`
on the command line.
An optional string. Equivalent to passing
:option:`--config <cmake--build --config>` on the command line.
``cleanFirst``
An optional bool. If true, equivalent to passing
:option:`--clean-first <cmake --clean-first>` on the command line.
:option:`--clean-first <cmake--build --clean-first>` on the command line.
``resolvePackageReferences``
An optional string that specifies the package resolve mode. This is
@ -498,7 +498,7 @@ that may contain the following fields:
.. note::
The command line parameter
:option:`--resolve-package-references <cmake --resolve-package-references>`
:option:`--resolve-package-references <cmake--build --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
@ -512,7 +512,7 @@ that may contain the following fields:
``verbose``
An optional bool. If true, equivalent to passing
:option:`--verbose <cmake --verbose>` on the command line.
:option:`--verbose <cmake--build --verbose>` on the command line.
``nativeToolOptions``
An optional array of strings. Equivalent to passing options after ``--``
@ -981,6 +981,8 @@ fields:
``vendorName``
An optional string representing the vendor name.
.. _`Workflow Preset`:
Workflow Preset
^^^^^^^^^^^^^^^

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

@ -516,6 +516,8 @@ Options
Build a Project
===============
.. program:: cmake
CMake provides a command-line signature to build an already-generated
project binary tree:
@ -532,6 +534,8 @@ following options:
Project binary directory to be built. This is required (unless a preset
is specified) and must be first.
.. program:: cmake--build
.. option:: --preset <preset>, --preset=<preset>
Use a build preset to specify build options. The project binary directory
@ -567,7 +571,7 @@ following options:
.. option:: --clean-first
Build target ``clean`` first, then build.
(To clean only, use :option:`--target clean <cmake --target>`.)
(To clean only, use :option:`--target clean <cmake--build --target>`.)
.. option:: --resolve-package-references=<value>
@ -616,6 +620,8 @@ Run :option:`cmake --build` with no options for quick help.
Install a Project
=================
.. program:: cmake
CMake provides a command-line signature to install an already-generated
project binary tree:
@ -631,6 +637,8 @@ The options are:
Project binary directory to install. This is required and must be first.
.. program:: cmake--install
.. option:: --config <cfg>
For multi-configuration generators, choose configuration ``<cfg>``.
@ -662,6 +670,8 @@ Run :option:`cmake --install` with no options for quick help.
Open a Project
==============
.. program:: cmake
.. code-block:: shell
cmake --open <dir>
@ -675,16 +685,20 @@ supported by some generators.
Run a Script
============
.. program:: cmake_P
.. program:: cmake
.. code-block:: shell
cmake [-D <var>=<value>]... -P <cmake-script-file> [-- <unparsed-options>...]
.. program:: cmake-P
.. option:: -D <var>=<value>
Define a variable for script mode.
.. program:: cmake
.. option:: -P <cmake-script-file>
Process the given cmake file as a script written in the CMake
@ -702,7 +716,7 @@ script (including the ``--`` itself).
Run a Command-Line Tool
=======================
.. program:: cmake_E
.. program:: cmake
CMake provides builtin command-line tools through the signature
@ -714,6 +728,8 @@ CMake provides builtin command-line tools through the signature
Run ``cmake -E`` or ``cmake -E help`` for a summary of commands.
.. program:: cmake-E
Available commands are:
.. option:: capabilities
@ -1169,6 +1185,8 @@ The following ``cmake -E`` commands are available only on Windows:
Run the Find-Package Tool
=========================
.. program:: cmake--find-package
CMake provides a pkg-config like helper for Makefile-based projects:
.. code-block:: shell
@ -1189,9 +1207,23 @@ autoconf-based projects (via ``share/aclocal/cmake.m4``).
Run a Workflow Preset
=====================
.. program:: cmake
:manual:`CMake Presets <cmake-presets(7)>` provides a way to execute multiple
build steps in order:
.. code-block:: shell
cmake --workflow [<options>]
The options are:
.. option:: --workflow
Select a :ref:`Workflow Preset` using one of the following options.
.. program:: cmake--workflow
.. option:: --preset <preset>, --preset=<preset>
Use a workflow preset to specify a workflow. The project binary directory
@ -1207,6 +1239,8 @@ build steps in order:
View Help
=========
.. program:: cmake
To print selected pages from the CMake documentation, use
.. code-block:: shell
@ -1215,8 +1249,6 @@ 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

4
Help/release/dev/cmake-E-env-modify.rst
View File

@ -1,5 +1,5 @@
cmake-E-env-modify
------------------
* A new ``--modify`` flag was added to :option:`cmake -E env <cmake_E env>` to support :prop_test:`ENVIRONMENT_MODIFICATION`
operations.
* A new ``--modify`` flag was added to :option:`cmake -E env <cmake-E env>` to
support :prop_test:`ENVIRONMENT_MODIFICATION` operations.

2
Help/variable/CMAKE_BINARY_DIR.rst
View File

@ -7,7 +7,7 @@ This is the full path to the top level of the current CMake build
tree. For an in-source build, this would be the same as
:variable:`CMAKE_SOURCE_DIR`.
When run in :option:`-P <cmake_P -P>` script mode, CMake sets the variables
When run in :option:`cmake -P` script mode, CMake sets the variables
:variable:`CMAKE_BINARY_DIR`, :variable:`CMAKE_SOURCE_DIR`,
:variable:`CMAKE_CURRENT_BINARY_DIR` and
:variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory.

2
Help/variable/CMAKE_CURRENT_BINARY_DIR.rst
View File

@ -9,7 +9,7 @@ create a binary directory in the build tree, and as it is being
processed this variable will be set. For in-source builds this is the
current source directory being processed.
When run in :option:`-P <cmake_P -P>` script mode, CMake sets the variables
When run in :option:`cmake -P` script mode, CMake sets the variables
:variable:`CMAKE_BINARY_DIR`, :variable:`CMAKE_SOURCE_DIR`,
:variable:`CMAKE_CURRENT_BINARY_DIR` and
:variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory.

2
Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst
View File

@ -6,7 +6,7 @@ The path to the source directory currently being processed.
This is the full path to the source directory that is currently being
processed by cmake.
When run in :option:`-P <cmake_P -P>` script mode, CMake sets the variables
When run in :option:`cmake -P` script mode, CMake sets the variables
:variable:`CMAKE_BINARY_DIR`, :variable:`CMAKE_SOURCE_DIR`,
:variable:`CMAKE_CURRENT_BINARY_DIR` and
:variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory.

4
Help/variable/CMAKE_INSTALL_PREFIX.rst
View File

@ -27,8 +27,8 @@ 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 :option:`--install <cmake --install>` mode, one may
specify a different prefix using the :option:`--prefix <cmake --prefix>`
command-line tool's :option:`--install <cmake --install>` mode, one may specify
a different prefix using the :option:`--prefix <cmake--install --prefix>`
option:
.. code-block:: shell

4
Help/variable/CMAKE_SCRIPT_MODE_FILE.rst
View File

@ -1,9 +1,9 @@
CMAKE_SCRIPT_MODE_FILE
----------------------
Full path to the :option:`cmake -P <cmake_P -P>` script file currently being
Full path to the :option:`cmake -P` script file currently being
processed.
When run in :option:`cmake -P <cmake_P -P>` script mode, CMake sets this variable to
When run in :option:`cmake -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.

2
Help/variable/CMAKE_SOURCE_DIR.rst
View File

@ -7,7 +7,7 @@ This is the full path to the top level of the current CMake source
tree. For an in-source build, this would be the same as
:variable:`CMAKE_BINARY_DIR`.
When run in :option:`-P <cmake_P -P>` script mode, CMake sets the variables
When run in :option:`cmake -P` script mode, CMake sets the variables
:variable:`CMAKE_BINARY_DIR`, :variable:`CMAKE_SOURCE_DIR`,
:variable:`CMAKE_CURRENT_BINARY_DIR` and
:variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory.