diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/install.rst | 2 | ||||
| -rw-r--r-- | Help/command/try_compile.rst | 29 | ||||
| -rw-r--r-- | Help/command/try_run.rst | 8 | ||||
| -rw-r--r-- | Help/envvar/DESTDIR.rst | 2 | ||||
| -rw-r--r-- | Help/generator/Ninja Multi-Config.rst | 4 | ||||
| -rw-r--r-- | Help/guide/user-interaction/index.rst | 8 | ||||
| -rw-r--r-- | Help/manual/cmake-presets.7.rst | 16 | ||||
| -rw-r--r-- | Help/manual/cmake.1.rst | 67 | ||||
| -rw-r--r-- | Help/release/3.23.rst | 6 | ||||
| -rw-r--r-- | Help/release/dev/cmake-E-env-modify.rst | 4 | ||||
| -rw-r--r-- | Help/release/dev/try_compile-signatures.rst | 5 | ||||
| -rw-r--r-- | Help/variable/CMAKE_BINARY_DIR.rst | 2 | ||||
| -rw-r--r-- | Help/variable/CMAKE_CURRENT_BINARY_DIR.rst | 2 | ||||
| -rw-r--r-- | Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst | 2 | ||||
| -rw-r--r-- | Help/variable/CMAKE_INSTALL_PREFIX.rst | 4 | ||||
| -rw-r--r-- | Help/variable/CMAKE_SCRIPT_MODE_FILE.rst | 4 | ||||
| -rw-r--r-- | Help/variable/CMAKE_SOURCE_DIR.rst | 2 |
17 files changed, 107 insertions, 60 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 <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 diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index 6cb4f99..b5fad77 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -59,10 +59,10 @@ Try Compiling Source Files .. code-block:: cmake try_compile(<resultVar> - <SOURCES <srcfile...>] | - SOURCE_FROM_ARG <name> <content>] | - SOURCE_FROM_VAR <name> <var>] | - SOURCE_FROM_FILE <name> <path> >... + <SOURCES <srcfile...>] | + SOURCE_FROM_CONTENT <name> <content>] | + SOURCE_FROM_VAR <name> <var>] | + SOURCE_FROM_FILE <name> <path> >... [NO_CACHE] [CMAKE_FLAGS <flags>...] [COMPILE_DEFINITIONS <defs>...] @@ -102,9 +102,9 @@ contain something like the following: target_link_options(cmTryCompileExec PRIVATE <LINK_OPTIONS from caller>) target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES}) -CMake will automatically generate a unique directory for each ``try_compile`` -operation in an unspecified location within the project's binary directory. -These directories will be cleaned automatically unless +CMake automatically generates, for each ``try_compile`` operation, a +unique directory under ``${CMAKE_BINARY_DIR}/CMakeFiles/CMakeScratch`` +with an unspecified name. These directories are cleaned automatically unless :option:`--debug-trycompile <cmake --debug-trycompile>` is passed to ``cmake``. Such directories from previous runs are also unconditionally cleaned at the beginning of any ``cmake`` execution. @@ -194,7 +194,7 @@ The options are: ``OUTPUT_VARIABLE <var>`` Store the output from the build process in the given variable. -``SOURCE_FROM_ARG <name> <content>`` +``SOURCE_FROM_CONTENT <name> <content>`` .. versionadded:: 3.25 Write ``<content>`` to a file named ``<name>`` in the operation directory. @@ -202,7 +202,7 @@ The options are: the contents of the file are dynamically specified. The specified ``<name>`` is not allowed to contain path components. - ``SOURCE_FROM_ARG`` may be specified multiple times. + ``SOURCE_FROM_CONTENT`` may be specified multiple times. ``SOURCE_FROM_FILE <name> <path>`` .. versionadded:: 3.25 @@ -214,14 +214,15 @@ The options are: ``SOURCE_FROM_*``. (Otherwise, ``SOURCES`` is usually more convenient.) The specified ``<name>`` is not allowed to contain path components. -``SOURCE_FROM_VAR <name> <content>`` +``SOURCE_FROM_VAR <name> <var>`` .. versionadded:: 3.25 Write the contents of ``<var>`` to a file named ``<name>`` in the operation - directory. This is the same as ``SOURCE_FROM_ARG``, but takes the contents - from the specified CMake variable, rather than directly, which may be useful - when passing arguments through a function which wraps ``try_compile``. The - specified ``<name>`` is not allowed to contain path components. + directory. This is the same as ``SOURCE_FROM_CONTENT``, but takes the + contents from the specified CMake variable, rather than directly, which may + be useful when passing arguments through a function which wraps + ``try_compile``. The specified ``<name>`` is not allowed to contain path + components. ``SOURCE_FROM_VAR`` may be specified multiple times. diff --git a/Help/command/try_run.rst b/Help/command/try_run.rst index 8393e1b..be7c734 100644 --- a/Help/command/try_run.rst +++ b/Help/command/try_run.rst @@ -13,10 +13,10 @@ Try Compiling and Running Source Files .. code-block:: cmake try_run(<runResultVar> <compileResultVar> - <SOURCES <srcfile...>] | - SOURCE_FROM_ARG <name> <content>] | - SOURCE_FROM_VAR <name> <var>] | - SOURCE_FROM_FILE <name> <path> >... + <SOURCES <srcfile...>] | + SOURCE_FROM_CONTENT <name> <content>] | + SOURCE_FROM_VAR <name> <var>] | + SOURCE_FROM_FILE <name> <path> >... [NO_CACHE] [CMAKE_FLAGS <flags>...] [COMPILE_DEFINITIONS <defs>...] 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 <cmake --install>` mode, one may specify a different prefix using the -:option:`--prefix <cmake --prefix>` option. +:option:`--prefix <cmake--install --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-<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 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 <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 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 <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 ^^^^^^^^^^^^^^^ diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index c05f3c8..879ad0b 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -278,15 +278,24 @@ Options .. option:: --debug-trycompile - Do not delete the :command:`try_compile` build tree. - Only useful on one :command:`try_compile` at a time. + Do not delete the the files and directories created for + :command:`try_compile` / :command:`try_run` calls. + This is useful in debugging failed checks. - Do not delete the files and directories created for :command:`try_compile` - calls. This is useful in debugging failed try_compiles. It may - however change the results of the try-compiles as old junk from a - previous try-compile may cause a different test to either pass or - fail incorrectly. This option is best used for one try-compile at a - time, and only when debugging. + Note that some uses of :command:`try_compile` may use the same build tree, + which will limit the usefulness of this option if a project executes more + than one :command:`try_compile`. For example, such uses may change results + as artifacts from a previous try-compile may cause a different test to either + pass or fail incorrectly. This option is best used only when debugging. + + (With respect to the preceding, the :command:`try_run` command + is effectively a :command:`try_compile`. Any combination of the two + is subject to the potential issues described.) + + .. versionadded:: 3.25 + + When this option is enabled, every try-compile check prints a log + message reporting the directory in which the check is performed. .. option:: --debug-output @@ -512,6 +521,8 @@ Options Build a Project =============== +.. program:: cmake + CMake provides a command-line signature to build an already-generated project binary tree: @@ -528,6 +539,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 @@ -563,7 +576,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> @@ -612,6 +625,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: @@ -627,6 +642,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>``. @@ -658,6 +675,8 @@ Run :option:`cmake --install` with no options for quick help. Open a Project ============== +.. program:: cmake + .. code-block:: shell cmake --open <dir> @@ -671,16 +690,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 @@ -698,7 +721,7 @@ script (including the ``--`` itself). Run a Command-Line Tool ======================= -.. program:: cmake_E +.. program:: cmake CMake provides builtin command-line tools through the signature @@ -710,6 +733,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 @@ -1165,6 +1190,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 @@ -1185,9 +1212,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 @@ -1203,6 +1244,8 @@ build steps in order: View Help ========= +.. program:: cmake + To print selected pages from the CMake documentation, use .. code-block:: shell @@ -1211,8 +1254,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/3.23.rst b/Help/release/3.23.rst index 69898e9..209be45 100644 --- a/Help/release/3.23.rst +++ b/Help/release/3.23.rst @@ -310,9 +310,9 @@ Changes made since CMake 3.23.0 include the following. The old ``CPACK_PACKAGEMAKER_CHOICES`` variable is now also set to the same content as it was before, but it is formally deprecated. -3.23.3 ------- +3.23.3, 3.23.4 +-------------- -* This version made no changes to documented features or interfaces. +* These versions made no changes to documented features or interfaces. Some implementation updates were made to support ecosystem changes and/or fix regressions. 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 <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. diff --git a/Help/release/dev/try_compile-signatures.rst b/Help/release/dev/try_compile-signatures.rst index d477d989..c32babd 100644 --- a/Help/release/dev/try_compile-signatures.rst +++ b/Help/release/dev/try_compile-signatures.rst @@ -5,4 +5,7 @@ try_compile-signatures signatures that more consistently use keyword dispatch and do not require a binary directory to be specified. Additionally, these signatures use a unique directory for each invocation, which allows multiple outputs to be - preserved when using ``--debug-trycompile``. + preserved when using :option:`--debug-trycompile <cmake --debug-trycompile>`. + +* The :option:`cmake --debug-trycompile` option now prints log messages + reporting the directory in which each try-compile check is done. 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 <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. 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 <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. 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 <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. 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 <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 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 <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. 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 <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. |