From b768a5e23ba58b1eaf747c54451a5a255663650b Mon Sep 17 00:00:00 2001 From: Brad King Date: Wed, 5 Oct 2022 14:33:10 -0400 Subject: Help: Disambiguate cmake(1) program modes in Sphinx option references 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-` programs. --- Help/command/install.rst | 2 +- Help/envvar/DESTDIR.rst | 2 +- Help/generator/Ninja Multi-Config.rst | 4 +-- Help/guide/user-interaction/index.rst | 8 +++--- Help/manual/cmake-presets.7.rst | 16 +++++++----- Help/manual/cmake.1.rst | 42 ++++++++++++++++++++++++++---- Help/release/dev/cmake-E-env-modify.rst | 4 +-- Help/variable/CMAKE_BINARY_DIR.rst | 2 +- Help/variable/CMAKE_CURRENT_BINARY_DIR.rst | 2 +- Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst | 2 +- Help/variable/CMAKE_INSTALL_PREFIX.rst | 4 +-- Help/variable/CMAKE_SCRIPT_MODE_FILE.rst | 4 +-- Help/variable/CMAKE_SOURCE_DIR.rst | 2 +- 13 files changed, 64 insertions(+), 30 deletions(-) diff --git a/Help/command/install.rst b/Help/command/install.rst index 45da99b..feff436 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -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 `. 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 diff --git a/Help/envvar/DESTDIR.rst b/Help/envvar/DESTDIR.rst index 414db12..dec8430 100644 --- a/Help/envvar/DESTDIR.rst +++ b/Help/envvar/DESTDIR.rst @@ -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 ` mode, one may specify a different prefix using the -:option:`--prefix ` option. +:option:`--prefix ` option. .. note:: diff --git a/Help/generator/Ninja Multi-Config.rst b/Help/generator/Ninja Multi-Config.rst index ae075ed..2cf823a 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-.ninja``. A :variable:`CMAKE_CONFIGURATION_TYPES`. ``cmake --build . --config `` will always use ``build-.ninja`` -to build. If no :option:`--config ` argument is specified, -:option:`cmake --build .` will use ``build.ninja``. +to build. If no :option:`--config ` argument is +specified, :option:`cmake --build . ` will use ``build.ninja``. Each ``build-.ninja`` file contains ```` targets as well as ``:`` targets, where ```` is the same as the diff --git a/Help/guide/user-interaction/index.rst b/Help/guide/user-interaction/index.rst index 9cc5816..3355992 100644 --- a/Help/guide/user-interaction/index.rst +++ b/Help/guide/user-interaction/index.rst @@ -511,7 +511,7 @@ command associated with the the build tool configured by the user. The :option:`--build ` mode also accepts -the parameter :option:`--target ` to +the parameter :option:`--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 ` mode also accepts a -:option:`--config ` parameter +:option:`--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 ` option has no +The :option:`--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 ` +during the build. The :option:`--verbose ` flag can be used to cause those command lines to be shown: .. code-block:: console diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst index 93f929e..eb3e460 100644 --- a/Help/manual/cmake-presets.7.rst +++ b/Help/manual/cmake-presets.7.rst @@ -460,21 +460,21 @@ that may contain the following fields: ``jobs`` An optional integer. Equivalent to passing - :option:`--parallel ` or ``-j`` on the command line. + :option:`--parallel ` or ``-j`` on the command line. ``targets`` An optional string or array of strings. Equivalent to passing - :option:`--target ` or ``-t`` on the command line. + :option:`--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 ` - on the command line. + An optional string. Equivalent to passing + :option:`--config ` on the command line. ``cleanFirst`` An optional bool. If true, equivalent to passing - :option:`--clean-first ` on the command line. + :option:`--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 ` + :option:`--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 ` on the command line. + :option:`--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 ^^^^^^^^^^^^^^^ diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 868dac4..d22317e 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -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= 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 `.) + (To clean only, use :option:`--target clean `.) .. option:: --resolve-package-references= @@ -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 For multi-configuration generators, choose configuration ````. @@ -662,6 +670,8 @@ Run :option:`cmake --install` with no options for quick help. Open a Project ============== +.. program:: cmake + .. code-block:: shell cmake --open @@ -675,16 +685,20 @@ supported by some generators. Run a Script ============ -.. program:: cmake_P +.. program:: cmake .. code-block:: shell cmake [-D =]... -P [-- ...] +.. program:: cmake-P + .. option:: -D = Define a variable for script mode. +.. program:: cmake + .. option:: -P 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 ` provides a way to execute multiple build steps in order: +.. code-block:: shell + + cmake --workflow [] + +The options are: + +.. option:: --workflow + + Select a :ref:`Workflow Preset` using one of the following options. + +.. program:: cmake--workflow + .. option:: --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 diff --git a/Help/release/dev/cmake-E-env-modify.rst b/Help/release/dev/cmake-E-env-modify.rst index ea4a622..08f1fb5 100644 --- a/Help/release/dev/cmake-E-env-modify.rst +++ b/Help/release/dev/cmake-E-env-modify.rst @@ -1,5 +1,5 @@ cmake-E-env-modify ------------------ -* A new ``--modify`` flag was added to :option:`cmake -E env ` to support :prop_test:`ENVIRONMENT_MODIFICATION` - operations. +* A new ``--modify`` flag was added to :option:`cmake -E env ` to + support :prop_test:`ENVIRONMENT_MODIFICATION` operations. diff --git a/Help/variable/CMAKE_BINARY_DIR.rst b/Help/variable/CMAKE_BINARY_DIR.rst index f9c7689..e601eb8 100644 --- a/Help/variable/CMAKE_BINARY_DIR.rst +++ b/Help/variable/CMAKE_BINARY_DIR.rst @@ -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 ` 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. diff --git a/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst b/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst index 6f82dcc..15f81d2 100644 --- a/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst +++ b/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst @@ -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 ` 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. diff --git a/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst b/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst index 0678f99..5b86026 100644 --- a/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst +++ b/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst @@ -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 ` 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. diff --git a/Help/variable/CMAKE_INSTALL_PREFIX.rst b/Help/variable/CMAKE_INSTALL_PREFIX.rst index 1636739..c76727e 100644 --- a/Help/variable/CMAKE_INSTALL_PREFIX.rst +++ b/Help/variable/CMAKE_INSTALL_PREFIX.rst @@ -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 ` mode, one may -specify a different prefix using the :option:`--prefix ` +command-line tool's :option:`--install ` mode, one may specify +a different prefix using the :option:`--prefix ` option: .. code-block:: shell diff --git a/Help/variable/CMAKE_SCRIPT_MODE_FILE.rst b/Help/variable/CMAKE_SCRIPT_MODE_FILE.rst index 104f4ac..313fb4e 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 :option:`cmake -P ` script file currently being +Full path to the :option:`cmake -P` script file currently being processed. -When run in :option:`cmake -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. diff --git a/Help/variable/CMAKE_SOURCE_DIR.rst b/Help/variable/CMAKE_SOURCE_DIR.rst index 32e6e90..7210f75 100644 --- a/Help/variable/CMAKE_SOURCE_DIR.rst +++ b/Help/variable/CMAKE_SOURCE_DIR.rst @@ -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 ` 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. -- cgit v0.12