diff options
| -rw-r--r-- | Help/command/cmake_language.rst | 14 | ||||
| -rw-r--r-- | Help/command/configure_file.rst | 2 | ||||
| -rw-r--r-- | Help/command/execute_process.rst | 14 | ||||
| -rw-r--r-- | Help/command/file.rst | 51 | ||||
| -rw-r--r-- | Help/command/find_package.rst | 3 | ||||
| -rw-r--r-- | Help/command/separate_arguments.rst | 2 | ||||
| -rw-r--r-- | Help/command/string.rst | 16 | ||||
| -rw-r--r-- | Help/cpack_gen/external.rst | 6 | ||||
| -rw-r--r-- | Help/policy/CMP0112.rst | 6 | ||||
| -rw-r--r-- | Help/policy/CMP0114.rst | 2 | ||||
| -rw-r--r-- | Help/release/3.19.rst | 60 | ||||
| -rw-r--r-- | Modules/CMakePackageConfigHelpers.cmake | 4 | ||||
| -rw-r--r-- | Modules/CheckCompilerFlag.cmake | 2 | ||||
| -rw-r--r-- | Modules/CheckLinkerFlag.cmake | 15 |
14 files changed, 107 insertions, 90 deletions
diff --git a/Help/command/cmake_language.rst b/Help/command/cmake_language.rst index 00e1a69..40a45e3 100644 --- a/Help/command/cmake_language.rst +++ b/Help/command/cmake_language.rst @@ -134,14 +134,14 @@ The options are: ``ID <id>`` Specify an identification for the deferred call. - The id may not be empty and may not begin in a capital letter ``A-Z``. - The id may begin in a ``_`` only if it was generated by another call - that used ``ID_VAR`` to get the id. + The ``<id>`` may not be empty and may not begin with a capital letter ``A-Z``. + The ``<id>`` may begin with an underscore (``_``) only if it was generated + automatically by an earlier call that used ``ID_VAR`` to get the id. ``ID_VAR <var>`` - Sepcify a variable in which to store the identification for the + Specify a variable in which to store the identification for the deferred call. If ``ID <id>`` is not given, a new identification - will be generated starting in a ``_``. + will be generated and the generated id will start with an underscore (``_``). The currently scheduled list of deferred calls may be retrieved: @@ -149,7 +149,7 @@ The currently scheduled list of deferred calls may be retrieved: cmake_language(DEFER [DIRECTORY <dir>] GET_CALL_IDS <var>) -This will store in ``<var>`` a :ref:`Semicolon-separated list <CMake Language +This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language Lists>` of deferred call ids. Details of a specific call may be retrieved from its id: @@ -158,7 +158,7 @@ Details of a specific call may be retrieved from its id: cmake_language(DEFER [DIRECTORY <dir>] GET_CALL <id> <var>) -This will store in ``<var>`` a :ref:`Semicolon-separated list <CMake Language +This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language Lists>` in which the first element is the name of the command to be called, and the remaining elements are its unevaluated arguments (any contained ``;`` characters are included literally and cannot be distinguished diff --git a/Help/command/configure_file.rst b/Help/command/configure_file.rst index 46d1a05..c59995a 100644 --- a/Help/command/configure_file.rst +++ b/Help/command/configure_file.rst @@ -83,7 +83,7 @@ The arguments are: Restrict variable replacement to references of the form ``@VAR@``. This is useful for configuring scripts that use ``${VAR}`` syntax. - ``NO_SOURCE_PERMISSIONS`` +``NO_SOURCE_PERMISSIONS`` Does not transfer the file permissions of the original file to the copy. The copied file permissions default to the standard 644 value (-rw-r--r--). diff --git a/Help/command/execute_process.rst b/Help/command/execute_process.rst index a6f141a..268c307 100644 --- a/Help/command/execute_process.rst +++ b/Help/command/execute_process.rst @@ -118,9 +118,17 @@ Options: This is analogous to the ``tee`` Unix command. ``COMMAND_ERROR_IS_FATAL <ANY|LAST>`` - ``COMMAND_ERROR_IS_FATAL ANY`` option stops processing if any command fails. - ``COMMAND_ERROR_IS_FATAL LAST`` option stops processing if the last command - in the command list fails. + The option following ``COMMAND_ERROR_IS_FATAL`` determines the behavior when + an error is encountered: + + ``ANY`` + If any of the commands in the list of commands fail, the + ``execute_process()`` command halts with an error. + + ``LAST`` + If the last command in the list of commands fails, the + ``execute_process()`` command halts with an error. Commands earlier in the + list will not cause a fatal error. If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the same pipe the precedence is not specified. diff --git a/Help/command/file.rst b/Help/command/file.rst index 4210bd4..b406e10 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -54,7 +54,7 @@ Synopsis file({`TO_CMAKE_PATH`_ | `TO_NATIVE_PATH`_} <path> <out-var>) `Transfer`_ - file(`DOWNLOAD`_ <url> <file> [...]) + file(`DOWNLOAD`_ <url> [<file>] [...]) file(`UPLOAD`_ <file> <url> [...]) `Locking`_ @@ -498,8 +498,9 @@ from the input content to produce the output content. The options are: See policy :policy:`CMP0070`. ``TARGET <target>`` - Specify target which to use when evaluating generator expressions. Enables - use of generator expressions requiring a target. + Specify which target to use when evaluating generator expressions that + require a target for evaluation (e.g. ``$<COMPILE_FEATURES:...>``, + ``$<TARGET_PROPERTY:prop>``). Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific ``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``. @@ -763,7 +764,8 @@ which would make them unable to support a hard link. .. code-block:: cmake - file(CHMOD <files>... <directories>... [PERMISSIONS <permissions>...] + file(CHMOD <files>... <directories>... + [PERMISSIONS <permissions>...] [FILE_PERMISSIONS <permissions>...] [DIRECTORY_PERMISSIONS <permissions>...]) @@ -775,34 +777,36 @@ Valid permissions are ``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``, Valid combination of keywords are: ``PERMISSIONS`` - all items are changed + All items are changed. ``FILE_PERMISSIONS`` - only files are changed + Only files are changed. ``DIRECTORY_PERMISSIONS`` - only directories are changed + Only directories are changed. ``PERMISSIONS`` and ``FILE_PERMISSIONS`` - ``FILE_PERMISSIONS`` overrides ``PERMISSIONS`` for files + ``FILE_PERMISSIONS`` overrides ``PERMISSIONS`` for files. ``PERMISSIONS`` and ``DIRECTORY_PERMISSIONS`` - ``DIRECTORY_PERMISSIONS`` overrides ``PERMISSIONS`` for directories + ``DIRECTORY_PERMISSIONS`` overrides ``PERMISSIONS`` for directories. ``FILE_PERMISSIONS`` and ``DIRECTORY_PERMISSIONS`` - use ``FILE_PERMISSIONS`` for files and ``DIRECTORY_PERMISSIONS`` for - directories + Use ``FILE_PERMISSIONS`` for files and ``DIRECTORY_PERMISSIONS`` for + directories. .. _CHMOD_RECURSE: .. code-block:: cmake - file(CHMOD_RECURSE <files>... <directories>... PERMISSIONS <permissions>... - FILE_PERMISSIONS <permissions>... DIRECTORY_PERMISSIONS <permissions>...) + file(CHMOD_RECURSE <files>... <directories>... + [PERMISSIONS <permissions>...] + [FILE_PERMISSIONS <permissions>...] + [DIRECTORY_PERMISSIONS <permissions>...]) Same as `CHMOD`_, but change the permissions of files and directories present in -the ``<directories>..`` recursively. +the ``<directories>...`` recursively. Path Conversion ^^^^^^^^^^^^^^^ @@ -859,11 +863,11 @@ Transfer file(DOWNLOAD <url> [<file>] [<options>...]) file(UPLOAD <file> <url> [<options>...]) -The ``DOWNLOAD`` mode downloads the given ``<url>`` to a local ``<file>``. If -``<file>`` is not specified for ``file(DOWNLOAD)``, the file is not saved. This -can be useful if you want to know if a file can be downloaded (for example, to -check that it exists) without actually saving it anywhere. The ``UPLOAD`` mode -uploads a local ``<file>`` to a given ``<url>``. +The ``DOWNLOAD`` subcommand downloads the given ``<url>`` to a local ``<file>``. +If ``<file>`` is not specified for ``file(DOWNLOAD)``, the file is not saved. +This can be useful if you want to know if a file can be downloaded (for example, +to check that it exists) without actually saving it anywhere. The ``UPLOAD`` +mode uploads a local ``<file>`` to a given ``<url>``. Options to both ``DOWNLOAD`` and ``UPLOAD`` are: @@ -986,8 +990,7 @@ Archiving file(ARCHIVE_CREATE OUTPUT <archive> PATHS <paths>... [FORMAT <format>] - [COMPRESSION <compression>] - [COMPRESSION_LEVEL <compression level>] + [COMPRESSION <compression> [COMPRESSION_LEVEL <compression-level>]] [MTIME <mtime>] [VERBOSE]) @@ -1005,9 +1008,9 @@ compression. The other formats use no compression by default, but can be directed to do so with the ``COMPRESSION`` option. Valid values for ``<compression>`` are ``None``, ``BZip2``, ``GZip``, ``XZ``, and ``Zstd``. -Compression level can be specied by using ``COMPRESSION_LEVEL`` option. -Compression level should be between 0-9. 0 is the default compression. -``COMPRESSION`` option must be specified for ``COMPRESSION_LEVEL``. +The compression level can be specified with the ``COMPRESSION_LEVEL`` option. +The ``<compression-level>`` should be between 0-9, with the default being 0. +The ``COMPRESSION`` option must be present when ``COMPRESSION_LEVEL`` is given. .. note:: With ``FORMAT`` set to ``raw`` only one file will be compressed with the diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 87265ce..1be2e09 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -44,7 +44,8 @@ specified: * A version range with the format ``versionMin...[<]versionMax`` where ``versionMin`` and ``versionMax`` have the same format as the single version. By default, both end points are included. By specifying ``<``, - the upper end point will be excluded. + the upper end point will be excluded. Version ranges are only supported + with CMake 3.19 or later. The ``EXACT`` option requests that the version be matched exactly. This option is incompatible with the specification of a version range. diff --git a/Help/command/separate_arguments.rst b/Help/command/separate_arguments.rst index 3c094aa..69fb726 100644 --- a/Help/command/separate_arguments.rst +++ b/Help/command/separate_arguments.rst @@ -37,7 +37,7 @@ be one of the following keywords: ``PROGRAM`` The first item in ``<args>`` is assumed to be an executable and will be - search in the system search path or left as a full path. If not found, + searched in the system search path or left as a full path. If not found, ``<variable>`` will be empty. Otherwise, ``<variable>`` is a list of 2 elements: diff --git a/Help/command/string.rst b/Help/command/string.rst index 0bc2b48..0c2f57e 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -484,12 +484,12 @@ where each ``x`` represents a lower case hexadecimal character. Where required, an uppercase representation can be requested with the optional ``UPPER`` flag. +.. _JSON: + JSON ^^^^ -.. _JSON: - -Functionality for querying a JSON string +Functionality for querying a JSON string. .. _GET: .. code-block:: cmake @@ -522,7 +522,7 @@ will be set to one of ``NULL``, ``NUMBER``, ``STRING``, ``BOOLEAN``, MEMBER <json-string> [<member|index> ...] <index>) -Get the name of the ``<index>``:th member in ``<json-string>`` at the location +Get the name of the ``<index>``-th member in ``<json-string>`` at the location given by the list of ``<member|index>`` arguments. Requires an element of object type. @@ -534,7 +534,7 @@ Requires an element of object type. Get the length of an element in ``<json-string>`` at the location given by the list of ``<member|index>`` arguments. -Required an element of array or object type. +Requires an element of array or object type. .. _REMOVE: .. code-block:: cmake @@ -544,7 +544,7 @@ Required an element of array or object type. Remove an element from ``<json-string>`` at the location given by the list of ``<member|index>`` arguments. The JSON string -without the removed element will we written in ``<out-var>``. +without the removed element will be stored in ``<out-var>``. .. _SET: .. code-block:: cmake @@ -566,8 +566,8 @@ Compare the two JSON objects given by ``<json-string1>`` and ``<json-string2>`` for equality -If the optional ``ERROR_VARIABLE`` argument is given errors will be -reported in ``<error-variable>``. If no error occurs the ``<error-variable>`` +If the optional ``ERROR_VARIABLE`` argument is given, errors will be +reported in ``<error-variable>``. If no error occurs, the ``<error-variable>`` will be set to ``NOTFOUND``. If ``ERROR_VARIABLE`` is not set a CMake error will be issued. When an error occurs the ``<out-var>`` will be set to diff --git a/Help/cpack_gen/external.rst b/Help/cpack_gen/external.rst index 7ef1071..e54b356 100644 --- a/Help/cpack_gen/external.rst +++ b/Help/cpack_gen/external.rst @@ -285,6 +285,6 @@ Variables specific to CPack External generator .. variable:: CPACK_EXTERNAL_BUILT_PACKAGES The ``CPACK_EXTERNAL_PACKAGE_SCRIPT`` script may set this list variable to the - full paths of generated package files. CPack copy these files from the stage - directory back to the top build directory and possibly produce checksum files - if the :variable:`CPACK_PACKAGE_CHECKSUM` is set. + full paths of generated package files. CPack will copy these files from the + staging directory back to the top build directory and possibly produce + checksum files if the :variable:`CPACK_PACKAGE_CHECKSUM` is set. diff --git a/Help/policy/CMP0112.rst b/Help/policy/CMP0112.rst index 3eab6d2..78a9055 100644 --- a/Help/policy/CMP0112.rst +++ b/Help/policy/CMP0112.rst @@ -21,13 +21,13 @@ file name components no longer add a dependency on the evaluated target. In CMake 3.18 and lower a dependency on the evaluated target of the above -generator expressions would be always added. CMake 3.19 and above prefer +generator expressions would always be added. CMake 3.19 and above prefer to not add this dependency. This policy provides compatibility for projects that have not been updated to expect the new behavior. The ``OLD`` behavior for this policy is to add a dependency on the evaluated -target for the the above generator expressions. The ``NEW`` behavior of -this policy is to not add a dependency on the evaluated target for the the +target for the above generator expressions. The ``NEW`` behavior of +this policy is to not add a dependency on the evaluated target for the above generator expressions. This policy was introduced in CMake version 3.19. Unlike many policies, diff --git a/Help/policy/CMP0114.rst b/Help/policy/CMP0114.rst index 1bc1216..ae48478 100644 --- a/Help/policy/CMP0114.rst +++ b/Help/policy/CMP0114.rst @@ -47,7 +47,7 @@ a revised design to address these problems: * The ``download``, ``update``, and ``patch`` steps are independent. * The ``configure``, ``build``, ``test``, and ``install`` steps are not. - For custom steps, the :command:`ExternalProject_Add_Step` command provies + For custom steps, the :command:`ExternalProject_Add_Step` command provides an ``INDEPENDENT`` option to mark them as independent. It is an error to mark a step as independent if it depends on other steps that are not. Note that this use of the term "independent" refers only to independence from diff --git a/Help/release/3.19.rst b/Help/release/3.19.rst index 93e060e..6e46452 100644 --- a/Help/release/3.19.rst +++ b/Help/release/3.19.rst @@ -14,7 +14,8 @@ Presets ------- * :manual:`cmake(1)` and :manual:`cmake-gui(1)` now recognize - ``CMakePresets.json`` and ``CMakeUserPresets.json`` files. + ``CMakePresets.json`` and ``CMakeUserPresets.json`` files (see + :manual:`cmake-presets(7)`). Generators ---------- @@ -105,21 +106,22 @@ Commands * The :command:`file(GENERATE)` command gained a new ``TARGET`` keyword to support resolving target-dependent generator expressions. -* The :command:`file` gained sub-command `REAL_PATH` to compute a path with - symlinks resolved. +* The :command:`file` command gained a new ``REAL_PATH`` sub-command to + compute a path with symlinks resolved. * The :command:`find_package` command learned to handle a version range. -* The :command:`separate_arguments` command gained new ``PROGRAM`` option to - search program. +* The :command:`separate_arguments` command gained a new ``PROGRAM`` option. + It allows the arguments to be treated as a program invocation and will + resolve the executable to a full path if it can be found. -* The :command:`set_property`, :command:`get_property`, - and :command:`get_directory_property` commands' ``DIRECTORY`` - options now accept references to binary directory paths, - such as the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. +* The ``DIRECTORY`` option of the :command:`set_property`, + :command:`get_property`, and :command:`get_directory_property` commands + now accepts references to binary directory paths, such as the value of + :variable:`CMAKE_CURRENT_BINARY_DIR`. -* The :command:`string` command gained set of new ``JSON`` sub commands - to provide JSON parsing capabilities. +* The :command:`string` command gained a set of new ``JSON`` sub commands + that provide JSON parsing capabilities. Variables --------- @@ -134,6 +136,9 @@ Variables initialize the new :prop_tgt:`OPTIMIZE_DEPENDENCIES` target property and avoid unnecessarily building dependencies for a static library. +* The :variable:`CMAKE_PCH_INSTANTIATE_TEMPLATES` variable was added to + initialize the new :prop_tgt:`PCH_INSTANTIATE_TEMPLATES` target property. + * The :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM` variable was added to tell the :ref:`Visual Studio Generators` what maximum version of the Windows SDK to choose. @@ -149,8 +154,8 @@ Properties * The :prop_tgt:`PCH_INSTANTIATE_TEMPLATES` target property was added to enable template instantiation in the precompiled header. This is enabled by default - and offers a roughly 20% compile time improvement. Currently only supported - by Clang 11. + and may significantly improve compile times. Currently only supported for + Clang (version 11 or later). * The :prop_tgt:`WIN32_EXECUTABLE` target property now supports :manual:`generator expressions <cmake-generator-expressions(7)>`. @@ -175,19 +180,20 @@ Modules :module:`CheckCXXSourceRuns` to more languages. It also supports the ``CUDA`` language. -* :module:`CMakePackageConfigHelpers` module learned to manage version range. +* The :module:`CMakePackageConfigHelpers` module gained support for version + ranges. * The :module:`FindCUDAToolkit` module gained support for finding CUDA toolkits that do not contain ``nvcc``, as well as for finding scattered toolkit installations when cross-compiling. * The :module:`FindPackageHandleStandardArgs` module learned to handle - version range. It also gained the ``find_package_check_version()`` command to - check the validity of a version against version-related arguments of + version ranges. It also gained the ``find_package_check_version()`` command + to check the validity of a version against version-related arguments of :command:`find_package` command. * The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython` - modules gained the capability to manage a version range. + modules gained the ability to handle a version range. * The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython` modules provide, respectively, the variable ``Python3_LINK_OPTIONS``, @@ -195,14 +201,14 @@ Modules * The :module:`FindSDL` module now provides: - * imported target ``SDL::SDL``, + * An imported target ``SDL::SDL``. - * result variables ``SDL_LIBRARIES`` and ``SDL_INCLUDE_DIRS``, + * Result variables ``SDL_LIBRARIES`` and ``SDL_INCLUDE_DIRS``. - * version variables ``SDL_VERSION``, ``SDL_VERSION_MAJOR`` + * Version variables ``SDL_VERSION``, ``SDL_VERSION_MAJOR``, ``SDL_VERSION_MINOR``, and ``SDL_VERSION_PATCH``. -* :module:`FindSWIG` module gains the capability to manage a version range. +* The :module:`FindSWIG` module gained the ability to handle a version range. * The :module:`FindTIFF` module gained a ``CXX`` component to find the ``tiffxx`` library containing C++ bindings. @@ -211,15 +217,17 @@ Modules target and associated ``Vulkan_GLSLC_EXECUTABLE`` variable which contain the path to the GLSL SPIR-V compiler. -* :module:`UseSWIG` module gains new source file properties ``OUTPUT_DIR`` and - ``OUTFILE_DIR`` to manage output directories on per source basis. +* The :module:`UseSWIG` module gained support for new source file properties + ``OUTPUT_DIR`` and ``OUTFILE_DIR`` to manage output directories on a + per-source basis. CTest ----- -* :manual:`ctest(1)` now supports ``compute-sanitizer`` (``cuda-memcheck``) as - ``CTEST_MEMORYCHECK_COMMAND``. The different tools (memcheck, racecheck, - synccheck, initcheck) supplied by ``compute-sanitizer`` can be selected by +* :manual:`ctest(1)` now supports the CUDA ``compute-sanitizer`` checker + (previously known as ``cuda-memcheck``) as the ``CTEST_MEMORYCHECK_COMMAND``. + The different tools (``memcheck``, ``racecheck``, ``synccheck`` and + ``initcheck``) supported by ``compute-sanitizer`` can be selected by adding appropriate flags to the ``CTEST_MEMORYCHECK_COMMAND_OPTIONS`` variable. The default flags are ``--tool memcheck --leak-check full``. diff --git a/Modules/CMakePackageConfigHelpers.cmake b/Modules/CMakePackageConfigHelpers.cmake index 50d7605..1a7f9cf 100644 --- a/Modules/CMakePackageConfigHelpers.cmake +++ b/Modules/CMakePackageConfigHelpers.cmake @@ -161,8 +161,8 @@ macro. .. note:: ``COMPATIBILITY_MODE`` ``AnyNewerVersion`` handles the version range if any is specified (see :command:`find_package` command for the details). - All other modes are incompatible with version range and will display an - author warning if a one is specified. + All other modes are incompatible with version ranges and will display an + author warning if one is specified. If ``ARCH_INDEPENDENT`` is given, the installed package version will be considered compatible even if it was built for a different architecture than diff --git a/Modules/CheckCompilerFlag.cmake b/Modules/CheckCompilerFlag.cmake index 3ce1b9b..d7789df 100644 --- a/Modules/CheckCompilerFlag.cmake +++ b/Modules/CheckCompilerFlag.cmake @@ -19,7 +19,7 @@ Check that the ``<flag>`` is accepted by the compiler without a diagnostic. Stores the result in an internal cache entry named ``<var>``. This command temporarily sets the ``CMAKE_REQUIRED_DEFINITIONS`` variable -and calls the ``check_source_compiles(<LANG>`` function from the +and calls the ``check_source_compiles(<LANG>)`` function from the :module:`CheckSourceCompiles` module. See documentation of that module for a listing of variables that can otherwise modify the build. diff --git a/Modules/CheckLinkerFlag.cmake b/Modules/CheckLinkerFlag.cmake index f56d365..3c7a828 100644 --- a/Modules/CheckLinkerFlag.cmake +++ b/Modules/CheckLinkerFlag.cmake @@ -19,15 +19,12 @@ Check that the link ``<flag>`` is accepted by the ``<lang>`` compiler without a diagnostic. Stores the result in an internal cache entry named ``<var>``. This command temporarily sets the ``CMAKE_REQUIRED_LINK_OPTIONS`` variable -and calls the ``check_<lang>_source_compiles`` macro from the -``Check<lang>SourceCompiles`` module (:module:`CheckCSourceCompiles`, -:module:`CheckCSourceCompiles`, :module:`CheckCXXSourceCompiles`, -:module:`CheckOBJCSourceCompiles`, :module:`CheckOBJCXXSourceCompiles` or -:module:`CheckFortranSourceCompiles`). See documentation of these -modules for a listing of variables that can otherwise modify the build. - -The underlying implementation rely on :prop_tgt:`LINK_OPTIONS` property to -check the specified flag. The ``LINKER:`` prefix, as described in +and calls the :command:`check_source_compiles` command from the +:module:`CheckSourceCompiles` module. See that module's documentation +for a listing of variables that can otherwise modify the build. + +The underlying implementation relies on the :prop_tgt:`LINK_OPTIONS` property +to check the specified flag. The ``LINKER:`` prefix, as described in the :command:`target_link_options` command, can be used as well. A positive result from this check indicates only that the compiler did not |