diff options
Diffstat (limited to 'Help/command')
24 files changed, 581 insertions, 72 deletions
diff --git a/Help/command/DEVICE_LINK_OPTIONS.txt b/Help/command/DEVICE_LINK_OPTIONS.txt index 1297cd0..3d50208 100644 --- a/Help/command/DEVICE_LINK_OPTIONS.txt +++ b/Help/command/DEVICE_LINK_OPTIONS.txt @@ -1,3 +1,5 @@ +Host And Device Specific Link Options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. versionadded:: 3.18 When a device link step is involved, which is controlled by diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index 97eecfc..5b63e1c 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -11,10 +11,11 @@ The general signature is: |FIND_XXX| ( <VAR> name | |NAMES| - [HINTS path1 [path2 ... ENV var]] - [PATHS path1 [path2 ... ENV var]] + [HINTS [path | ENV var]... ] + [PATHS [path | ENV var]... ] [PATH_SUFFIXES suffix1 [suffix2 ...]] [DOC "cache documentation string"] + [NO_CACHE] [REQUIRED] [NO_DEFAULT_PATH] [NO_PACKAGE_ROOT_PATH] @@ -28,8 +29,8 @@ The general signature is: ) This command is used to find a |SEARCH_XXX_DESC|. -A cache entry named by ``<VAR>`` is created to store the result -of this command. +A cache entry, or a normal variable if ``NO_CACHE`` is specified, +named by ``<VAR>`` is created to store the result of this command. If the |SEARCH_XXX| is found the result is stored in the variable and the search will not be repeated unless the variable is cleared. If nothing is found, the result will be ``<VAR>-NOTFOUND``. @@ -56,6 +57,22 @@ Options include: ``DOC`` Specify the documentation string for the ``<VAR>`` cache entry. +``NO_CACHE`` + .. versionadded:: 3.21 + + The result of the search will be stored in a normal variable rather than + a cache entry. + + .. note:: + + If the variable is already set before the call (as a normal or cache + variable) then the search will not occur. + + .. warning:: + + This option should be used with caution because it can greatly increase + the cost of repeated configure steps. + ``REQUIRED`` .. versionadded:: 3.18 diff --git a/Help/command/LINK_OPTIONS_LINKER.txt b/Help/command/LINK_OPTIONS_LINKER.txt index 3f66181..e71e5ea 100644 --- a/Help/command/LINK_OPTIONS_LINKER.txt +++ b/Help/command/LINK_OPTIONS_LINKER.txt @@ -1,3 +1,6 @@ +Handling Compiler Driver Differences +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + To pass options to the linker tool, each compiler driver has its own syntax. The ``LINKER:`` prefix and ``,`` separator can be used to specify, in a portable way, options to pass to the linker tool. ``LINKER:`` is replaced by the diff --git a/Help/command/OPTIONS_SHELL.txt b/Help/command/OPTIONS_SHELL.txt index 4051ffe..4171f01 100644 --- a/Help/command/OPTIONS_SHELL.txt +++ b/Help/command/OPTIONS_SHELL.txt @@ -1,11 +1,15 @@ -The final set of compile or link options used for a target is constructed by +Option De-duplication +^^^^^^^^^^^^^^^^^^^^^ + +The final set of options used for a target is constructed by accumulating options from the current target and the usage requirements of its dependencies. The set of options is de-duplicated to avoid repetition. .. versionadded:: 3.12 While beneficial for individual options, the de-duplication step can break - up option groups. For example, ``-D A -D B`` becomes ``-D A B``. One may - specify a group of options using shell-like quoting along with a ``SHELL:`` - prefix. The ``SHELL:`` prefix is dropped, and the rest of the option string - is parsed using the :command:`separate_arguments` ``UNIX_COMMAND`` mode. - For example, ``"SHELL:-D A" "SHELL:-D B"`` becomes ``-D A -D B``. + up option groups. For example, ``-option A -option B`` becomes + ``-option A B``. One may specify a group of options using shell-like + quoting along with a ``SHELL:`` prefix. The ``SHELL:`` prefix is dropped, + and the rest of the option string is parsed using the + :command:`separate_arguments` ``UNIX_COMMAND`` mode. For example, + ``"SHELL:-option A" "SHELL:-option B"`` becomes ``-option A -option B``. diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index c0b9593..d881a66 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -271,21 +271,30 @@ The options are: ``DEPFILE`` .. versionadded:: 3.7 - Specify a ``.d`` depfile for the :generator:`Ninja` generator and - :ref:`Makefile Generators`. - A ``.d`` file holds dependencies usually emitted by the custom - command itself. - Using ``DEPFILE`` with other generators than :generator:`Ninja` or - :ref:`Makefile Generators` is an error. + Specify a ``.d`` depfile for the :generator:`Ninja`, :generator:`Xcode` and + :ref:`Makefile <Makefile Generators>` generators. The depfile may use + "generator expressions" with the syntax ``$<...>``. See the + :manual:`generator-expressions(7) <cmake-generator-expressions(7)>` manual + for available expressions. A ``.d`` file holds dependencies usually emitted + by the custom command itself. + + Using ``DEPFILE`` with other generators than :generator:`Ninja`, + :generator:`Xcode` or :ref:`Makefile <Makefile Generators>` is an error. .. versionadded:: 3.20 - Added the support of :ref:`Makefile Generators`. + Added support for :ref:`Makefile Generators`. + + .. versionadded:: 3.21 + Added support for :ref:`Visual Studio Generators` with VS 2012 and above, + for the :generator:`Xcode` generator, and for + :manual:`generator expressions <cmake-generator-expressions(7)>`. If the ``DEPFILE`` argument is relative, it should be relative to :variable:`CMAKE_CURRENT_BINARY_DIR`, and any relative paths inside the ``DEPFILE`` should also be relative to :variable:`CMAKE_CURRENT_BINARY_DIR` (see policy :policy:`CMP0116`. This policy is always ``NEW`` for - :ref:`Makefile Generators`). + :ref:`Makefile Generators`, :ref:`Visual Studio Generators`, + and the :generator:`Xcode` generator). .. note:: @@ -331,6 +340,8 @@ will re-run whenever ``in.txt`` changes. where ``<config>`` is the build configuration, and then compile the generated source as part of a library. +.. _`add_custom_command(TARGET)`: + Build Events ^^^^^^^^^^^^ @@ -381,6 +392,9 @@ of the following is specified: This allows to add individual build events for every configuration. +.. versionadded:: 3.21 + Support for target-dependent generator expressions. + Examples: Build Events ^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/command/build_command.rst b/Help/command/build_command.rst index 6659005..a03979d 100644 --- a/Help/command/build_command.rst +++ b/Help/command/build_command.rst @@ -8,23 +8,29 @@ This is mainly intended for internal use by the :module:`CTest` module. build_command(<variable> [CONFIGURATION <config>] + [PARALLEL_LEVEL <parallel>] [TARGET <target>] [PROJECT_NAME <projname>] # legacy, causes warning ) Sets the given ``<variable>`` to a command-line string of the form:: - <cmake> --build . [--config <config>] [--target <target>...] [-- -i] + <cmake> --build . [--config <config>] [--parallel <parallel>] [--target <target>...] [-- -i] where ``<cmake>`` is the location of the :manual:`cmake(1)` command-line -tool, and ``<config>`` and ``<target>`` are the values provided to the -``CONFIGURATION`` and ``TARGET`` options, if any. The trailing ``-- -i`` -option is added for :ref:`Makefile Generators` if policy :policy:`CMP0061` -is not set to ``NEW``. +tool, and ``<config>``, ``<parallel>`` and ``<target>`` are the values +provided to the ``CONFIGURATION``, ``PARALLEL_LEVEL`` and ``TARGET`` +options, if any. The trailing ``-- -i`` option is added for +:ref:`Makefile Generators` if policy :policy:`CMP0061` is not set to +``NEW``. When invoked, this ``cmake --build`` command line will launch the underlying build system tool. +.. versionadded:: 3.21 + The ``PARALLEL_LEVEL`` argument can be used to set the ``--parallel`` + flag. + .. code-block:: cmake build_command(<cachevariable> <makecommand>) diff --git a/Help/command/cmake_language.rst b/Help/command/cmake_language.rst index 99f874b..2859f6b 100644 --- a/Help/command/cmake_language.rst +++ b/Help/command/cmake_language.rst @@ -190,7 +190,7 @@ For example, the code: .. code-block:: cmake cmake_language(DEFER CALL message "${deferred_message}") - cmake_language(DEFER ID_VAR id CALL message "Cancelled Message") + cmake_language(DEFER ID_VAR id CALL message "Canceled Message") cmake_language(DEFER CANCEL_CALL ${id}) message("Immediate Message") set(deferred_message "Deferred Message") @@ -201,7 +201,7 @@ prints:: Deferred Message The ``Cancelled Message`` is never printed because its command is -cancelled. The ``deferred_message`` variable reference is not evaluated +canceled. The ``deferred_message`` variable reference is not evaluated until the call site, so it can be set after the deferred call is scheduled. In order to evaluate variable references immediately when scheduling a diff --git a/Help/command/cmake_minimum_required.rst b/Help/command/cmake_minimum_required.rst index c3b3e73..d159770 100644 --- a/Help/command/cmake_minimum_required.rst +++ b/Help/command/cmake_minimum_required.rst @@ -5,21 +5,21 @@ Require a minimum version of cmake. .. code-block:: cmake - cmake_minimum_required(VERSION <min>[...<max>] [FATAL_ERROR]) + cmake_minimum_required(VERSION <min>[...<policy_max>] [FATAL_ERROR]) .. versionadded:: 3.12 - The optional ``<max>`` version. + The optional ``<policy_max>`` version. Sets the minimum required version of cmake for a project. Also updates the policy settings as explained below. -``<min>`` and the optional ``<max>`` are each CMake versions of the form -``major.minor[.patch[.tweak]]``, and the ``...`` is literal. +``<min>`` and the optional ``<policy_max>`` are each CMake versions of the +form ``major.minor[.patch[.tweak]]``, and the ``...`` is literal. If the running version of CMake is lower than the ``<min>`` required version it will stop processing the project and report an error. -The optional ``<max>`` version, if specified, must be at least the -``<min>`` version and affects policy settings as described below. +The optional ``<policy_max>`` version, if specified, must be at least the +``<min>`` version and affects policy settings as described in `Policy Settings`_. If the running version of CMake is older than 3.12, the extra ``...`` dots will be seen as version component separators, resulting in the ``...<max>`` part being ignored and preserving the pre-3.12 behavior @@ -40,8 +40,15 @@ with an error instead of just a warning. they may affect. See also policy :policy:`CMP0000`. Calling ``cmake_minimum_required()`` inside a :command:`function` - limits some effects to the function scope when invoked. Such calls - should not be made with the intention of having global effects. + limits some effects to the function scope when invoked. For example, + the :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable won't be set + in the calling scope. Functions do not introduce their own policy + scope though, so policy settings of the caller *will* be affected + (see below). Due to this mix of things that do and do not affect the + calling scope, calling ``cmake_minimum_required()`` inside a function + is generally discouraged. + +.. _`Policy Settings`: Policy Settings ^^^^^^^^^^^^^^^ diff --git a/Help/command/cmake_path.rst b/Help/command/cmake_path.rst index e7a01ab..565a37b 100644 --- a/Help/command/cmake_path.rst +++ b/Help/command/cmake_path.rst @@ -688,7 +688,8 @@ When the ``NORMALIZE`` option is specified, the path is :ref:`normalized <Normalization>` after the path computation. Because ``cmake_path()`` does not access the filesystem, symbolic links are -not resolved. To compute a real path with symbolic links resolved, use the +not resolved and any leading tilde is not expanded. To compute a real path +with symbolic links resolved and leading tildes expanded, use the :command:`file(REAL_PATH)` command instead. Native Conversion diff --git a/Help/command/configure_file.rst b/Help/command/configure_file.rst index d00f08b..086668c 100644 --- a/Help/command/configure_file.rst +++ b/Help/command/configure_file.rst @@ -36,8 +36,30 @@ or depending on whether ``VAR`` is set in CMake to any value not considered a false constant by the :command:`if` command. The "..." content on the line after the variable name, if any, is processed as above. -Input file lines of the form ``#cmakedefine01 VAR`` will be replaced with -either ``#define VAR 1`` or ``#define VAR 0`` similarly. + +Unlike lines of the form ``#cmakedefine VAR ...``, in lines of the form +``#cmakedefine01 VAR``, ``VAR`` itself will expand to ``VAR 0`` or ``VAR 1`` +rather than being assigned the value ``...``. Therefore, input lines of the form + +.. code-block:: c + + #cmakedefine01 VAR + +will be replaced with either + +.. code-block:: c + + #define VAR 0 + +or + +.. code-block:: c + + #define VAR 1 + +Input lines of the form ``#cmakedefine01 VAR ...`` will expand +as ``#cmakedefine01 VAR ... 0`` or ``#cmakedefine01 VAR ... 0``, +which may lead to undefined behavior. .. versionadded:: 3.10 The result lines (with the exception of the ``#undef`` comments) can be diff --git a/Help/command/ctest_build.rst b/Help/command/ctest_build.rst index 4d6dc5a..e05df1a 100644 --- a/Help/command/ctest_build.rst +++ b/Help/command/ctest_build.rst @@ -7,6 +7,7 @@ Perform the :ref:`CTest Build Step` as a :ref:`Dashboard Client`. ctest_build([BUILD <build-dir>] [APPEND] [CONFIGURATION <config>] + [PARALLEL_LEVEL <parallel>] [FLAGS <flags>] [PROJECT_NAME <project-name>] [TARGET <target-name>] @@ -42,6 +43,13 @@ The options are: Otherwise the ``-C <cfg>`` option given to the :manual:`ctest(1)` command will be used, if any. +``PARALLEL_LEVEL <parallel>`` + .. versionadded:: 3.21 + + Specify the parallel level of the underlying build system. If not + specified, the :envvar:`CMAKE_BUILD_PARALLEL_LEVEL` environment + variable will be checked. + ``FLAGS <flags>`` Pass additional arguments to the underlying build command. If not specified the ``CTEST_BUILD_FLAGS`` variable will be checked. diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst index b4493a0..2153c90 100644 --- a/Help/command/ctest_test.rst +++ b/Help/command/ctest_test.rst @@ -25,6 +25,7 @@ Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`. [RETURN_VALUE <result-var>] [CAPTURE_CMAKE_ERROR <result-var>] [REPEAT <mode>:<n>] + [OUTPUT_JUNIT <file>] [QUIET] ) @@ -150,6 +151,15 @@ The options are: Store in the ``<result-var>`` variable -1 if there are any errors running the command and prevent ctest from returning non-zero if an error occurs. +``OUTPUT_JUNIT`` + .. versionadded:: 3.21 + + Write test results to ``<file>`` in JUnit XML format. If ``<file>`` is a + relative path it will be placed in the build directory. If ``<file>>`` + already exists it will be overwritten. Note that the resulting JUnit XML + file is **not** uploaded to CDash because it would be redundant with + CTest's ``Test.xml`` file. + ``QUIET`` .. versionadded:: 3.3 @@ -160,3 +170,103 @@ The options are: See also the :variable:`CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE` and :variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE` variables. + +.. _`Additional Test Measurements`: + +Additional Test Measurements +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +CTest can parse the output of your tests for extra measurements to report +to CDash. + +When run as a :ref:`Dashboard Client`, CTest will include these custom +measurements in the ``Test.xml`` file that gets uploaded to CDash. + +Check the `CDash test measurement documentation +<https://github.com/Kitware/CDash/blob/master/docs/test_measurements.md>`_ +for more information on the types of test measurements that CDash recognizes. + +The following example demonstrates how to output a variety of custom test +measurements. + +.. code-block:: c++ + + std::cout << + "<DartMeasurement type=\"numeric/double\" name=\"score\">28.3</DartMeasurement>" + << std::endl; + + std::cout << + "<DartMeasurement type=\"text/string\" name=\"color\">red</DartMeasurement>" + << std::endl; + + std::cout << + "<DartMeasurement type=\"text/link\" name=\"CMake URL\">https://cmake.org</DartMeasurement>" + << std::endl; + + std::cout << + "<DartMeasurement type=\"text/preformatted\" name=\"Console Output\">" << + "line 1.\n" << + " \033[31;1m line 2. Bold red, and indented!\033[0;0ml\n" << + "line 3. Not bold or indented...\n" << + "</DartMeasurement>" << std::endl; + +Image Measurements +"""""""""""""""""" + +The following example demonstrates how to upload test images to CDash. + +.. code-block:: c++ + + std::cout << + "<DartMeasurementFile type=\"image/jpg\" name=\"TestImage\">" << + "/dir/to/test_img.jpg</DartMeasurementFile>" << std::endl; + + std::cout << + "<DartMeasurementFile type=\"image/gif\" name=\"ValidImage\">" << + "/dir/to/valid_img.gif</DartMeasurementFile>" << std::endl; + + std::cout << + "<DartMeasurementFile type=\"image/png\" name=\"AlgoResult\"> << + "/dir/to/img.png</DartMeasurementFile>" + << std::endl; + +Images will be displayed together in an interactive comparison mode on CDash +if they are provided with two or more of the following names. + +* ``TestImage`` +* ``ValidImage`` +* ``BaselineImage`` +* ``DifferenceImage2`` + +By convention, ``TestImage`` is the image generated by your test, and +``ValidImage`` (or ``BaselineImage``) is basis of comparison used to determine +if the test passed or failed. + +If another image name is used it will be displayed by CDash as a static image +separate from the interactive comparison UI. + +Attached Files +"""""""""""""" + +The following example demonstrates how to upload non-image files to CDash. + +.. code-block:: c++ + + std::cout << + "<DartMeasurementFile type=\"file\" name=\"MyTestInputData\">" << + "/dir/to/data.csv</DartMeasurementFile>" << std::endl; + +If the name of the file to upload is known at configure time, you can use the +:prop_test:`ATTACHED_FILES` or :prop_test:`ATTACHED_FILES_ON_FAIL` test +properties instead. + +Custom Details +"""""""""""""" + +The following example demonstrates how to specify a custom value for the +``Test Details`` field displayed on CDash. + +.. code-block:: c++ + + std::cout << + "<CTestDetails>My Custom Details Value</CTestDetails>" << std::endl; diff --git a/Help/command/enable_language.rst b/Help/command/enable_language.rst index ce765de..d2acbc8 100644 --- a/Help/command/enable_language.rst +++ b/Help/command/enable_language.rst @@ -10,7 +10,7 @@ Enables support for the named language in CMake. This is the same as the :command:`project` command but does not create any of the extra variables that are created by the project command. Example languages are ``CXX``, ``C``, ``CUDA``, ``OBJC``, ``OBJCXX``, ``Fortran``, -``ISPC``, and ``ASM``. +``HIP``, ``ISPC``, and ``ASM``. .. versionadded:: 3.8 Added ``CUDA`` support. @@ -21,6 +21,9 @@ are ``CXX``, ``C``, ``CUDA``, ``OBJC``, ``OBJCXX``, ``Fortran``, .. versionadded:: 3.18 Added ``ISPC`` support. +.. versionadded:: 3.21 + Added ``HIP`` support. + If enabling ``ASM``, enable it last so that CMake can check whether compilers for other languages like ``C`` work for assembly too. diff --git a/Help/command/file.rst b/Help/command/file.rst index 31de610..b6ed416 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -38,7 +38,8 @@ Synopsis `Filesystem`_ file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] [<globbing-expr>...]) - file(`RENAME`_ <oldname> <newname>) + file(`RENAME`_ <oldname> <newname> [...]) + file(`COPY_FILE`_ <oldname> <newname> [...]) file({`REMOVE`_ | `REMOVE_RECURSE`_ } [<files>...]) file(`MAKE_DIRECTORY`_ [<dir>...]) file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...]) @@ -49,7 +50,7 @@ Synopsis file(`CHMOD_RECURSE`_ <files>... <directories>... PERMISSIONS <permissions>... [...]) `Path Conversion`_ - file(`REAL_PATH`_ <path> <out-var> [BASE_DIRECTORY <dir>]) + file(`REAL_PATH`_ <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE]) file(`RELATIVE_PATH`_ <out-var> <directory> <file>) file({`TO_CMAKE_PATH`_ | `TO_NATIVE_PATH`_} <path> <out-var>) @@ -115,7 +116,8 @@ Parse a list of ASCII strings from ``<filename>`` and store it in binary while reading unless this option is given. ``REGEX <regex>`` - Consider only strings that match the given regular expression. + Consider only strings that match the given regular expression, + as described under :ref:`string(REGEX) <Regex Specification>`. ``ENCODING <encoding-type>`` .. versionadded:: 3.1 @@ -178,6 +180,8 @@ the ``<format>`` and ``UTC`` options. [PRE_EXCLUDE_REGEXES [<regexes>...]] [POST_INCLUDE_REGEXES [<regexes>...]] [POST_EXCLUDE_REGEXES [<regexes>...]] + [POST_INCLUDE_FILES [<files>...]] + [POST_EXCLUDE_FILES [<files>...]] ) .. versionadded:: 3.16 @@ -275,6 +279,18 @@ be resolved. See below for a full description of how they work. List of post-exclude regexes through which to filter the names of resolved dependencies. +``POST_INCLUDE_FILES <files>`` + .. versionadded:: 3.21 + + List of post-include filenames through which to filter the names of resolved + dependencies. Symlinks are resolved when attempting to match these filenames. + +``POST_EXCLUDE_FILES <files>`` + .. versionadded:: 3.21 + + List of post-exclude filenames through which to filter the names of resolved + dependencies. Symlinks are resolved when attempting to match these filenames. + These arguments can be used to exclude unwanted system libraries when resolving the dependencies, or to include libraries from a specific directory. The filtering works as follows: @@ -288,16 +304,18 @@ directory. The filtering works as follows: 4. ``file(GET_RUNTIME_DEPENDENCIES)`` searches for the dependency according to the linking rules of the platform (see below). 5. If the dependency is found, and its full path matches one of the - ``POST_INCLUDE_REGEXES``, the full path is added to the resolved - dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` recursively resolves - that library's own dependencies. Otherwise, resolution proceeds to step 6. + ``POST_INCLUDE_REGEXES`` or ``POST_INCLUDE_FILES``, the full path is added + to the resolved dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` + recursively resolves that library's own dependencies. Otherwise, resolution + proceeds to step 6. 6. If the dependency is found, but its full path matches one of the - ``POST_EXCLUDE_REGEXES``, it is not added to the resolved dependencies, and - dependency resolution stops for that dependency. + ``POST_EXCLUDE_REGEXES`` or ``POST_EXCLUDE_FILES``, it is not added to the + resolved dependencies, and dependency resolution stops for that dependency. 7. If the dependency is found, and its full path does not match either - ``POST_INCLUDE_REGEXES`` or ``POST_EXCLUDE_REGEXES``, the full path is added - to the resolved dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` - recursively resolves that library's own dependencies. + ``POST_INCLUDE_REGEXES``, ``POST_INCLUDE_FILES``, ``POST_EXCLUDE_REGEXES``, + or ``POST_EXCLUDE_FILES``, the full path is added to the resolved + dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` recursively resolves + that library's own dependencies. Different platforms have different rules for how dependencies are resolved. These specifics are described here. @@ -675,11 +693,46 @@ Examples of recursive globbing include:: .. code-block:: cmake - file(RENAME <oldname> <newname>) + file(RENAME <oldname> <newname> + [RESULT <result>] + [NO_REPLACE]) Move a file or directory within a filesystem from ``<oldname>`` to ``<newname>``, replacing the destination atomically. +The options are: + +``RESULT <result>`` + Set ``<result>`` variable to ``0`` on success or an error message otherwise. + If ``RESULT`` is not specified and the operation fails, an error is emitted. + +``NO_REPLACE`` + If the ``<newname>`` path already exists, do not replace it. + If ``RESULT <result>`` is used, the result variable will be + set to ``NO_REPLACE``. Otherwise, an error is emitted. + +.. _COPY_FILE: + +.. code-block:: cmake + + file(COPY_FILE <oldname> <newname> + [RESULT <result>] + [ONLY_IF_DIFFERENT]) + +Copy a file from ``<oldname>`` to ``<newname>``. Directories are not +supported. Symlinks are ignored and ``<oldfile>``'s content is read and +written to ``<newname>`` as a new file. + +The options are: + +``RESULT <result>`` + Set ``<result>`` variable to ``0`` on success or an error message otherwise. + If ``RESULT`` is not specified and the operation fails, an error is emitted. + +``ONLY_IF_DIFFERENT`` + If the ``<newname>`` path already exists, do not replace it if it is the + same as ``<oldname>``. Otherwise, an error is emitted. + .. _REMOVE: .. _REMOVE_RECURSE: @@ -888,16 +941,26 @@ Path Conversion .. code-block:: cmake - file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>]) + file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE]) .. versionadded:: 3.19 Compute the absolute path to an existing file or directory with symlinks resolved. -If the provided ``<path>`` is a relative path, it is evaluated relative to the -given base directory ``<dir>``. If no base directory is provided, the default -base directory will be :variable:`CMAKE_CURRENT_SOURCE_DIR`. +``BASE_DIRECTORY <dir>`` + If the provided ``<path>`` is a relative path, it is evaluated relative to the + given base directory ``<dir>``. If no base directory is provided, the default + base directory will be :variable:`CMAKE_CURRENT_SOURCE_DIR`. + +``EXPAND_TILDE`` + .. versionadded:: 3.21 + + If the ``<path>`` is ``~`` or starts with ``~/``, the ``~`` is replaced by + the user's home directory. The path to the home directory is obtained from + environment variables. On Windows, the ``USERPROFILE`` environment variable + is used, falling back to the ``HOME`` environment variable if ``USERPROFILE`` + is not defined. On all other platforms, only ``HOME`` is used. .. _RELATIVE_PATH: @@ -1024,7 +1087,7 @@ If neither ``NETRC`` option is given CMake will check variables For ``https://`` URLs CMake must be built with OpenSSL support. ``TLS/SSL`` certificates are not checked by default. Set ``TLS_VERIFY`` to ``ON`` to check certificates. If neither ``TLS`` option is given CMake will check -variables ``CMAKE_TLS_VERIFY`` and ``CMAKE_TLS_CAINFO``, respectively. +variables :variable:`CMAKE_TLS_VERIFY` and ``CMAKE_TLS_CAINFO``, respectively. Additional options to ``DOWNLOAD`` are: diff --git a/Help/command/foreach.rst b/Help/command/foreach.rst index 8de6deb..d9f54ca 100644 --- a/Help/command/foreach.rst +++ b/Help/command/foreach.rst @@ -14,9 +14,12 @@ semicolon or whitespace. All commands between ``foreach`` and the matching ``endforeach`` are recorded without being invoked. Once the ``endforeach`` is evaluated, the recorded list of commands is invoked once for each item in ``<items>``. -At the beginning of each iteration the variable ``loop_var`` will be set +At the beginning of each iteration the variable ``<loop_var>`` will be set to the value of the current item. +The scope of ``<loop_var>`` is restricted to the loop scope. See policy +:policy:`CMP0124` for details. + The commands :command:`break` and :command:`continue` provide means to escape from the normal control flow. diff --git a/Help/command/install.rst b/Help/command/install.rst index 35207f4..acfaa48 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -9,11 +9,13 @@ Synopsis .. parsed-literal:: install(`TARGETS`_ <target>... [...]) + install(`IMPORTED_RUNTIME_ARTIFACTS`_ <target>... [...]) install({`FILES`_ | `PROGRAMS`_} <file>... [...]) install(`DIRECTORY`_ <dir>... [...]) install(`SCRIPT`_ <file> [...]) install(`CODE`_ <code> [...]) install(`EXPORT`_ <export-name> [...]) + install(`RUNTIME_DEPENDENCY_SET`_ <set-name> [...]) Introduction ^^^^^^^^^^^^ @@ -124,6 +126,7 @@ Installing Targets .. code-block:: cmake install(TARGETS targets... [EXPORT <export-name>] + [RUNTIME_DEPENDENCIES args...|RUNTIME_DEPENDENCY_SET <set-name>] [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE| PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE] [DESTINATION <dir>] @@ -338,6 +341,34 @@ top level: relative path is specified, it is treated as relative to the ``$<INSTALL_PREFIX>``. +``RUNTIME_DEPENDENCY_SET`` + .. versionadded:: 3.21 + + This option causes all runtime dependencies of installed executable, shared + library, and module targets to be added to the specified runtime dependency + set. This set can then be installed later on with an + `install(RUNTIME_DEPENDENCY_SET)`_ command. + + This argument and the ``RUNTIME_DEPENDENCIES`` argument are mutually + exclusive. + +``RUNTIME_DEPENDENCIES`` + .. versionadded:: 3.21 + + This option causes all runtime dependencies of installed executable, shared + library, and module targets to be installed along with the targets + themselves. The ``RUNTIME``, ``LIBRARY``, ``FRAMEWORK``, and generic + arguments are used to determine the properties (``DESTINATION``, + ``COMPONENT``, etc.) of the installation of these dependencies. + + ``RUNTIME_DEPENDENCIES`` is semantically equivalent to calling + ``install(TARGETS ... RUNTIME_DEPENDENCY_SET)`` and then + `install(RUNTIME_DEPENDENCY_SET)`_ with a randomly generated name. It accepts + all of the same options as `install(RUNTIME_DEPENDENCY_SET)`_. + + This argument and the ``RUNTIME_DEPENDENCY_SET`` argument are mutually + exclusive. + One or more groups of properties may be specified in a single call to the ``TARGETS`` form of this command. A target may be installed more than once to different locations. Consider hypothetical targets ``myExe``, @@ -382,6 +413,48 @@ set to ``TRUE`` has undefined behavior. to ensure that such out-of-directory targets are built before the subdirectory-specific install rules are run. +Installing Imported Runtime Artifacts +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. _`install(IMPORTED_RUNTIME_ARTIFACTS)`: +.. _IMPORTED_RUNTIME_ARTIFACTS: + +.. versionadded:: 3.21 + +.. code-block:: cmake + + install(IMPORTED_RUNTIME_ARTIFACTS targets... + [RUNTIME_DEPENDENCY_SET <set-name>] + [[LIBRARY|RUNTIME|FRAMEWORK|BUNDLE] + [DESTINATION <dir>] + [PERMISSIONS permissions...] + [CONFIGURATIONS [Debug|Release|...]] + [COMPONENT <component>] + [OPTIONAL] [EXCLUDE_FROM_ALL] + ] [...] + ) + +The ``IMPORTED_RUNTIME_ARTIFACTS`` form specifies rules for installing the +runtime artifacts of imported targets. Projects may do this if they want to +bundle outside executables or modules inside their installation. The +``LIBRARY``, ``RUNTIME``, ``FRAMEWORK``, and ``BUNDLE`` arguments have the +same semantics that they do in the `TARGETS`_ mode. Only the runtime artifacts +of imported targets are installed (except in the case of :prop_tgt:`FRAMEWORK` +libraries, :prop_tgt:`MACOSX_BUNDLE` executables, and :prop_tgt:`BUNDLE` +CFBundles.) For example, headers and import libraries associated with DLLs are +not installed. In the case of :prop_tgt:`FRAMEWORK` libraries, +:prop_tgt:`MACOSX_BUNDLE` executables, and :prop_tgt:`BUNDLE` CFBundles, the +entire directory is installed. + +``IMPORTED_RUNTIME_ARTIFACTS`` accepts the following additional arguments: + +``RUNTIME_DEPENDENCY_SET`` + + This option causes all runtime dependencies of installed executable, shared + library, and module targets to be added to the specified runtime dependency + set. This set can then be installed later on with an + `install(RUNTIME_DEPENDENCY_SET)`_ command. + Installing Files ^^^^^^^^^^^^^^^^ @@ -540,7 +613,8 @@ any expression. For example, the code will extract and install header files from a source tree. -Some options may follow a ``PATTERN`` or ``REGEX`` expression and are applied +Some options may follow a ``PATTERN`` or ``REGEX`` expression as described +under :ref:`string(REGEX) <Regex Specification>` and are applied only to files or directories matching them. The ``EXCLUDE`` option will skip the matched file or directory. The ``PERMISSIONS`` option overrides the permissions setting for the matched file or directory. For @@ -619,7 +693,7 @@ Custom Installation Logic .. code-block:: cmake install([[SCRIPT <file>] [CODE <code>]] - [COMPONENT <component>] [EXCLUDE_FROM_ALL] [...]) + [COMPONENT <component>] [EXCLUDE_FROM_ALL] [ALL_COMPONENTS] [...]) The ``SCRIPT`` form will invoke the given CMake script files during installation. If the script file name is a relative path it will be @@ -634,6 +708,12 @@ example, the code will print a message during installation. +The option ``ALL_COMPONENTS`` + .. versionadded:: 3.21 + + Run the custom installation script code for every component of a + component-specific installation. + .. versionadded:: 3.14 ``<file>`` or ``<code>`` may use "generator expressions" with the syntax ``$<...>`` (in the case of ``<file>``, this refers to their use in the file @@ -724,7 +804,7 @@ executable from the installation tree using the imported target name ``mp_myexe`` as if the target were built in its own tree. .. note:: - This command supercedes the :command:`install_targets` command and + This command supersedes the :command:`install_targets` command and the :prop_tgt:`PRE_INSTALL_SCRIPT` and :prop_tgt:`POST_INSTALL_SCRIPT` target properties. It also replaces the ``FILES`` forms of the :command:`install_files` and :command:`install_programs` commands. @@ -733,6 +813,74 @@ executable from the installation tree using the imported target name :command:`install_files`, and :command:`install_programs` commands is not defined. +Installing Runtime Dependencies +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. _`install(RUNTIME_DEPENDENCY_SET)`: +.. _RUNTIME_DEPENDENCY_SET: + +.. versionadded:: 3.21 + +.. code-block:: cmake + + install(RUNTIME_DEPENDENCY_SET <set-name> + [[LIBRARY|RUNTIME|FRAMEWORK] + [DESTINATION <dir>] + [PERMISSIONS permissions...] + [CONFIGURATIONS [Debug|Release|...]] + [COMPONENT <component>] + [NAMELINK_COMPONENT <component>] + [OPTIONAL] [EXCLUDE_FROM_ALL] + ] [...] + [PRE_INCLUDE_REGEXES regexes...] + [PRE_EXCLUDE_REGEXES regexes...] + [POST_INCLUDE_REGEXES regexes...] + [POST_EXCLUDE_REGEXES regexes...] + [DIRECTORIES directories...] + ) + +Installs a runtime dependency set created by one or more +`install(TARGETS)`_ or `install(IMPORTED_RUNTIME_ARTIFACTS)`_ commands. The +dependencies of targets belonging to a runtime dependency set are installed in +the ``RUNTIME`` destination and component on DLL platforms, and in the +``LIBRARY`` destination and component on non-DLL platforms. macOS frameworks +are installed in the ``FRAMEWORK`` destination and component. The generated +install script calls :command:`file(GET_RUNTIME_DEPENDENCIES)` on the +build-tree files to calculate the runtime dependencies, with the build-tree +executable files as the ``EXECUTABLES`` argument, the build-tree shared +libraries as the ``LIBRARIES`` argument, and the build-tree modules as the +``MODULES`` argument. If one of the executables is a :prop_tgt:`MACOSX_BUNDLE` +executable on a macOS platform, that executable is passed as the +``BUNDLE_EXECUTABLE`` argument. If ``RUNTIME_DEPENDENCY_SET`` is specified on +a macOS platform, at most one :prop_tgt:`MACOSX_BUNDLE` executable may be in +the runtime dependency set. The :prop_tgt:`MACOSX_BUNDLE` property has no +effect on non-macOS platforms. Targets built within the build tree will never +be installed as runtime dependencies, nor will their own dependencies, unless +the targets themselves are installed with `install(TARGETS)`_. + +This argument accepts the following sub-arguments: + +``DIRECTORIES <directories>`` + List of directories to be passed as the ``DIRECTORIES`` argument of + :command:`file(GET_RUNTIME_DEPENDENCIES)`. This argument supports + :manual:`generator expressions <cmake-generator-expressions(7)>`. If a + ``DIRECTORIES`` argument evaluates to an empty string, it is not passed to + :command:`file(GET_RUNTIME_DEPENDENCIES)`. + +``PRE_INCLUDE_REGEXES <regexes>``, ``PRE_EXCLUDE_REGEXES <regexes>``, ``POST_INCLUDE_REGEXES <regexes>``, ``POST_EXCLUDE_REGEXES <regexes>`` + List of regular expressions to be passed as their respective arguments to + :command:`file(GET_RUNTIME_DEPENDENCIES)`. These arguments support + :manual:`generator expressions <cmake-generator-expressions(7)>`. If an + argument evaluates to an empty string, it is not passed to + :command:`file(GET_RUNTIME_DEPENDENCIES)`. + +``POST_INCLUDE_FILES <files>``, ``POST_EXCLUDE_FILES <files>`` + List of files to be passed as their respective arguments to + :command:`file(GET_RUNTIME_DEPENDENCIES)`. These arguments support + :manual:`generator expressions <cmake-generator-expressions(7)>`. If an + argument evaluates to an empty string, it is not passed to + :command:`file(GET_RUNTIME_DEPENDENCIES)`. + Generated Installation Script ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/command/install_files.rst b/Help/command/install_files.rst index ff074a8..494f3d0 100644 --- a/Help/command/install_files.rst +++ b/Help/command/install_files.rst @@ -5,7 +5,7 @@ install_files Use the :command:`install(FILES)` command instead. -This command has been superceded by the :command:`install` command. It is +This command has been superseded by the :command:`install` command. It is provided for compatibility with older CMake code. The ``FILES`` form is directly replaced by the ``FILES`` form of the :command:`install` command. The regexp form can be expressed more clearly using the ``GLOB`` diff --git a/Help/command/install_programs.rst b/Help/command/install_programs.rst index fab6482..eafae89 100644 --- a/Help/command/install_programs.rst +++ b/Help/command/install_programs.rst @@ -5,7 +5,7 @@ install_programs Use the :command:`install(PROGRAMS)` command instead. -This command has been superceded by the :command:`install` command. It is +This command has been superseded by the :command:`install` command. It is provided for compatibility with older CMake code. The ``FILES`` form is directly replaced by the ``PROGRAMS`` form of the :command:`install` command. The regexp form can be expressed more clearly using the ``GLOB`` diff --git a/Help/command/install_targets.rst b/Help/command/install_targets.rst index c9efdce..9355f8d 100644 --- a/Help/command/install_targets.rst +++ b/Help/command/install_targets.rst @@ -5,7 +5,7 @@ install_targets Use the :command:`install(TARGETS)` command instead. -This command has been superceded by the :command:`install` command. It is +This command has been superseded by the :command:`install` command. It is provided for compatibility with older CMake code. :: diff --git a/Help/command/list.rst b/Help/command/list.rst index 7accc5a..f46641f 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -141,8 +141,8 @@ Appends elements to the list. Includes or removes items from the list that match the mode's pattern. In ``REGEX`` mode, items will be matched against the given regular expression. -For more information on regular expressions see also the -:command:`string` command. +For more information on regular expressions look under +:ref:`string(REGEX) <Regex Specification>`. .. _INSERT: diff --git a/Help/command/project.rst b/Help/command/project.rst index 6c931b6..2a9dcfe 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -20,12 +20,18 @@ Sets the name of the project, and stores it in the variable ``CMakeLists.txt`` also stores the project name in the variable :variable:`CMAKE_PROJECT_NAME`. -Also sets the variables +Also sets the variables: -* :variable:`PROJECT_SOURCE_DIR`, - :variable:`<PROJECT-NAME>_SOURCE_DIR` -* :variable:`PROJECT_BINARY_DIR`, - :variable:`<PROJECT-NAME>_BINARY_DIR` +:variable:`PROJECT_SOURCE_DIR`, :variable:`<PROJECT-NAME>_SOURCE_DIR` + Absolute path to the source directory for the project. + +:variable:`PROJECT_BINARY_DIR`, :variable:`<PROJECT-NAME>_BINARY_DIR` + Absolute path to the binary directory for the project. + +:variable:`PROJECT_IS_TOP_LEVEL`, :variable:`<PROJECT-NAME>_IS_TOP_LEVEL` + .. versionadded:: 3.21 + + Boolean value indicating whether the project is top-level. Further variables are set by the optional arguments described in the following. If any of these arguments is not used, then the corresponding variables are @@ -97,7 +103,7 @@ The options are: Selects which programming languages are needed to build the project. Supported languages include ``C``, ``CXX`` (i.e. C++), ``CUDA``, - ``OBJC`` (i.e. Objective-C), ``OBJCXX``, ``Fortran``, ``ISPC``, and ``ASM``. + ``OBJC`` (i.e. Objective-C), ``OBJCXX``, ``Fortran``, ``HIP``, ``ISPC``, and ``ASM``. By default ``C`` and ``CXX`` are enabled if no language options are given. Specify language ``NONE``, or use the ``LANGUAGES`` keyword and list no languages, to skip enabling any languages. diff --git a/Help/command/set.rst b/Help/command/set.rst index c0e02e2..af862e4 100644 --- a/Help/command/set.rst +++ b/Help/command/set.rst @@ -68,9 +68,13 @@ users. If the cache entry does not exist prior to the call or the ``FORCE`` option is given then the cache entry will be set to the given value. -Furthermore, any normal variable binding in the current scope will -be removed to expose the newly cached value to any immediately -following evaluation. + +.. note:: + + The content of the cache variable will not be directly accessible if a normal + variable of the same name already exists (see :ref:`rules of variable + evaluation <CMake Language Variables>`). If policy :policy:`CMP0126` is set + to ``OLD``, any normal variable binding in the current scope will be removed. It is possible for the cache entry to exist prior to the call but have no type set if it was created on the :manual:`cmake(1)` command diff --git a/Help/command/source_group.rst b/Help/command/source_group.rst index 5db1ec8..a4b5bf1 100644 --- a/Help/command/source_group.rst +++ b/Help/command/source_group.rst @@ -11,6 +11,9 @@ There are two different signatures to create source groups. Defines a group into which sources will be placed in project files. This is intended to set up file tabs in Visual Studio. +The group is scoped in the directory where the command is called, +and applies to sources in targets created in that directory. + The options are: ``TREE`` diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index 872e264..ac231bc 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -289,6 +289,91 @@ treated as :ref:`Interface Libraries`, but when they appear in a target's :prop_tgt:`LINK_LIBRARIES` property their object files will be included in the link too. +.. _`Linking Object Libraries via $<TARGET_OBJECTS>`: + +Linking Object Libraries via $<TARGET_OBJECTS> +"""""""""""""""""""""""""""""""""""""""""""""" + +.. versionadded:: 3.21 + +The object files associated with an object library may be referenced +by the :genex:`$<TARGET_OBJECTS>` generator expression. Such object +files are placed on the link line *before* all libraries, regardless +of their relative order. Additionally, an ordering dependency will be +added to the build sysstem to make sure the object library is up-to-date +before the dependent target links. For example, the code + +.. code-block:: cmake + + add_library(obj3 OBJECT obj3.c) + target_compile_definitions(obj3 PUBLIC OBJ3) + + add_executable(main3 main3.c) + target_link_libraries(main3 PRIVATE a3 $<TARGET_OBJECTS:obj3> b3) + +links executable ``main3`` with object files from ``main3.c`` +and ``obj3.c`` followed by the ``a3`` and ``b3`` libraries. +``main3.c`` is *not* compiled with usage requirements from ``obj3``, +such as ``-DOBJ3``. + +This approach can be used to achieve transitive inclusion of object +files in link lines as usage requirements. Continuing the above +example, the code + +.. code-block:: cmake + + add_library(iface_obj3 INTERFACE) + target_link_libraries(iface_obj3 INTERFACE obj3 $<TARGET_OBJECTS:obj3>) + +creates an interface library ``iface_obj3`` that forwards the ``obj3`` +usage requirements and adds the ``obj3`` object files to dependents' +link lines. The code + +.. code-block:: cmake + + add_executable(use_obj3 use_obj3.c) + target_link_libraries(use_obj3 PRIVATE iface_obj3) + +compiles ``use_obj3.c`` with ``-DOBJ3`` and links executable ``use_obj3`` +with object files from ``use_obj3.c`` and ``obj3.c``. + +This also works transitively through a static library. Since a static +library does not link, it does not consume the object files from +object libraries referenced this way. Instead, the object files +become transitive link dependencies of the static library. +Continuing the above example, the code + +.. code-block:: cmake + + add_library(static3 STATIC static3.c) + target_link_libraries(static3 PRIVATE iface_obj3) + + add_executable(use_static3 use_static3.c) + target_link_libraries(use_static3 PRIVATE static3) + +compiles ``static3.c`` with ``-DOBJ3`` and creates ``libstatic3.a`` +using only its own object file. ``use_static3.c`` is compiled *without* +``-DOBJ3`` because the usage requirement is not transitive through +the private dependency of ``static3``. However, the link dependencies +of ``static3`` are propagated, including the ``iface_obj3`` reference +to ``$<TARGET_OBJECTS:obj3>``. The ``use_static3`` executable is +created with object files from ``use_static3.c`` and ``obj3.c``, and +linked to library ``libstatic3.a``. + +When using this approach, it is the project's responsibility to avoid +linking multiple dependent binaries to ``iface_obj3``, because they will +all get the ``obj3`` object files on their link lines. + +.. note:: + + Referencing :genex:`$<TARGET_OBJECTS>` in ``target_link_libraries`` + calls worked in versions of CMake prior to 3.21 for some cases, + but was not fully supported: + + * It did not place the object files before libraries on link lines. + * It did not add an ordering dependency on the object library. + * It did not work in Xcode with multiple architectures. + Cyclic Dependencies of Static Libraries ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |