diff options
Diffstat (limited to 'Help')
255 files changed, 5554 insertions, 680 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index 5b63e1c..6683edb 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -13,6 +13,7 @@ The general signature is: name | |NAMES| [HINTS [path | ENV var]... ] [PATHS [path | ENV var]... ] + [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)] [PATH_SUFFIXES suffix1 [suffix2 ...]] [DOC "cache documentation string"] [NO_CACHE] @@ -23,6 +24,7 @@ The general signature is: [NO_CMAKE_ENVIRONMENT_PATH] [NO_SYSTEM_ENVIRONMENT_PATH] [NO_CMAKE_SYSTEM_PATH] + [NO_CMAKE_INSTALL_PREFIX] [CMAKE_FIND_ROOT_PATH_BOTH | ONLY_CMAKE_FIND_ROOT_PATH | NO_CMAKE_FIND_ROOT_PATH] @@ -50,6 +52,16 @@ Options include: The ``ENV var`` sub-option reads paths from a system environment variable. + .. versionchanged:: 3.24 + On ``Windows`` platform, it is possible to include registry queries as part + of the directories, using a :ref:`dedicated syntax <Find Using Windows Registry>`. + Such specifications will be ignored on all other platforms. + +``REGISTRY_VIEW`` + .. versionadded:: 3.24 + + .. include:: FIND_XXX_REGISTRY_VIEW.txt + ``PATH_SUFFIXES`` Specify additional subdirectories to check below each directory location otherwise considered. @@ -154,9 +166,11 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: * |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| 6. Search cmake variables defined in the Platform files - for the current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` - is passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` - to ``FALSE``. + for the current system. The searching of ``CMAKE_INSTALL_PREFIX` can be + skipped if ``NO_CMAKE_INSTALL_PREFIX`` is passed or by setting the + :variable:`CMAKE_FIND_USE_INSTALL_PREFIX` to ``FALSE. All these locations + can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is passed or by setting the + :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` to ``FALSE``. * |CMAKE_SYSTEM_PREFIX_PATH_XXX| * |CMAKE_SYSTEM_XXX_PATH| @@ -170,6 +184,11 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: or in the short-hand version of the command. These are typically hard-coded guesses. +The :variable:`CMAKE_IGNORE_PATH`, :variable:`CMAKE_IGNORE_PREFIX_PATH`, +:variable:`CMAKE_SYSTEM_IGNORE_PATH` and +:variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` variables can also cause some +of the above locations to be ignored. + .. versionadded:: 3.16 Added ``CMAKE_FIND_USE_<CATEGORY>_PATH`` variables to globally disable various search locations. diff --git a/Help/command/FIND_XXX_REGISTRY_VIEW.txt b/Help/command/FIND_XXX_REGISTRY_VIEW.txt new file mode 100644 index 0000000..39b156f --- /dev/null +++ b/Help/command/FIND_XXX_REGISTRY_VIEW.txt @@ -0,0 +1,41 @@ +Specify which registry views must be queried. This option is only meaningful +on ``Windows`` platform and will be ignored on other ones. When not +specified, |FIND_XXX_REGISTRY_VIEW_DEFAULT| view is used when :policy:`CMP0134` +policy is ``NEW``. Refer to :policy:`CMP0134` policy for default view when +policy is ``OLD`` or undefined. + +``64`` + Query the 64bit registry. On ``32bit Windows``, returns always the string + ``/REGISTRY-NOTFOUND``. + +``32`` + Query the 32bit registry. + +``64_32`` + Query both views (``64`` and ``32``) and generate a path for each. + +``32_64`` + Query both views (``32`` and ``64``) and generate a path for each. + +``HOST`` + Query the registry matching the architecture of the host: ``64`` on ``64bit + Windows`` and ``32`` on ``32bit Windows``. + +``TARGET`` + Query the registry matching the architecture specified by + :variable:`CMAKE_SIZEOF_VOID_P` variable. If not defined, fallback to + ``HOST`` view. + +``BOTH`` + Query both views (``32`` and ``64``). The order depends of the following + rules: If :variable:`CMAKE_SIZEOF_VOID_P` variable is defined. Use the + following view depending of the content of this variable: + + * ``8``: ``64_32`` + * ``4``: ``32_64`` + + If :variable:`CMAKE_SIZEOF_VOID_P` variable is not defined, rely on + architecture of the host: + + * ``64bit``: ``64_32`` + * ``32bit``: ``32`` diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index b45a079..4fe9326 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -271,9 +271,47 @@ The options are: ``DEPFILE`` .. versionadded:: 3.7 - Specify a ``.d`` depfile which holds dependencies for the custom command. - It is usually emitted by the custom command itself. This keyword may only - be used if the generator supports it, as detailed below. + Specify a depfile which holds dependencies for the custom command. It is + usually emitted by the custom command itself. This keyword may only be used + if the generator supports it, as detailed below. + + The expected format, compatible with what is generated by ``gcc`` with the + option ``-M``, is independent of the generator or platform. + + The formal syntax, as specified using + `BNF <https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form>`_ notation with + the regular extensions, is the following: + + .. raw:: latex + + \begin{small} + + .. productionlist:: depfile + depfile: `rule`* + rule: `targets` (':' (`separator` `dependencies`?)?)? `eol` + targets: `target` (`separator` `target`)* `separator`* + target: `pathname` + dependencies: `dependency` (`separator` `dependency`)* `separator`* + dependency: `pathname` + separator: (`space` | `line_continue`)+ + line_continue: '\' `eol` + space: ' ' | '\t' + pathname: `character`+ + character: `std_character` | `dollar` | `hash` | `whitespace` + std_character: <any character except '$', '#' or ' '> + dollar: '$$' + hash: '\#' + whitespace: '\ ' + eol: '\r'? '\n' + + .. raw:: latex + + \end{small} + + .. note:: + + As part of ``pathname``, any slash and backslash is interpreted as + a directory separator. .. versionadded:: 3.7 The :generator:`Ninja` generator supports ``DEPFILE`` since the keyword diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index 1235155..7dc4365 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -151,6 +151,7 @@ itself and is not included as a target in the generated buildsystem. ``PUBLIC`` keywords. If an interface library has source files (i.e. the :prop_tgt:`SOURCES` + target property is set), or header sets (i.e. the :prop_tgt:`HEADER_SETS` target property is set), it will appear in the generated buildsystem as a build target much like a target defined by the :command:`add_custom_target` command. It does not compile any sources, diff --git a/Help/command/add_test.rst b/Help/command/add_test.rst index 95cd037..53555a4 100644 --- a/Help/command/add_test.rst +++ b/Help/command/add_test.rst @@ -20,6 +20,9 @@ if necessary. See policy :policy:`CMP0110`. The options are: automatically be replaced by the location of the executable created at build time. + The command may be specified using + :manual:`generator expressions <cmake-generator-expressions(7)>`. + ``CONFIGURATIONS`` Restrict execution of the test only to the named configurations. @@ -30,6 +33,9 @@ if necessary. See policy :policy:`CMP0110`. The options are: directory set to the build directory corresponding to the current source directory. + The working directory may be specified using + :manual:`generator expressions <cmake-generator-expressions(7)>`. + ``COMMAND_EXPAND_LISTS`` .. versionadded:: 3.16 @@ -48,9 +54,10 @@ unless the :prop_test:`PASS_REGULAR_EXPRESSION`, .. versionadded:: 3.16 Added :prop_test:`SKIP_REGULAR_EXPRESSION` property. -The ``COMMAND`` and ``WORKING_DIRECTORY`` options may use "generator -expressions" with the syntax ``$<...>``. See the -:manual:`cmake-generator-expressions(7)` manual for available expressions. +Tests added with the ``add_test(NAME)`` signature support using +:manual:`generator expressions <cmake-generator-expressions(7)>` +in test properties set by :command:`set_property(TEST)` or +:command:`set_tests_properties`. Example usage: @@ -73,10 +80,15 @@ file produced by target ``myexe``. --------------------------------------------------------------------- +This command also supports a simpler, but less flexible, signature: + .. code-block:: cmake add_test(<name> <command> [<arg>...]) -Add a test called ``<name>`` with the given command-line. Unlike -the above ``NAME`` signature no transformation is performed on the -command-line to support target names or generator expressions. +Add a test called ``<name>`` with the given command-line. + +Unlike the above ``NAME`` signature, target names are not supported +in the command-line. Furthermore, tests added with this signature do not +support :manual:`generator expressions <cmake-generator-expressions(7)>` +in the command-line or test properties. diff --git a/Help/command/cmake_host_system_information.rst b/Help/command/cmake_host_system_information.rst index 998e146..c84c5b5 100644 --- a/Help/command/cmake_host_system_information.rst +++ b/Help/command/cmake_host_system_information.rst @@ -1,9 +1,23 @@ cmake_host_system_information ----------------------------- -Query host system specific information. +Query various host system information. -.. code-block:: cmake +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + `Query host system specific information`_ + cmake_host_system_information(RESULT <variable> QUERY <key> ...) + + `Query Windows registry`_ + cmake_host_system_information(RESULT <variable> QUERY WINDOWS_REGISTRY <key> ...) + +Query host system specific information +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: cmake_host_system_information(RESULT <variable> QUERY <key> ...) @@ -180,7 +194,7 @@ distribution-specific files`_ to collect OS identification data and map it into `man 5 os-release`_ variables. Fallback Interface Variables -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""""""" .. variable:: CMAKE_GET_OS_RELEASE_FALLBACK_SCRIPTS @@ -246,3 +260,137 @@ Example: .. _man 5 os-release: https://www.freedesktop.org/software/systemd/man/os-release.html .. _various distribution-specific files: http://linuxmafia.com/faq/Admin/release-files.html + +.. _Query Windows registry: + +Query Windows registry +^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.24 + +:: + + cmake_host_system_information(RESULT <variable> + QUERY WINDOWS_REGISTRY <key> [VALUE_NAMES|SUBKEYS|VALUE <name>] + [VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)] + [SEPARATOR <separator>] + [ERROR_VARIABLE <result>]) + +Performs query operations on local computer registry subkey. Returns a list of +subkeys or value names that are located under the specified subkey in the +registry or the data of the specified value name. The result of the queried +entity is stored in ``<variable>``. + +.. note:: + + Querying registry for any other platforms than ``Windows``, including + ``CYGWIN``, will always returns an empty string and sets an error message in + the variable specified with sub-option ``ERROR_VARIABLE``. + +``<key>`` specify the full path of a subkey on the local computer. The +``<key>`` must include a valid root key. Valid root keys for the local computer +are: + +* ``HKLM`` or ``HKEY_LOCAL_MACHINE`` +* ``HKCU`` or ``HKEY_CURRENT_USER`` +* ``HKCR`` or ``HKEY_CLASSES_ROOT`` +* ``HKU`` or ``HKEY_USERS`` +* ``HKCC`` or ``HKEY_CURRENT_CONFIG`` + +And, optionally, the path to a subkey under the specified root key. The path +separator can be the slash or the backslash. ``<key>`` is not case sensitive. +For example: + +.. code-block:: cmake + + cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKLM") + cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware") + cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKCU\\SOFTWARE\\Kitware") + +``VALUE_NAMES`` + Request the list of value names defined under ``<key>``. If a default value + is defined, it will be identified with the special name ``(default)``. + +``SUBKEYS`` + Request the list of subkeys defined under ``<key>``. + +``VALUE <name>`` + Request the data stored in value named ``<name>``. If ``VALUE`` is not + specified or argument is the special name ``(default)``, the content of the + default value, if any, will be returned. + + .. code-block:: cmake + + # query default value for HKLM/SOFTWARE/Kitware key + cmake_host_system_information(RESULT result + QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware") + + # query default value for HKLM/SOFTWARE/Kitware key using special value name + cmake_host_system_information(RESULT result + QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware" + VALUE "(default)") + + Supported types are: + + * ``REG_SZ``. + * ``REG_EXPAND_SZ``. The returned data is expanded. + * ``REG_MULTI_SZ``. The returned is expressed as a CMake list. See also + ``SEPARATOR`` sub-option. + * ``REG_DWORD``. + * ``REG_QWORD``. + + For all other types, an empty string is returned. + +``VIEW`` + Specify which registry views must be queried. When not specified, ``BOTH`` + view is used. + + ``64`` + Query the 64bit registry. On ``32bit Windows``, returns always an empty + string. + + ``32`` + Query the 32bit registry. + + ``64_32`` + For ``VALUE`` sub-option or default value, query the registry using view + ``64``, and if the request failed, query the registry using view ``32``. + For ``VALUE_NAMES`` and ``SUBKEYS`` sub-options, query both views (``64`` + and ``32``) and merge the results (sorted and duplicates removed). + + ``32_64`` + For ``VALUE`` sub-option or default value, query the registry using view + ``32``, and if the request failed, query the registry using view ``64``. + For ``VALUE_NAMES`` and ``SUBKEYS`` sub-options, query both views (``32`` + and ``64``) and merge the results (sorted and duplicates removed). + + ``HOST`` + Query the registry matching the architecture of the host: ``64`` on ``64bit + Windows`` and ``32`` on ``32bit Windows``. + + ``TARGET`` + Query the registry matching the architecture specified by + :variable:`CMAKE_SIZEOF_VOID_P` variable. If not defined, fallback to + ``HOST`` view. + + ``BOTH`` + Query both views (``32`` and ``64``). The order depends of the following + rules: If :variable:`CMAKE_SIZEOF_VOID_P` variable is defined. Use the + following view depending of the content of this variable: + + * ``8``: ``64_32`` + * ``4``: ``32_64`` + + If :variable:`CMAKE_SIZEOF_VOID_P` variable is not defined, rely on + architecture of the host: + + * ``64bit``: ``64_32`` + * ``32bit``: ``32`` + +``SEPARATOR`` + Specify the separator character for ``REG_MULTI_SZ`` type. When not + specified, the character ``\0`` is used. + +``ERROR_VARIABLE <result>`` + Returns any error raised during query operation. In case of success, the + variable holds an empty string. diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst index 6a9a6a0..11ebdbd 100644 --- a/Help/command/ctest_test.rst +++ b/Help/command/ctest_test.rst @@ -172,8 +172,9 @@ The options are: affected. Summary info detailing the percentage of passing tests is also unaffected by the ``QUIET`` option. -See also the :variable:`CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE` -and :variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE` variables. +See also the :variable:`CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE`, +:variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE` and +:variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` variables. .. _`Additional Test Measurements`: diff --git a/Help/command/define_property.rst b/Help/command/define_property.rst index 8f7439b..76b060b 100644 --- a/Help/command/define_property.rst +++ b/Help/command/define_property.rst @@ -8,15 +8,18 @@ Define and document custom properties. define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE | TEST | VARIABLE | CACHED_VARIABLE> PROPERTY <name> [INHERITED] - BRIEF_DOCS <brief-doc> [docs...] - FULL_DOCS <full-doc> [docs...]) + [BRIEF_DOCS <brief-doc> [docs...]] + [FULL_DOCS <full-doc> [docs...]] + [INITIALIZE_FROM_VARIABLE <variable>]) Defines one property in a scope for use with the :command:`set_property` and -:command:`get_property` commands. This is primarily useful to associate -documentation with property names that may be retrieved with the -:command:`get_property` command. The first argument determines the kind of -scope in which the property should be used. It must be one of the -following: +:command:`get_property` commands. It is mainly useful for defining the way +a property is initialized or inherited. Historically, the command also +associated documentation with a property, but that is no longer considered a +primary use case. + +The first argument determines the kind of scope in which the property should +be used. It must be one of the following: :: @@ -55,5 +58,18 @@ out the contents to append to. The ``BRIEF_DOCS`` and ``FULL_DOCS`` options are followed by strings to be associated with the property as its brief and full documentation. -Corresponding options to the :command:`get_property` command will retrieve -the documentation. +CMake does not use this documentation other than making it available to the +project via corresponding options to the :command:`get_property` command. + +.. versionchanged:: 3.23 + + The ``BRIEF_DOCS`` and ``FULL_DOCS`` options are optional. + +.. versionadded:: 3.23 + + The ``INITIALIZE_FROM_VARIABLE`` option specifies a variable from which the + property should be initialized. It can only be used with target properties. + The ``<variable>`` name must end with the property name and must not begin + with ``CMAKE_`` or ``_CMAKE_``. The property name must contain at least one + underscore. It is recommended that the property name have a prefix specific + to the project. diff --git a/Help/command/export.rst b/Help/command/export.rst index e8a1fa7..dc69645 100644 --- a/Help/command/export.rst +++ b/Help/command/export.rst @@ -1,44 +1,62 @@ export ------ -Export targets from the build tree for use by outside projects. +Export targets or packages for outside projects to use them directly +from the current project's build tree, without installation. + +See the :command:`install(EXPORT)` command to export targets from an +install tree. + +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + export(`TARGETS`_ <target>... [...]) + export(`EXPORT`_ <export-name> [...]) + export(`PACKAGE`_ <PackageName>) + +Exporting Targets +^^^^^^^^^^^^^^^^^ + +.. _`export(TARGETS)`: +.. _TARGETS: .. code-block:: cmake - export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>]) + export(TARGETS <target>... [NAMESPACE <namespace>] + [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES]) Creates a file ``<filename>`` that may be included by outside projects to -import targets from the current project's build tree. This is useful -during cross-compiling to build utility executables that can run on -the host platform in one project and then import them into another -project being compiled for the target platform. If the ``NAMESPACE`` -option is given the ``<namespace>`` string will be prepended to all target -names written to the file. - -Target installations are associated with the export ``<export-name>`` -using the ``EXPORT`` option of the :command:`install(TARGETS)` command. +import targets named by ``<target>...`` from the current project's build tree. +This is useful during cross-compiling to build utility executables that can +run on the host platform in one project and then import them into another +project being compiled for the target platform. The file created by this command is specific to the build tree and should never be installed. See the :command:`install(EXPORT)` command to -export targets from an installation tree. +export targets from an install tree. -The properties set on the generated IMPORTED targets will have the -same values as the final values of the input TARGETS. +The options are: -.. code-block:: cmake +``NAMESPACE <namespace>`` + Prepend the ``<namespace>`` string to all target names written to the file. - export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>] - [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES]) +``APPEND`` + Append to the file instead of overwriting it. This can be used to + incrementally export multiple targets to the same file. + +``EXPORT_LINK_INTERFACE_LIBRARIES`` + Include the contents of the properties named with the pattern + ``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?`` + in the export, even when policy :policy:`CMP0022` is NEW. This is useful + to support consumers using CMake versions older than 2.8.12. -This signature is similar to the ``EXPORT`` signature, but targets are listed -explicitly rather than specified as an export-name. If the APPEND option is -given the generated code will be appended to the file instead of overwriting it. -The EXPORT_LINK_INTERFACE_LIBRARIES keyword, if present, causes the -contents of the properties matching -``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?`` to be exported, when -policy CMP0022 is NEW. If a library target is included in the export -but a target to which it links is not included the behavior is -unspecified. +This signature requires all targets to be listed explicitly. If a library +target is included in the export, but a target to which it links is not +included, the behavior is unspecified. See the `export(EXPORT)`_ signature +to automatically export the same targets from the build tree as +:command:`install(EXPORT)` would from an install tree. .. note:: @@ -49,6 +67,50 @@ unspecified. transitive usage requirements of other targets that link to the object libraries in their implementation. +Exporting Targets to Android.mk +""""""""""""""""""""""""""""""" + +.. code-block:: cmake + + export(TARGETS <target>... ANDROID_MK <filename>) + +.. versionadded:: 3.7 + +This signature exports cmake built targets to the android ndk build system +by creating an ``Android.mk`` file that references the prebuilt targets. The +Android NDK supports the use of prebuilt libraries, both static and shared. +This allows cmake to build the libraries of a project and make them available +to an ndk build system complete with transitive dependencies, include flags +and defines required to use the libraries. The signature takes a list of +targets and puts them in the ``Android.mk`` file specified by the +``<filename>`` given. This signature can only be used if policy +:policy:`CMP0022` is NEW for all targets given. A error will be issued if +that policy is set to OLD for one of the targets. + +Exporting Targets matching install(EXPORT) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. _`export(EXPORT)`: +.. _EXPORT: + +.. code-block:: cmake + + export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>]) + +Creates a file ``<filename>`` that may be included by outside projects to +import targets from the current project's build tree. This is the same +as the `export(TARGETS)`_ signature, except that the targets are not +explicitly listed. Instead, it exports the targets associated with +the installation export ``<export-name>``. Target installations may be +associated with the export ``<export-name>`` using the ``EXPORT`` option +of the :command:`install(TARGETS)` command. + +Exporting Packages +^^^^^^^^^^^^^^^^^^ + +.. _`export(PACKAGE)`: +.. _PACKAGE: + .. code-block:: cmake export(PACKAGE <PackageName>) @@ -74,20 +136,3 @@ registry. outside the source and build trees. Set the :variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable to add build directories to the CMake user package registry. - -.. code-block:: cmake - - export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>]) - -.. versionadded:: 3.7 - -This signature exports cmake built targets to the android ndk build system -by creating an Android.mk file that references the prebuilt targets. The -Android NDK supports the use of prebuilt libraries, both static and shared. -This allows cmake to build the libraries of a project and make them available -to an ndk build system complete with transitive dependencies, include flags -and defines required to use the libraries. The signature takes a list of -targets and puts them in the Android.mk file specified by the ``<filename>`` -given. This signature can only be used if policy CMP0022 is NEW for all -targets given. A error will be issued if that policy is set to OLD for one -of the targets. diff --git a/Help/command/file.rst b/Help/command/file.rst index 799b6ff..3374d2d 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -1128,6 +1128,18 @@ Additional options to ``DOWNLOAD`` are: Historical short-hand for ``EXPECTED_HASH MD5=<value>``. It is an error to specify this if ``DOWNLOAD`` is not given a ``<file>``. +``RANGE_START <value>`` + .. versionadded:: 3.24 + + Offset of the start of the range in file in bytes. Could be omitted to + download up to the specified ``RANGE_END``. + +``RANGE_END <value>`` + .. versionadded:: 3.24 + + Offset of the end of the range in file in bytes. Could be omitted to + download everything from the specified ``RANGE_START`` to the end of file. + Locking ^^^^^^^ @@ -1215,7 +1227,8 @@ the ``MTIME`` option. [DESTINATION <dir>] [PATTERNS <patterns>...] [LIST_ONLY] - [VERBOSE]) + [VERBOSE] + [TOUCH]) .. versionadded:: 3.18 @@ -1233,4 +1246,8 @@ extracted. ``LIST_ONLY`` will list the files in the archive rather than extract them. +.. versionadded:: 3.24 + The ``TOUCH`` option gives extracted files a current local + timestamp instead of extracting file timestamps from the archive. + With ``VERBOSE``, the command will produce verbose output. diff --git a/Help/command/find_file.rst b/Help/command/find_file.rst index 39dfb85..c5c4014 100644 --- a/Help/command/find_file.rst +++ b/Help/command/find_file.rst @@ -8,6 +8,8 @@ find_file .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include`` .. |entry_XXX_SUBDIR| replace:: ``<entry>/include`` +.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET`` + .. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace:: ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst index ab957ce..c237e7f 100644 --- a/Help/command/find_library.rst +++ b/Help/command/find_library.rst @@ -8,6 +8,8 @@ find_library .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/lib`` .. |entry_XXX_SUBDIR| replace:: ``<entry>/lib`` +.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET`` + .. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace:: ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 1a79a8a..a7d7d00 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -1,6 +1,12 @@ find_package ------------ +.. |FIND_XXX| replace:: find_package +.. |FIND_ARGS_XXX| replace:: <PackageName> +.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET`` +.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: + :variable:`CMAKE_FIND_ROOT_PATH_MODE_PACKAGE` + .. only:: html .. contents:: @@ -11,7 +17,7 @@ and load its package-specific details. Search Modes ^^^^^^^^^^^^ -The command has two very distinct ways of conducting the search: +The command has a few modes by which it searches for packages: **Module mode** In this mode, CMake searches for a file called ``Find<PackageName>.cmake``, @@ -54,7 +60,17 @@ The command has two very distinct ways of conducting the search: Config mode is supported by both the :ref:`basic <Basic Signature>` and :ref:`full <Full Signature>` command signatures. -The command arguments determine which of the above modes is used. When the +**FetchContent redirection mode** + .. versionadded:: 3.24 + A call to ``find_package()`` can be redirected internally to a package + provided by the :module:`FetchContent` module. To the caller, the behavior + will appear similar to Config mode, except that the search logic is + by-passed and the component information is not used. See + :command:`FetchContent_Declare` and :command:`FetchContent_MakeAvailable` + for further details. + +When not redirected to a package provided by :module:`FetchContent`, the +command arguments determine whether Module or Config mode is used. When the `basic signature`_ is used, the command searches in Module mode first. If the package is not found, the search falls back to Config mode. A user may set the :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` variable @@ -64,7 +80,7 @@ forced to use only Module mode with a ``MODULE`` keyword. If the `full signature`_ is used, the command only searches in Config mode. Where possible, user code should generally look for packages using the -`basic signature`_, since that allows the package to be found with either mode. +`basic signature`_, since that allows the package to be found with any mode. Project maintainers wishing to provide a config package should understand the bigger picture, as explained in :ref:`Full Signature` and all subsequent sections on this page. @@ -74,12 +90,14 @@ sections on this page. Basic Signature ^^^^^^^^^^^^^^^ -.. code-block:: cmake +.. parsed-literal:: find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE] [REQUIRED] [[COMPONENTS] [components...]] [OPTIONAL_COMPONENTS components...] - [NO_POLICY_SCOPE]) + [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)] + [NO_POLICY_SCOPE] + [GLOBAL]) The basic signature is supported by both Module and Config modes. The ``MODULE`` keyword implies that only Module mode can be used to find @@ -115,6 +133,17 @@ define what occurs in such cases. Common arrangements include assuming it should find all components, no components or some well-defined subset of the available components. +.. versionadded:: 3.24 + The ``REGISTRY_VIEW`` keyword enables to specify which registry views must be + queried. This keyword is only meaningful on ``Windows`` platform and will be + ignored on all other ones. Formally, it is up to the target package how to + interpret the registry view information given to it. + +Specifying the ``GLOBAL`` keyword will promote all imported targets to +a global scope in the importing project. Alternatively this functionality +can be enabled by setting the variable +:variable:`CMAKE_FIND_PACKAGE_TARGETS_GLOBAL` + .. _FIND_PACKAGE_VERSION_FORMAT: The ``[version]`` argument requests a version with which the package found @@ -149,17 +178,19 @@ of the ``NO_POLICY_SCOPE`` option. Full Signature ^^^^^^^^^^^^^^ -.. code-block:: cmake +.. parsed-literal:: find_package(<PackageName> [version] [EXACT] [QUIET] [REQUIRED] [[COMPONENTS] [components...]] [OPTIONAL_COMPONENTS components...] [CONFIG|NO_MODULE] [NO_POLICY_SCOPE] + [GLOBAL] [NAMES name1 [name2 ...]] [CONFIGS config1 [config2 ...]] [HINTS path1 [path2 ... ]] [PATHS path1 [path2 ... ]] + [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)] [PATH_SUFFIXES suffix1 [suffix2 ...]] [NO_DEFAULT_PATH] [NO_PACKAGE_ROOT_PATH] @@ -169,6 +200,7 @@ Full Signature [NO_CMAKE_PACKAGE_REGISTRY] [NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing. [NO_CMAKE_SYSTEM_PATH] + [NO_CMAKE_INSTALL_PREFIX] [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY] [CMAKE_FIND_ROOT_PATH_BOTH | ONLY_CMAKE_FIND_ROOT_PATH | @@ -181,9 +213,12 @@ proceeds at once with Config mode search. Config mode search attempts to locate a configuration file provided by the package to be found. A cache entry called ``<PackageName>_DIR`` is created to -hold the directory containing the file. By default the command -searches for a package with the name ``<PackageName>``. If the ``NAMES`` option -is given the names following it are used instead of ``<PackageName>``. +hold the directory containing the file. By default, the command searches for +a package with the name ``<PackageName>``. If the ``NAMES`` option is given, +the names following it are used instead of ``<PackageName>``. The names are +also considered when determining whether to redirect the call to a package +provided by :module:`FetchContent`. + The command searches for a file called ``<PackageName>Config.cmake`` or ``<lowercasePackageName>-config.cmake`` for each name specified. A replacement set of possible configuration file names may be given @@ -220,6 +255,14 @@ Config Mode Search Procedure whether the :ref:`full <full signature>` or :ref:`basic <basic signature>` signature was given. +.. versionadded:: 3.24 + All calls to ``find_package()`` (even in Module mode) first look for a config + package file in the :variable:`CMAKE_FIND_PACKAGE_REDIRECTS_DIR` directory. + The :module:`FetchContent` module, or even the project itself, may write files + to that location to redirect ``find_package()`` calls to content already + provided by the project. If no config package file is found in that location, + the search proceeds with the logic described below. + CMake constructs a set of possible installation prefixes for the package. Under each prefix several directories are searched for a configuration file. The tables below show the directories searched. @@ -264,6 +307,18 @@ that order). if the :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` property is set to ``TRUE``. * The ``lib`` path is always searched. +.. versionchanged:: 3.24 + On ``Windows`` platform, it is possible to include registry queries as part + of the directories specified through ``HINTS`` and ``PATHS`` keywords, using + a :ref:`dedicated syntax <Find Using Windows Registry>`. Such specifications + will be ignored on all other platforms. + +.. versionadded:: 3.24 + ``REGISTRY_VIEW`` can be specified to manage ``Windows`` registry queries + specified as part of ``PATHS`` and ``HINTS``. + +.. include:: FIND_XXX_REGISTRY_VIEW.txt + If ``PATH_SUFFIXES`` is specified, the suffixes are appended to each (``W``) or (``U``) directory entry one-by-one. @@ -339,9 +394,11 @@ enabled. package registry. 7. Search cmake variables defined in the Platform files for the - current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is - passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` - to ``FALSE``: + current system. The searching of ``CMAKE_INSTALL_PREFIX` can be skipped + if ``NO_CMAKE_INSTALL_PREFIX`` is passed or by setting the + :variable:`CMAKE_FIND_USE_INSTALL_PREFIX` to ``FALSE. All these locations + can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is passed or by setting the + :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` to ``FALSE``: * :variable:`CMAKE_SYSTEM_PREFIX_PATH` * :variable:`CMAKE_SYSTEM_FRAMEWORK_PATH` @@ -363,15 +420,15 @@ enabled. 9. Search paths specified by the ``PATHS`` option. These are typically hard-coded guesses. +The :variable:`CMAKE_IGNORE_PATH`, :variable:`CMAKE_IGNORE_PREFIX_PATH`, +:variable:`CMAKE_SYSTEM_IGNORE_PATH` and +:variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` variables can also cause some +of the above locations to be ignored. + .. versionadded:: 3.16 Added the ``CMAKE_FIND_USE_<CATEGORY>`` variables to globally disable various search locations. -.. |FIND_XXX| replace:: find_package -.. |FIND_ARGS_XXX| replace:: <PackageName> -.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: - :variable:`CMAKE_FIND_ROOT_PATH_MODE_PACKAGE` - .. include:: FIND_XXX_ROOT.txt .. include:: FIND_XXX_ORDER.txt @@ -383,7 +440,8 @@ to resolve symbolic links and store the real path to the file. Every non-REQUIRED ``find_package`` call can be disabled or made REQUIRED: * Setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable - to ``TRUE`` disables the package. + to ``TRUE`` disables the package. This also disables redirection to a + package provided by :module:`FetchContent`. * Setting the :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` variable to ``TRUE`` makes the package REQUIRED. @@ -406,8 +464,8 @@ version (see :ref:`format specification <FIND_PACKAGE_VERSION_FORMAT>`). If the ``EXACT`` option is given, only a version of the package claiming an exact match of the requested version may be found. CMake does not establish any convention for the meaning of version numbers. Package version -numbers are checked by "version" files provided by the packages -themselves. For a candidate package configuration file +numbers are checked by "version" files provided by the packages themselves +or by :module:`FetchContent`. For a candidate package configuration file ``<config-file>.cmake`` the corresponding version file is located next to it and named either ``<config-file>-version.cmake`` or ``<config-file>Version.cmake``. If no such version file is available @@ -542,6 +600,8 @@ restores their original state before returning): True if ``REQUIRED`` option was given ``<PackageName>_FIND_QUIETLY`` True if ``QUIET`` option was given +``<PackageName>_FIND_REGISTRY_VIEW`` + The requested view if ``REGISTRY_VIEW`` option was given ``<PackageName>_FIND_VERSION`` Full requested version string ``<PackageName>_FIND_VERSION_MAJOR`` diff --git a/Help/command/find_path.rst b/Help/command/find_path.rst index ec66771..1d7648d 100644 --- a/Help/command/find_path.rst +++ b/Help/command/find_path.rst @@ -8,6 +8,8 @@ find_path .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include`` .. |entry_XXX_SUBDIR| replace:: ``<entry>/include`` +.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET`` + .. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace:: ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| diff --git a/Help/command/find_program.rst b/Help/command/find_program.rst index e2ff693..f4149be 100644 --- a/Help/command/find_program.rst +++ b/Help/command/find_program.rst @@ -8,6 +8,8 @@ find_program .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/[s]bin`` .. |entry_XXX_SUBDIR| replace:: ``<entry>/[s]bin`` +.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``BOTH`` + .. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace:: |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| .. |CMAKE_PREFIX_PATH_XXX| replace:: diff --git a/Help/command/get_filename_component.rst b/Help/command/get_filename_component.rst index 4bdd388..4bfe087 100644 --- a/Help/command/get_filename_component.rst +++ b/Help/command/get_filename_component.rst @@ -4,10 +4,16 @@ get_filename_component Get a specific component of a full filename. .. versionchanged:: 3.20 - This command been superseded by :command:`cmake_path` command, except - ``REALPATH`` now offered by :ref:`file(REAL_PATH) <REAL_PATH>` command and + This command has been superseded by :command:`cmake_path` command, except + ``REALPATH`` now offered by :ref:`file(REAL_PATH)<REAL_PATH>` command and ``PROGRAM`` now available in :command:`separate_arguments(PROGRAM)` command. +.. versionchanged:: 3.24 + The undocumented feature offering the capability to query the ``Windows`` + registry is superseded by + :ref:`cmake_host_system_information(QUERY WINDOWS_REGISTRY)<Query Windows registry>` + command. + .. code-block:: cmake get_filename_component(<var> <FileName> <mode> [CACHE]) diff --git a/Help/command/if.rst b/Help/command/if.rst index 5dba13e..64f1c35 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -38,21 +38,29 @@ The following syntax applies to the ``condition`` argument of the ``if``, ``elseif`` and :command:`while` clauses. Compound conditions are evaluated in the following order of precedence: -Innermost parentheses are evaluated first. Next come unary tests such -as `EXISTS`_, `COMMAND`_, and `DEFINED`_. Then binary tests such as -`EQUAL`_, `LESS`_, `LESS_EQUAL`_, `GREATER`_, `GREATER_EQUAL`_, -`STREQUAL`_, `STRLESS`_, `STRLESS_EQUAL`_, `STRGREATER`_, -`STRGREATER_EQUAL`_, `VERSION_EQUAL`_, `VERSION_LESS`_, -`VERSION_LESS_EQUAL`_, `VERSION_GREATER`_, `VERSION_GREATER_EQUAL`_, -and `MATCHES`_. Then the boolean operators in the order `NOT`_, `AND`_, -and finally `OR`_. + +1. Parentheses. + +2. Unary tests such as `EXISTS`_, `COMMAND`_, and `DEFINED`_. + +3. Binary tests such as `EQUAL`_, `LESS`_, `LESS_EQUAL`_, `GREATER`_, + `GREATER_EQUAL`_, `STREQUAL`_, `STRLESS`_, `STRLESS_EQUAL`_, + `STRGREATER`_, `STRGREATER_EQUAL`_, `VERSION_EQUAL`_, `VERSION_LESS`_, + `VERSION_LESS_EQUAL`_, `VERSION_GREATER`_, `VERSION_GREATER_EQUAL`_, + and `MATCHES`_. + +4. Unary logical operator `NOT`_. + +5. Binary logical operators `AND`_ and `OR`_, from left to right, + without any short-circuit. Basic Expressions """"""""""""""""" ``if(<constant>)`` True if the constant is ``1``, ``ON``, ``YES``, ``TRUE``, ``Y``, - or a non-zero number. False if the constant is ``0``, ``OFF``, + or a non-zero number (including floating point numbers). + False if the constant is ``0``, ``OFF``, ``NO``, ``FALSE``, ``N``, ``IGNORE``, ``NOTFOUND``, the empty string, or ends in the suffix ``-NOTFOUND``. Named boolean constants are case-insensitive. If the argument is not one of these specific @@ -63,8 +71,9 @@ Basic Expressions True if given a variable that is defined to a value that is not a false constant. False otherwise, including if the variable is undefined. Note that macro arguments are not variables. - Environment variables also cannot be tested this way, e.g. - ``if(ENV{some_var})`` will always evaluate to false. + :ref:`Environment Variables <CMake Language Environment Variables>` also + cannot be tested this way, e.g. ``if(ENV{some_var})`` will always evaluate + to false. ``if(<string>)`` A quoted string always evaluates to false unless: @@ -126,7 +135,16 @@ Existence Checks ``if(DEFINED <name>|CACHE{<name>}|ENV{<name>})`` True if a variable, cache variable or environment variable with given ``<name>`` is defined. The value of the variable - does not matter. Note that macro arguments are not variables. + does not matter. Note the following caveats: + + * Macro arguments are not variables. + * It is not possible to test directly whether a `<name>` is a non-cache + variable. The expression ``if(DEFINED someName)`` will evaluate to true + if either a cache or non-cache variable ``someName`` exists. In + comparison, the expression ``if(DEFINED CACHE{someName})`` will only + evaluate to true if a cache variable ``someName`` exists. Both expressions + need to be tested if you need to know whether a non-cache variable exists: + ``if(DEFINED someName AND NOT DEFINED CACHE{someName})``. .. versionadded:: 3.14 Added support for ``CACHE{<name>}`` variables. diff --git a/Help/command/install.rst b/Help/command/install.rst index 1236f1d..973aa31 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -85,7 +85,7 @@ signatures that specify them. The common options are: ``COMPONENT`` Specify an installation component name with which the install rule - is associated, such as "runtime" or "development". During + is associated, such as ``Runtime`` or ``Development``. During component-specific installation only install rules associated with the given component name will be executed. During a full installation all components are installed unless marked with ``EXCLUDE_FROM_ALL``. @@ -132,7 +132,7 @@ Installing Targets 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] + PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE|FILE_SET <set-name>] [DESTINATION <dir>] [PERMISSIONS permissions...] [CONFIGURATIONS [Debug|Release|...]] @@ -204,6 +204,17 @@ that may be installed: Similar to ``PUBLIC_HEADER`` and ``PRIVATE_HEADER``, but for ``RESOURCE`` files. See :prop_tgt:`RESOURCE` for details. +``FILE_SET <set>`` + .. versionadded:: 3.23 + + File sets are defined by the :command:`target_sources(FILE_SET)` command. + If the file set ``<set>`` exists and is ``PUBLIC`` or ``INTERFACE``, any + files in the set are installed under the destination (see below). + The directory structure relative to the file set's base directories is + preserved. For example, a file added to the file set as + ``/blah/include/myproj/here.h`` with a base directory ``/blah/include`` + would be installed to ``myproj/here.h`` below the destination. + For each of these arguments given, the arguments following them only apply to the target or file type specified in the argument. If none is given, the installation properties apply to all target types. If only one is given then @@ -214,30 +225,32 @@ For regular executables, static libraries and shared libraries, the ``DESTINATION`` argument is not required. For these target types, when ``DESTINATION`` is omitted, a default destination will be taken from the appropriate variable from :module:`GNUInstallDirs`, or set to a built-in -default value if that variable is not defined. The same is true for the -public and private headers associated with the installed targets through the -:prop_tgt:`PUBLIC_HEADER` and :prop_tgt:`PRIVATE_HEADER` target properties. -A destination must always be provided for module libraries, Apple bundles and -frameworks. A destination can be omitted for interface and object libraries, -but they are handled differently (see the discussion of this topic toward the -end of this section). +default value if that variable is not defined. The same is true for file +sets, and the public and private headers associated with the installed +targets through the :prop_tgt:`PUBLIC_HEADER` and :prop_tgt:`PRIVATE_HEADER` +target properties. A destination must always be provided for module libraries, +Apple bundles and frameworks. A destination can be omitted for interface and +object libraries, but they are handled differently (see the discussion of this +topic toward the end of this section). The following table shows the target types with their associated variables and built-in defaults that apply when no destination is given: -================== =============================== ====================== - Target Type GNUInstallDirs Variable Built-In Default -================== =============================== ====================== -``RUNTIME`` ``${CMAKE_INSTALL_BINDIR}`` ``bin`` -``LIBRARY`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib`` -``ARCHIVE`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib`` -``PRIVATE_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include`` -``PUBLIC_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include`` -================== =============================== ====================== +=============================== =============================== ====================== + Target Type GNUInstallDirs Variable Built-In Default +=============================== =============================== ====================== +``RUNTIME`` ``${CMAKE_INSTALL_BINDIR}`` ``bin`` +``LIBRARY`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib`` +``ARCHIVE`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib`` +``PRIVATE_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include`` +``PUBLIC_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include`` +``FILE_SET`` (type ``HEADERS``) ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include`` +=============================== =============================== ====================== Projects wishing to follow the common practice of installing headers into a -project-specific subdirectory will need to provide a destination rather than -rely on the above. +project-specific subdirectory may prefer using file sets with appropriate +paths and base directories. Otherwise, they must provide a ``DESTINATION`` +instead of being able to rely on the above (see next example below). To make packages compliant with distribution filesystem layout policies, if projects must specify a ``DESTINATION``, it is recommended that they use a @@ -246,7 +259,7 @@ This allows package maintainers to control the install destination by setting the appropriate cache variables. The following example shows a static library being installed to the default destination provided by :module:`GNUInstallDirs`, but with its headers installed to a project-specific -subdirectory that follows the above recommendation: +subdirectory without using file sets: .. code-block:: cmake @@ -338,6 +351,11 @@ top level: See documentation of the :prop_tgt:`EXPORT_NAME` target property to change the name of the exported target. + If ``EXPORT`` is used and the targets include ``PUBLIC`` or ``INTERFACE`` + file sets, all of them must be specified with ``FILE_SET`` arguments. All + ``PUBLIC`` or ``INTERFACE`` file sets associated with a target are included + in the export. + ``INCLUDES DESTINATION`` This option specifies a list of directories which will be added to the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property of the @@ -478,6 +496,12 @@ Installing Files .. _FILES: .. _PROGRAMS: +.. note:: + + If installing header files, consider using file sets defined by + :command:`target_sources(FILE_SET)` instead. File sets associate + headers with a target and they install as part of the target. + .. code-block:: cmake install(<FILES|PROGRAMS> files... @@ -534,7 +558,8 @@ file type if they wish to explicitly define the install destination. Projects wishing to follow the common practice of installing headers into a project-specific subdirectory will need to provide a destination rather than -rely on the above. +rely on the above. Using file sets for headers instead of ``install(FILES)`` +would be even better (see :command:`target_sources(FILE_SET)`). Note that some of the types' built-in defaults use the ``DATAROOT`` directory as a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with @@ -547,13 +572,14 @@ projects must specify a ``DESTINATION``, it is recommended that they use a path that begins with the appropriate :module:`GNUInstallDirs` variable. This allows package maintainers to control the install destination by setting the appropriate cache variables. The following example shows how to follow -this advice while installing headers to a project-specific subdirectory: +this advice while installing an image to a project-specific documentation +subdirectory: .. code-block:: cmake include(GNUInstallDirs) - install(FILES mylib.h - DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj + install(FILES logo.png + DESTINATION ${CMAKE_INSTALL_DOCDIR}/myproj ) .. versionadded:: 3.4 @@ -572,6 +598,13 @@ Installing Directories .. _`install(DIRECTORY)`: .. _DIRECTORY: +.. note:: + + To install a directory sub-tree of headers, consider using file sets + defined by :command:`target_sources(FILE_SET)` instead. File sets not only + preserve directory structure, they also associate headers with a target + and install as part of the target. + .. code-block:: cmake install(DIRECTORY dirs... @@ -623,10 +656,10 @@ any expression. For example, the code .. code-block:: cmake - install(DIRECTORY src/ DESTINATION include/myproj - FILES_MATCHING PATTERN "*.h") + install(DIRECTORY src/ DESTINATION doc/myproj + FILES_MATCHING PATTERN "*.png") -will extract and install header files from a source tree. +will extract and install images from a source tree. Some options may follow a ``PATTERN`` or ``REGEX`` expression as described under :ref:`string(REGEX) <Regex Specification>` and are applied @@ -795,7 +828,7 @@ of the ``Development`` component in the package metadata, ensuring that the library is always installed if the headers and CMake export file are present. .. versionadded:: 3.7 - In addition to cmake language files, the ``EXPORT_ANDROID_MK`` mode maybe + In addition to cmake language files, the ``EXPORT_ANDROID_MK`` mode may be used to specify an export to the android ndk build system. This mode accepts the same options as the normal export mode. The Android NDK supports the use of prebuilt libraries, both static and shared. This diff --git a/Help/command/list.rst b/Help/command/list.rst index 9b49cb4..33c4f80 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -128,7 +128,9 @@ Modification list(APPEND <list> [<element> ...]) -Appends elements to the list. +Appends elements to the list. If no variable named ``<list>`` exists in the +current scope its value is treated as empty and the elements are appended to +that empty list. .. _FILTER: @@ -150,7 +152,12 @@ For more information on regular expressions look under list(INSERT <list> <element_index> <element> [<element> ...]) -Inserts elements to the list to the specified location. +Inserts elements to the list to the specified index. It is an +error to specify an out-of-range index. Valid indexes are 0 to `N` +where `N` is the length of the list, inclusive. An empty list +has length 0. If no variable named ``<list>`` exists in the +current scope its value is treated as empty and the elements are +inserted in that empty list. .. _POP_BACK: @@ -186,7 +193,9 @@ to the given variables and then remove the first `N` values from .. versionadded:: 3.15 -Insert elements to the 0th position in the list. +Insert elements to the 0th position in the list. If no variable named +``<list>`` exists in the current scope its value is treated as empty and +the elements are prepended to that empty list. .. _REMOVE_ITEM: diff --git a/Help/command/message.rst b/Help/command/message.rst index e44803e..ca4f5c1 100644 --- a/Help/command/message.rst +++ b/Help/command/message.rst @@ -32,6 +32,9 @@ influences the way the message is handled: ``FATAL_ERROR`` CMake Error, stop processing and generation. + The :manual:`cmake(1)` executable will return a non-zero + :ref:`exit code <CMake Exit Code>`. + ``SEND_ERROR`` CMake Error, continue processing, but skip generation. diff --git a/Help/command/project.rst b/Help/command/project.rst index 2a9dcfe..8f32fa3 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -123,28 +123,56 @@ The options are: The variables set through the ``VERSION``, ``DESCRIPTION`` and ``HOMEPAGE_URL`` options are intended for use as default values in package metadata and documentation. +.. _`Code Injection`: + Code Injection ^^^^^^^^^^^^^^ -If the :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` or -:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` variables are set, -the files they point to will be included as the first step of the -``project()`` command. -If both are set, then :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` will be -included before :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`. - -If the :variable:`CMAKE_PROJECT_INCLUDE` or -:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` variables are set, the files -they point to will be included as the last step of the ``project()`` command. -If both are set, then :variable:`CMAKE_PROJECT_INCLUDE` will be included before -:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`. - -.. versionadded:: 3.15 - Added the ``CMAKE_PROJECT_INCLUDE`` and ``CMAKE_PROJECT_INCLUDE_BEFORE`` - variables. - -.. versionadded:: 3.17 - Added the ``CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`` variable. +A number of variables can be defined by the user to specify files to include +at different points during the execution of the ``project()`` command. +The following outlines the steps performed during a ``project()`` call: + +* .. versionadded:: 3.15 + For every ``project()`` call regardless of the project + name, include the file named by :variable:`CMAKE_PROJECT_INCLUDE_BEFORE`, + if set. + +* .. versionadded:: 3.17 + If the ``project()`` command specifies ``<PROJECT-NAME>`` as its project + name, include the file named by + :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`, if set. + +* Set the various project-specific variables detailed in the `Synopsis`_ + and `Options`_ sections above. + +* For the very first ``project()`` call only: + + * If :variable:`CMAKE_TOOLCHAIN_FILE` is set, read it at least once. + It may be read multiple times and it may also be read again when + enabling languages later (see below). + + * Set the variables describing the host and target platforms. + Language-specific variables might or might not be set at this point. + On the first run, the only language-specific variables that might be + defined are those a toolchain file may have set. On subsequent runs, + language-specific variables cached from a previous run may be set. + + * .. versionadded:: 3.24 + Include each file listed in :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES`, + if set. The variable is ignored by CMake thereafter. + +* Enable any languages specified in the call, or the default languages if + none were provided. The toolchain file may be re-read when enabling a + language for the first time. + +* .. versionadded:: 3.15 + For every ``project()`` call regardless of the project + name, include the file named by :variable:`CMAKE_PROJECT_INCLUDE`, + if set. + +* If the ``project()`` command specifies ``<PROJECT-NAME>`` as its project + name, include the file named by + :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, if set. Usage ^^^^^ diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst index 555520d..b9b12c4 100644 --- a/Help/command/set_property.rst +++ b/Help/command/set_property.rst @@ -85,6 +85,10 @@ It must be one of the following: Scope may name zero or more existing tests. See also the :command:`set_tests_properties` command. + Test property values may be specified using + :manual:`generator expressions <cmake-generator-expressions(7)>` + for tests created by the :command:`add_test(NAME)` signature. + ``CACHE`` Scope must name zero or more cache existing entries. diff --git a/Help/command/set_tests_properties.rst b/Help/command/set_tests_properties.rst index 9bc94ae..eadde33 100644 --- a/Help/command/set_tests_properties.rst +++ b/Help/command/set_tests_properties.rst @@ -9,8 +9,10 @@ Set a property of the tests. Sets a property for the tests. If the test is not found, CMake will report an error. -:manual:`Generator expressions <cmake-generator-expressions(7)>` will be -expanded the same as supported by the test's :command:`add_test` call. + +Test property values may be specified using +:manual:`generator expressions <cmake-generator-expressions(7)>` +for tests created by the :command:`add_test(NAME)` signature. See also the :command:`set_property(TEST)` command. diff --git a/Help/command/string.rst b/Help/command/string.rst index 29ad082..b1ca2cb 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -490,6 +490,9 @@ specifiers: ``%S`` The second of the current minute. 60 represents a leap second. (00-60) +``%f`` + The microsecond of the current second (000000-999999). + ``%U`` The week number of the current year (00-53). @@ -609,7 +612,7 @@ Requires an element of object type. .. code-block:: cmake string(JSON <out-var> [ERROR_VARIABLE <error-variable>] - LENGTH <json-string> <member|index> [<member|index> ...]) + LENGTH <json-string> [<member|index> ...]) Get the length of an element in ``<json-string>`` at the location given by the list of ``<member|index>`` arguments. diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst index 3e53b2e..9a99a7d 100644 --- a/Help/command/target_include_directories.rst +++ b/Help/command/target_include_directories.rst @@ -27,14 +27,16 @@ The following arguments specify include directories. .. versionadded:: 3.11 Allow setting ``INTERFACE`` items on :ref:`IMPORTED targets <Imported Targets>`. -Specified include directories may be absolute paths or relative paths. -Repeated calls for the same <target> append items in the order called. If -``SYSTEM`` is specified, the compiler will be told the -directories are meant as system include directories on some platforms -(signalling this setting might achieve effects such as the compiler -skipping warnings, or these fixed-install system files not being -considered in dependency calculations - see compiler docs). If ``SYSTEM`` -is used together with ``PUBLIC`` or ``INTERFACE``, the +Repeated calls for the same ``<target>`` append items in the order called. + +If ``SYSTEM`` is specified, the compiler will be told the directories +are meant as system include directories on some platforms. This may +have effects such as suppressing warnings or skipping the contained +headers in dependency calculations (see compiler documentation). +Additionally, system include directories are searched after normal +include directories regardless of the order specified. + +If ``SYSTEM`` is used together with ``PUBLIC`` or ``INTERFACE``, the :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` target property will be populated with the specified directories. @@ -43,12 +45,22 @@ with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem properties. +Specified include directories may be absolute paths or relative paths. +A relative path will be interpreted as relative to the current source +directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`) and converted to an +absolute path before storing it in the associated target property. +If the path starts with a generator expression, it will always be assumed +to be an absolute path (with one exception noted below) and will be used +unmodified. + Include directories usage requirements commonly differ between the build-tree -and the install-tree. The ``BUILD_INTERFACE`` and ``INSTALL_INTERFACE`` -generator expressions can be used to describe separate usage requirements -based on the usage location. Relative paths are allowed within the -``INSTALL_INTERFACE`` expression and are interpreted relative to the -installation prefix. For example: +and the install-tree. The :genex:`BUILD_INTERFACE` and +:genex:`INSTALL_INTERFACE` generator expressions can be used to describe +separate usage requirements based on the usage location. Relative paths +are allowed within the :genex:`INSTALL_INTERFACE` expression and are +interpreted as relative to the installation prefix. Relative paths should not +be used in :genex:`BUILD_INTERFACE` expressions because they will not be +converted to absolute. For example: .. code-block:: cmake diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst index 520614a..1ad6c37 100644 --- a/Help/command/target_sources.rst +++ b/Help/command/target_sources.rst @@ -15,34 +15,143 @@ Specifies sources to use when building a target and/or its dependents. The named ``<target>`` must have been created by a command such as :command:`add_executable` or :command:`add_library` or :command:`add_custom_target` and must not be an -:ref:`ALIAS target <Alias Targets>`. - -.. versionchanged:: 3.13 - Relative source file paths are interpreted as being relative to the current - source directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`). - See policy :policy:`CMP0076`. +:ref:`ALIAS target <Alias Targets>`. The ``<items>`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. .. versionadded:: 3.20 ``<target>`` can be a custom target. The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to -specify the scope of the items following them. ``PRIVATE`` and ``PUBLIC`` -items will populate the :prop_tgt:`SOURCES` property of -``<target>``, which are used when building the target itself. +specify the scope of the source file paths (``<items>``) that follow +them. ``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`SOURCES` +property of ``<target>``, which are used when building the target itself. ``PUBLIC`` and ``INTERFACE`` items will populate the :prop_tgt:`INTERFACE_SOURCES` property of ``<target>``, which are used -when building dependents. -The following arguments specify sources. Repeated calls for the same -``<target>`` append items in the order called. The targets created by -:command:`add_custom_target` can only have ``PRIVATE`` scope. +when building dependents. A target created by :command:`add_custom_target` +can only have ``PRIVATE`` scope. + +Repeated calls for the same ``<target>`` append items in the order called. .. versionadded:: 3.3 Allow exporting targets with :prop_tgt:`INTERFACE_SOURCES`. .. versionadded:: 3.11 - Allow setting ``INTERFACE`` items on :ref:`IMPORTED targets <Imported Targets>`. + Allow setting ``INTERFACE`` items on + :ref:`IMPORTED targets <Imported Targets>`. + +.. versionchanged:: 3.13 + Relative source file paths are interpreted as being relative to the current + source directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`). + See policy :policy:`CMP0076`. + +A path that begins with a generator expression is left unmodified. +When a target's :prop_tgt:`SOURCE_DIR` property differs from +:variable:`CMAKE_CURRENT_SOURCE_DIR`, use absolute paths in generator +expressions to ensure the sources are correctly assigned to the target. + +.. code-block:: cmake + + # WRONG: starts with generator expression, but relative path used + target_sources(MyTarget "$<$<CONFIG:Debug>:dbgsrc.cpp>") + + # CORRECT: absolute path used inside the generator expression + target_sources(MyTarget "$<$<CONFIG:Debug>:${CMAKE_CURRENT_SOURCE_DIR}/dbgsrc.cpp>") + +See the :manual:`cmake-buildsystem(7)` manual for more on defining +buildsystem properties. + +File Sets +^^^^^^^^^ + +.. versionadded:: 3.23 + +.. code-block:: cmake + + target_sources(<target> + [<INTERFACE|PUBLIC|PRIVATE> + [FILE_SET <set> [TYPE <type>] [BASE_DIRS <dirs>...] [FILES <files>...]]... + ]...) + +Adds a file set to a target, or adds files to an existing file set. Targets +have zero or more named file sets. Each file set has a name, a type, a scope of +``INTERFACE``, ``PUBLIC``, or ``PRIVATE``, one or more base directories, and +files within those directories. The only acceptable type is ``HEADERS``. The +optional default file sets are named after their type. The target may not be a +custom target or :prop_tgt:`FRAMEWORK` target. + +Files in a ``PRIVATE`` or ``PUBLIC`` file set are marked as source files for +the purposes of IDE integration. Additionally, files in ``HEADERS`` file sets +have their :prop_sf:`HEADER_FILE_ONLY` property set to ``TRUE``. Files in an +``INTERFACE`` or ``PUBLIC`` file set can be installed with the +:command:`install(TARGETS)` command, and exported with the +:command:`install(EXPORT)` and :command:`export` commands. + +Each ``target_sources(FILE_SET)`` entry starts with ``INTERFACE``, ``PUBLIC``, or +``PRIVATE`` and accepts the following arguments: + +``FILE_SET <set>`` + + The name of the file set to create or add to. It must contain only letters, + numbers and underscores. Names starting with a capital letter are reserved + for built-in file sets predefined by CMake. The only predefined set name is + ``HEADERS``. All other set names must not start with a capital letter or + underscore. + +``TYPE <type>`` + + Every file set is associated with a particular type of file. ``HEADERS`` + is currently the only defined type and it is an error to specify anything + else. As a special case, if the name of the file set is ``HEADERS``, the + type does not need to be specified and the ``TYPE <type>`` arguments can be + omitted. For all other file set names, ``TYPE`` is required. + +``BASE_DIRS <dirs>...`` + + An optional list of base directories of the file set. Any relative path + is treated as relative to the current source directory + (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`). If no ``BASE_DIRS`` are + specified when the file set is first created, the value of + :variable:`CMAKE_CURRENT_SOURCE_DIR` is added. This argument supports + :manual:`generator expressions <cmake-generator-expressions(7)>`. + + No two base directories for a file set may be sub-directories of each other. + This requirement must be met across all base directories added to a file set, + not just those within a single call to ``target_sources()``. + +``FILES <files>...`` + + An optional list of files to add to the file set. Each file must be in + one of the base directories, or a subdirectory of one of the base + directories. This argument supports + :manual:`generator expressions <cmake-generator-expressions(7)>`. + + If relative paths are specified, they are considered relative to + :variable:`CMAKE_CURRENT_SOURCE_DIR` at the time ``target_sources()`` is + called. An exception to this is a path starting with ``$<``. Such paths + are treated as relative to the target's source directory after evaluation + of generator expressions. + +The following target properties are set by ``target_sources(FILE_SET)``, +but they should not generally be manipulated directly: + +* :prop_tgt:`HEADER_SETS` +* :prop_tgt:`INTERFACE_HEADER_SETS` +* :prop_tgt:`HEADER_SET` +* :prop_tgt:`HEADER_SET_<NAME>` +* :prop_tgt:`HEADER_DIRS` +* :prop_tgt:`HEADER_DIRS_<NAME>` + +Target properties related to include directories are also modified by +``target_sources(FILE_SET)`` as follows: + +:prop_tgt:`INCLUDE_DIRECTORIES` + + If the ``TYPE`` is ``HEADERS``, and the scope of the file set is ``PRIVATE`` + or ``PUBLIC``, all of the ``BASE_DIRS`` of the file set are wrapped in + :genex:`$<BUILD_INTERFACE>` and appended to this property. + +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` -Arguments to ``target_sources`` may use "generator expressions" -with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` -manual for available expressions. See the :manual:`cmake-buildsystem(7)` -manual for more on defining buildsystem properties. + If the ``TYPE`` is ``HEADERS``, and the scope of the file set is + ``INTERFACE`` or ``PUBLIC``, all of the ``BASE_DIRS`` of the file set are + wrapped in :genex:`$<BUILD_INTERFACE>` and appended to this property. diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index 08f8d5b..806a98d 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -7,6 +7,8 @@ try_compile Try building some code. +.. _`Try Compiling Whole Projects`: + Try Compiling Whole Projects ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -25,6 +27,15 @@ will not be deleted after this command is run. Specify ``<targetName>`` to build a specific target instead of the ``all`` or ``ALL_BUILD`` target. See below for the meaning of other options. +.. versionchanged:: 3.24 + CMake variables describing platform settings, and those listed by the + :variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES` variable, are propagated + into the project's build configuration. See policy :policy:`CMP0137`. + Previously this was only done by the + :ref:`source file <Try Compiling Source Files>` signature. + +.. _`Try Compiling Source Files`: + Try Compiling Source Files ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -150,6 +161,7 @@ Other Behavior Settings * :variable:`CMAKE_LINK_SEARCH_END_STATIC` * :variable:`CMAKE_MSVC_RUNTIME_LIBRARY` * :variable:`CMAKE_POSITION_INDEPENDENT_CODE` + * :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY` If :policy:`CMP0056` is set to ``NEW``, then :variable:`CMAKE_EXE_LINKER_FLAGS` is passed in as well. @@ -204,3 +216,7 @@ a build configuration. .. versionchanged:: 3.14 For the :generator:`Green Hills MULTI` generator the GHS toolset and target system customization cache variables are also propagated into the test project. + +.. versionadded:: 3.24 + The :variable:`CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES` variable may be + set to disable passing platform variables into the test project. diff --git a/Help/cpack_gen/dmg.rst b/Help/cpack_gen/dmg.rst index 1f05618..cba7a00 100644 --- a/Help/cpack_gen/dmg.rst +++ b/Help/cpack_gen/dmg.rst @@ -54,6 +54,27 @@ on macOS: Default behavior is to include a symlink to ``/Applications`` in the DMG. Set this option to ``ON`` to avoid adding the symlink. +.. variable:: CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE + + .. versionadded:: 3.23 + + Control whether :variable:`CPACK_RESOURCE_FILE_LICENSE`, if set to a + non-default value, is used as the license agreement provided when + mounting the DMG. If ``CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE`` is + not set, :manual:`cpack(1)` defaults to off. + + In a CMake project that uses the :module:`CPack` module to generate + ``CPackConfig.cmake``, ``CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE`` + must be explicitly enabled by the project to activate the SLA. + See policy :policy:`CMP0133`. + + .. note:: + + This option was added in response to macOS 12.0's deprecation of + the ``hdiutil udifrez`` command to make its use optional. + CPack 3.22 and below always use :variable:`CPACK_RESOURCE_FILE_LICENSE`, + if set to a non-default value, as the DMG license. + .. variable:: CPACK_DMG_SLA_DIR .. versionadded:: 3.5 diff --git a/Help/cpack_gen/ifw.rst b/Help/cpack_gen/ifw.rst index 6817eac..c23bab4 100644 --- a/Help/cpack_gen/ifw.rst +++ b/Help/cpack_gen/ifw.rst @@ -24,12 +24,12 @@ Microsoft Windows, and macOS. To make use of this generator, QtIFW needs to be installed. The :module:`CPackIFW` module looks for the location of the QtIFW command-line utilities, and defines several commands to -control the behavior of this generator. +control the behavior of this generator. See `Hints for Finding QtIFW`_. Variables ^^^^^^^^^ -You can use the following variables to change behavior of CPack ``IFW`` +You can use the following variables to change the behavior of the CPack ``IFW`` generator. Debug @@ -48,12 +48,12 @@ Package .. variable:: CPACK_IFW_PACKAGE_TITLE Name of the installer as displayed on the title bar. - By default used :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`. + If not specified, it defaults to :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`. .. variable:: CPACK_IFW_PACKAGE_PUBLISHER Publisher of the software (as shown in the Windows Control Panel). - By default used :variable:`CPACK_PACKAGE_VENDOR`. + If not specified, it defaults to :variable:`CPACK_PACKAGE_VENDOR`. .. variable:: CPACK_IFW_PRODUCT_URL @@ -61,83 +61,93 @@ Package .. variable:: CPACK_IFW_PACKAGE_ICON - Filename for a custom installer icon. The actual file is '.icns' (macOS), - '.ico' (Windows). No functionality on Unix. + Filename for a custom installer icon. It must be an absolute path. + This should be a ``.icns`` file on macOS and a ``.ico`` file on Windows. + It is ignored on other platforms. .. variable:: CPACK_IFW_PACKAGE_WINDOW_ICON Filename for a custom window icon in PNG format for the Installer - application. + application. It must be an absolute path. .. variable:: CPACK_IFW_PACKAGE_LOGO - Filename for a logo is used as QWizard::LogoPixmap. + Filename for a logo image in PNG format, used as ``QWizard::LogoPixmap``. + It must be an absolute path. .. variable:: CPACK_IFW_PACKAGE_WATERMARK .. versionadded:: 3.8 - Filename for a watermark is used as QWizard::WatermarkPixmap. + Filename for a watermark image in PNG format, used as + ``QWizard::WatermarkPixmap``. It must be an absolute path. .. variable:: CPACK_IFW_PACKAGE_BANNER .. versionadded:: 3.8 - Filename for a banner is used as QWizard::BannerPixmap. + Filename for a banner image in PNG format, used as ``QWizard::BannerPixmap``. + It must be an absolute path. .. variable:: CPACK_IFW_PACKAGE_BACKGROUND .. versionadded:: 3.8 - Filename for an image used as QWizard::BackgroundPixmap (only used by MacStyle). + Filename for a background image in PNG format, used as + ``QWizard::BackgroundPixmap`` (only used by ``MacStyle``). It must be an + absolute path. .. variable:: CPACK_IFW_PACKAGE_WIZARD_STYLE .. versionadded:: 3.8 - Wizard style to be used ("Modern", "Mac", "Aero" or "Classic"). + Wizard style to be used (``Modern``, ``Mac``, ``Aero`` or ``Classic``). .. variable:: CPACK_IFW_PACKAGE_WIZARD_DEFAULT_WIDTH .. versionadded:: 3.8 - Default width of the wizard in pixels. Setting a banner image will override this. + Default width of the wizard in pixels. Setting a banner image will override + this. .. variable:: CPACK_IFW_PACKAGE_WIZARD_DEFAULT_HEIGHT .. versionadded:: 3.8 - Default height of the wizard in pixels. Setting a watermark image will override this. + Default height of the wizard in pixels. Setting a watermark image will + override this. .. variable:: CPACK_IFW_PACKAGE_WIZARD_SHOW_PAGE_LIST .. versionadded:: 3.20 - Set to ``OFF`` if the widget listing installer pages on the left side of the wizard should not be shown. + Set to ``OFF`` if the widget listing installer pages on the left side of the + wizard should not be shown. - It is ``ON`` by default, but will only have an effect if using QtIFW 4.0 or later. + It is ``ON`` by default, but will only have an effect if using QtIFW 4.0 or + later. .. variable:: CPACK_IFW_PACKAGE_TITLE_COLOR .. versionadded:: 3.8 - Color of the titles and subtitles (takes an HTML color code, such as "#88FF33"). + Color of the titles and subtitles (takes an HTML color code, such as + ``#88FF33``). .. variable:: CPACK_IFW_PACKAGE_STYLE_SHEET .. versionadded:: 3.15 - Filename for a stylesheet. + Filename for a stylesheet. It must be an absolute path. .. variable:: CPACK_IFW_TARGET_DIRECTORY Default target directory for installation. - By default used - "@ApplicationsDir@/:variable:`CPACK_PACKAGE_INSTALL_DIRECTORY`" - (variables embedded in '@' are expanded by the - `QtIFW scripting engine <https://doc.qt.io/qtinstallerframework/scripting.html>`_). - - You can use predefined variables. + If :variable:`CPACK_PACKAGE_INSTALL_DIRECTORY` is set, this defaults to + ``@ApplicationsDir@/${CPACK_PACKAGE_INSTALL_DIRECTORY}``. If that variable + isn't set either, the default used is ``@RootDir@/usr/local``. + Predefined variables of the form ``@...@`` are expanded by the + `QtIFW scripting engine <https://doc.qt.io/qtinstallerframework/scripting.html>`_. .. variable:: CPACK_IFW_ADMIN_TARGET_DIRECTORY @@ -155,29 +165,28 @@ Package .. variable:: CPACK_IFW_PACKAGE_GROUP - The group, which will be used to configure the root package + The group, which will be used to configure the root package. .. variable:: CPACK_IFW_PACKAGE_NAME - The root package name, which will be used if configuration group is not - specified + The root package name, which will be used if the configuration group is not + specified. .. variable:: CPACK_IFW_PACKAGE_START_MENU_DIRECTORY .. versionadded:: 3.3 Name of the default program group for the product in the Windows Start menu. - - By default used :variable:`CPACK_IFW_PACKAGE_NAME`. + If not specified, it defaults to :variable:`CPACK_IFW_PACKAGE_NAME`. .. variable:: CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_NAME .. versionadded:: 3.3 Filename of the generated maintenance tool. - The platform-specific executable file extension is appended. + The platform-specific executable file extension will be appended. - By default used QtIFW defaults (``maintenancetool``). + If not specified, QtIFW provides a default name (``maintenancetool``). .. variable:: CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_INI_FILE @@ -185,15 +194,15 @@ Package Filename for the configuration of the generated maintenance tool. - By default used QtIFW defaults (``maintenancetool.ini``). + If not specified, QtIFW uses a default file name (``maintenancetool.ini``). .. variable:: CPACK_IFW_PACKAGE_ALLOW_NON_ASCII_CHARACTERS .. versionadded:: 3.3 Set to ``ON`` if the installation path can contain non-ASCII characters. - - Is ``ON`` for QtIFW less 2.0 tools. + Only supported for QtIFW 2.0 and later. Older QtIFW versions will always + allow non-ASCII characters. .. variable:: CPACK_IFW_PACKAGE_ALLOW_SPACE_IN_PATH @@ -203,6 +212,14 @@ Package Is ``ON`` for QtIFW less 2.0 tools. +.. variable:: CPACK_IFW_PACKAGE_DISABLE_COMMAND_LINE_INTERFACE + + .. versionadded:: 3.23 + + Set to ``ON`` if command line interface features should be disabled. + It is ``OFF`` by default and will only have an effect if using QtIFW 4.0 or + later. + .. variable:: CPACK_IFW_PACKAGE_CONTROL_SCRIPT .. versionadded:: 3.3 @@ -213,10 +230,11 @@ Package .. versionadded:: 3.7 - List of additional resources ('.qrc' files) to include in the installer - binary. + List of additional resources (``.qrc`` files) to include in the installer + binary. They should be specified as absolute paths and no two resource files + can have the same file name. - You can use :command:`cpack_ifw_add_package_resources` command to resolve + You can use the :command:`cpack_ifw_add_package_resources` command to resolve relative paths. .. variable:: CPACK_IFW_PACKAGE_FILE_EXTENSION @@ -226,27 +244,117 @@ Package The target binary extension. On Linux, the name of the target binary is automatically extended with - '.run', if you do not specify the extension. + ``.run``, if you do not specify the extension. On Windows, the target is created as an application with the extension - '.exe', which is automatically added, if not supplied. + ``.exe``, which is automatically added, if not supplied. On Mac, the target is created as an DMG disk image with the extension - '.dmg', which is automatically added, if not supplied. + ``.dmg``, which is automatically added, if not supplied. .. variable:: CPACK_IFW_REPOSITORIES_ALL The list of remote repositories. The default value of this variable is computed by CPack and contains - all repositories added with command :command:`cpack_ifw_add_repository` - or updated with command :command:`cpack_ifw_update_repository`. + all repositories added with :command:`cpack_ifw_add_repository` + or updated with :command:`cpack_ifw_update_repository`. .. variable:: CPACK_IFW_DOWNLOAD_ALL - If this is ``ON`` all components will be downloaded. - By default is ``OFF`` or used value - from ``CPACK_DOWNLOAD_ALL`` if set + If this is ``ON``, all components will be downloaded. If not set, the + behavior is determined by whether :command:`cpack_configure_downloads` has + been called with the ``ALL`` option or not. + +.. variable:: CPACK_IFW_PACKAGE_PRODUCT_IMAGES + + .. versionadded:: 3.23 + + A list of images to be shown on the ``PerformInstallationPage``. These + must be absolute paths and the images must be in PNG format. + + This feature is available for QtIFW 4.0.0 and later. + +.. variable:: CPACK_IFW_PACKAGE_RUN_PROGRAM + + .. versionadded:: 3.23 + + Command executed after the installer is finished, if the user accepts the + action. Provide the full path to the application, as found when installed. + This typically means the path should begin with the QtIFW predefined variable + ``@TargetDir@``. + + This feature is available for QtIFW 4.0.0 and later. + +.. variable:: CPACK_IFW_PACKAGE_RUN_PROGRAM_ARGUMENTS + + .. versionadded:: 3.23 + + List of arguments passed to the program specified in + :variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM`. + + This feature is available for QtIFW 4.0.0 and later. + +.. variable:: CPACK_IFW_PACKAGE_RUN_PROGRAM_DESCRIPTION + + .. versionadded:: 3.23 + + Text shown next to the check box for running the program after the + installation. If :variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM` is set but no + description is provided, QtIFW will use a default message like + ``Run <Name> now``. + + This feature is available for QtIFW 4.0.0 and later. + +.. variable:: CPACK_IFW_PACKAGE_SIGNING_IDENTITY + + .. versionadded:: 3.23 + + Allows specifying a code signing identity to be used for signing the generated + app bundle. Only available on macOS, ignored on other platforms. + +.. variable:: CPACK_IFW_ARCHIVE_FORMAT + + .. versionadded:: 3.23 + + Set the format used when packaging new component data archives. If you omit + this option, the ``7z`` format will be used as a default. Supported formats: + + * 7z + * zip + * tar.gz + * tar.bz2 + * tar.xz + + .. note:: + + If the Qt Installer Framework tools were built without libarchive support, + only ``7z`` format is supported. + + This feature is available for QtIFW 4.2.0 and later. + +.. variable:: CPACK_IFW_ARCHIVE_COMPRESSION + + .. versionadded:: 3.23 + + Archive compression level. The allowable values are: + + * 0 (*No compression*) + * 1 (*Fastest compression*) + * 3 (*Fast compression*) + * 5 (*Normal compression*) + * 7 (*Maximum compression*) + * 9 (*Ultra compression*) + + If this variable is not set, QtIFW will use a default compression level, + which will typically be 5 (*Normal compression*). + + .. note:: + + Some formats do not support all the possible values. For example ``zip`` + compression only supports values from 1 to 7. + + This feature is available for QtIFW 4.2.0 and later. Components """""""""" @@ -257,16 +365,17 @@ Components .. variable:: CPACK_IFW_PACKAGES_DIRECTORIES - Additional prepared packages dirs that will be used to resolve + Additional prepared packages directories that will be used to resolve dependent components. .. variable:: CPACK_IFW_REPOSITORIES_DIRECTORIES .. versionadded:: 3.10 - Additional prepared repository dirs that will be used to resolve and - repack dependent components. This feature available only - since QtIFW 3.1. + Additional prepared repository directories that will be used to resolve and + repack dependent components. + + This feature is available for QtIFW 3.1 and later. QtIFW Tools """"""""""" @@ -275,10 +384,11 @@ QtIFW Tools .. versionadded:: 3.3 - The version of used QtIFW tools. + The version of the QtIFW tools that will be used. This variable is set + by the :module:`CPackIFW` module. The following variables provide the locations of the QtIFW -command-line tools as discovered by the module :module:`CPackIFW`. +command-line tools as discovered by the :module:`CPackIFW` module. These variables are cached, and may be configured if needed. .. variable:: CPACK_IFW_ARCHIVEGEN_EXECUTABLE @@ -306,30 +416,33 @@ These variables are cached, and may be configured if needed. Hints for Finding QtIFW """"""""""""""""""""""" -Generally, the CPack ``IFW`` generator automatically finds QtIFW tools, -but if you don't use a default path for installation of the QtIFW tools, -the path may be specified in either a CMake or an environment variable: +Generally, the CPack ``IFW`` generator automatically finds QtIFW tools. +The following (in order of precedence) can also be set to augment the +locations normally searched by :command:`find_program`: .. variable:: CPACK_IFW_ROOT - .. versionadded:: 3.9 + .. versionadded:: 3.9 + + CMake variable + +.. envvar:: CPACK_IFW_ROOT - An CMake variable which specifies the location of the QtIFW tool suite. + .. versionadded:: 3.9 - The variable will be cached in the ``CPackConfig.cmake`` file and used at - CPack runtime. + Environment variable .. variable:: QTIFWDIR - An environment variable which specifies the location of the QtIFW tool - suite. + CMake variable -.. note:: - The specified path should not contain "bin" at the end - (for example: "D:\\DevTools\\QtIFW2.0.5"). +.. envvar:: QTIFWDIR + + Environment variable -The :variable:`CPACK_IFW_ROOT` variable has a higher priority and overrides -the value of the :variable:`QTIFWDIR` variable. +.. note:: + The specified path should not contain ``bin`` at the end + (for example: ``D:\\DevTools\\QtIFW2.0.5``). Other Settings ^^^^^^^^^^^^^^ @@ -337,7 +450,7 @@ Other Settings Online installer """""""""""""""" -By default, this generator generates an *offline installer*. This means that +By default, this generator generates an *offline installer*. This means that all packaged files are fully contained in the installer executable. In contrast, an *online installer* will download some or all components from @@ -367,14 +480,13 @@ CMake script. This is an optional feature. Installers created by QtIFW tools have built-in support for internationalization and many phrases are localized to many languages, -but this does not apply to the description of the your components and groups -that will be distributed. +but this does not apply to the description of your components and groups. Localization of the description of your components and groups is useful for users of your installers. -A localized variable or argument can contain a single default value, and a -set of pairs the name of the locale and the localized value. +A localized variable or argument can contain a single default value, and +after that a set of pairs with the name of the locale and the localized value. For example: @@ -392,16 +504,16 @@ See Also Qt Installer Framework Manual: * Index page: - http://doc.qt.io/qtinstallerframework/index.html + https://doc.qt.io/qtinstallerframework/index.html * Component Scripting: - http://doc.qt.io/qtinstallerframework/scripting.html + https://doc.qt.io/qtinstallerframework/scripting.html * Predefined Variables: - http://doc.qt.io/qtinstallerframework/scripting.html#predefined-variables + https://doc.qt.io/qtinstallerframework/scripting.html#predefined-variables * Promoting Updates: - http://doc.qt.io/qtinstallerframework/ifw-updates.html + https://doc.qt.io/qtinstallerframework/ifw-updates.html Download Qt Installer Framework for your platform from Qt site: - http://download.qt.io/official_releases/qt-installer-framework + https://download.qt.io/official_releases/qt-installer-framework diff --git a/Help/cpack_gen/packagemaker.rst b/Help/cpack_gen/packagemaker.rst index 256446d..6614f31 100644 --- a/Help/cpack_gen/packagemaker.rst +++ b/Help/cpack_gen/packagemaker.rst @@ -1,87 +1,7 @@ CPack PackageMaker Generator ---------------------------- -PackageMaker CPack generator (macOS). - -.. deprecated:: 3.17 - - Xcode no longer distributes the PackageMaker tools. - This CPack generator will be removed in a future version of CPack. - -Variables specific to CPack PackageMaker generator -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The following variable is specific to installers built on Mac -macOS using PackageMaker: - -.. variable:: CPACK_OSX_PACKAGE_VERSION - - The version of macOS that the resulting PackageMaker archive should be - compatible with. Different versions of macOS support different - features. For example, CPack can only build component-based installers for - macOS 10.4 or newer, and can only build installers that download - components on-the-fly for macOS 10.5 or newer. If left blank, this value - will be set to the minimum version of macOS that supports the requested - features. Set this variable to some value (e.g., 10.4) only if you want to - guarantee that your installer will work on that version of macOS, and - don't mind missing extra features available in the installer shipping with - later versions of macOS. - -Background Image -"""""""""""""""" - -.. versionadded:: 3.17 - -This group of variables controls the background image of the generated -installer. - -.. variable:: CPACK_PACKAGEMAKER_BACKGROUND - - Adds a background to Distribution XML if specified. The value contains the - path to image in ``Resources`` directory. - -.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_ALIGNMENT - - Adds an ``alignment`` attribute to the background in Distribution XML. - Refer to Apple documentation for valid values. - -.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_SCALING - - Adds a ``scaling`` attribute to the background in Distribution XML. - Refer to Apple documentation for valid values. - -.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_MIME_TYPE - - Adds a ``mime-type`` attribute to the background in Distribution XML. - The option contains MIME type of an image. - -.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_UTI - - Adds an ``uti`` attribute to the background in Distribution XML. - The option contains UTI type of an image. - -.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA - - Adds a background for the Dark Aqua theme to Distribution XML if - specified. The value contains the path to image in ``Resources`` - directory. - -.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_ALIGNMENT - - Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_ALIGNMENT` option, - but for the dark theme. - -.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_SCALING - - Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_SCALING` option, - but for the dark theme. - -.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_MIME_TYPE - - Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_MIME_TYPE` option, - but for the dark theme. - -.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_UTI - - Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_UTI` option, - but for the dark theme. +Removed. This once generated PackageMaker installers, but the +generator has been removed since CMake 3.24. Xcode no longer distributes +the PackageMaker tools. Use the :cpack_gen:`CPack productbuild Generator` +instead. diff --git a/Help/cpack_gen/productbuild.rst b/Help/cpack_gen/productbuild.rst index cf3041f..48a9b44 100644 --- a/Help/cpack_gen/productbuild.rst +++ b/Help/cpack_gen/productbuild.rst @@ -18,6 +18,14 @@ macOS using ProductBuild: the automatically detected command (or specify its location if the auto-detection fails to find it). +.. variable:: CPACK_PRODUCTBUILD_IDENTIFIER + + .. versionadded:: 3.23 + + Set the unique (non-localized) product identifier to be associated with the + product (i.e., ``com.kitware.cmake``). Any component product names will be + appended to this value. + .. variable:: CPACK_PRODUCTBUILD_IDENTITY_NAME .. versionadded:: 3.8 @@ -78,6 +86,65 @@ macOS using ProductBuild: :variable:`CPACK_RESOURCE_FILE_README`, and :variable:`CPACK_RESOURCE_FILE_LICENSE` files are copied. +.. variable:: CPACK_PRODUCTBUILD_DOMAINS + + .. versionadded:: 3.23 + + This option enables more granular control over where the product may be + installed. When it is set to true, a ``domains`` element of the following + form will be added to the productbuild Distribution XML: + + .. code-block:: xml + + <domains enable_anywhere="true" enable_currentUserHome="false" enable_localSystem="true"/> + + The default values are as shown above, but can be overridden with + :variable:`CPACK_PRODUCTBUILD_DOMAINS_ANYWHERE`, + :variable:`CPACK_PRODUCTBUILD_DOMAINS_USER`, and + :variable:`CPACK_PRODUCTBUILD_DOMAINS_ROOT`. + +.. variable:: CPACK_PRODUCTBUILD_DOMAINS_ANYWHERE + + .. versionadded:: 3.23 + + May be used to override the ``enable_anywhere`` attribute in the ``domains`` + element of the Distribution XML. When set to true, the product can be + installed at the root of any volume, including non-system volumes. + + :variable:`CPACK_PRODUCTBUILD_DOMAINS` must be set to true for this variable + to have any effect. + +.. variable:: CPACK_PRODUCTBUILD_DOMAINS_USER + + .. versionadded:: 3.23 + + May be used to override the ``enable_currentUserHome`` attribute in the + ``domains`` element of the Distribution XML. When set to true, the product + can be installed into the current user's home directory. Note that when + installing into the user's home directory, the following additional + requirements will apply: + + * The installer may not write outside the user's home directory. + * The install will be performed as the current user rather than as ``root``. + This may have ramifications for :variable:`CPACK_PREFLIGHT_<COMP>_SCRIPT` + and :variable:`CPACK_POSTFLIGHT_<COMP>_SCRIPT`. + * Administrative privileges will not be needed to perform the install. + + :variable:`CPACK_PRODUCTBUILD_DOMAINS` must be set to true for this variable + to have any effect. + +.. variable:: CPACK_PRODUCTBUILD_DOMAINS_ROOT + + .. versionadded:: 3.23 + + May be used to override the ``enable_localSystem`` attribute in the + ``domains`` element of the Distribution XML. When set to true, the product + can be installed in the root directory. This should normally be set to true + unless the product should only be installed to the user's home directory. + + :variable:`CPACK_PRODUCTBUILD_DOMAINS` must be set to true for this variable + to have any effect. + Background Image """""""""""""""" @@ -136,3 +203,47 @@ installer. Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_UTI` option, but for the dark theme. + +Distribution XML Template +^^^^^^^^^^^^^^^^^^^^^^^^^ + +CPack uses a template file to generate the ``distribution.dist`` file used +internally by this package generator. Ordinarily, CMake provides the template +file, but projects may supply their own by placing a file called +``CPack.distribution.dist.in`` in one of the directories listed in the +:variable:`CMAKE_MODULE_PATH` variable. CPack will then pick up the project's +template file instead of using its own. + +The ``distribution.dist`` file is generated by performing substitutions +similar to the :command:`configure_file` command. Any variable set when +CPack runs will be available for substitution using the usual ``@...@`` +form. The following variables are also set internally and made available for +substitution: + +``CPACK_RESOURCE_FILE_LICENSE_NOPATH`` + Same as :variable:`CPACK_RESOURCE_FILE_LICENSE` except without the path. + The named file will be available in the same directory as the generated + ``distribution.dist`` file. + +``CPACK_RESOURCE_FILE_README_NOPATH`` + Same as :variable:`CPACK_RESOURCE_FILE_README` except without the path. + The named file will be available in the same directory as the generated + ``distribution.dist`` file. + +``CPACK_RESOURCE_FILE_WELCOME_NOPATH`` + Same as :variable:`CPACK_RESOURCE_FILE_WELCOME` except without the path. + The named file will be available in the same directory as the generated + ``distribution.dist`` file. + +``CPACK_APPLE_PKG_INSTALLER_CONTENT`` + .. versionadded:: 3.23 + + This contains all the XML elements that specify installer-wide options + (including domain details), default backgrounds and the choices outline. + +``CPACK_PACKAGEMAKER_CHOICES`` + .. deprecated:: 3.23 + + This contains only the XML elements that specify the default backgrounds + and the choices outline. It does not include the installer-wide options or + any domain details. Use ``CPACK_APPLE_PKG_INSTALLER_CONTENT`` instead. diff --git a/Help/cpack_gen/wix.rst b/Help/cpack_gen/wix.rst index 79f835e..a3d43fc 100644 --- a/Help/cpack_gen/wix.rst +++ b/Help/cpack_gen/wix.rst @@ -320,3 +320,20 @@ Windows using WiX. name is the plain namespace without the usual xmlns: prefix and url is an unquoted namespace url. A list of commonly known WiX schemata can be found here: https://wixtoolset.org/documentation/manual/v3/xsd/ + +.. variable:: CPACK_WIX_SKIP_WIX_UI_EXTENSION + + .. versionadded:: 3.23 + + If this variable is set then the inclusion of WixUIExtensions is skipped, + i.e. the ``-ext "WixUIExtension"`` command line is not included during + the execution of the WiX light tool. + +.. variable:: CPACK_WIX_ARCHITECTURE + + .. versionadded:: 3.24 + + This variable can be optionally set to specify the target architecture + of the installer. May for example be set to ``x64`` or ``arm64``. + + When unspecified, CPack will default to ``x64`` or ``x86``. diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst index 4a2a5d9..db92022 100644 --- a/Help/dev/documentation.rst +++ b/Help/dev/documentation.rst @@ -513,7 +513,7 @@ bracket is excluded if and only if the line starts in ``#``. Additional such ``.rst:`` comments may appear anywhere in the module file. All such comments must start with ``#`` in the first column. -For example, a ``Findxxx.cmake`` module may contain: +For example, a ``FindXxx.cmake`` module may contain: :: @@ -540,13 +540,13 @@ For example, a ``Findxxx.cmake`` module may contain: <code> #[=======================================================================[.rst: - .. command:: xxx_do_something + .. command:: Xxx_do_something This command does something for Xxx:: - xxx_do_something(some arguments) + Xxx_do_something(some arguments) #]=======================================================================] - macro(xxx_do_something) + macro(Xxx_do_something) <code> endmacro() @@ -559,3 +559,56 @@ documentation, simply leave out the ``Help/module/<module-name>.rst`` file and the ``Help/manual/cmake-modules.7.rst`` toctree entry. .. _`Bracket Comment`: https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#bracket-comment + +Module Functions and Macros +--------------------------- + +Modules may provide CMake functions and macros defined by the `function()`_ +and `macro()`_ commands. To avoid conflicts across modules, name the +functions and macros using the prefix ``<ModuleName>_`` followed by the +rest of the name, where ``<ModuleName>`` is the exact-case spelling of +the module name. We have no convention for the portion of names after +the ``<ModuleName>_`` prefix. + +For historical reasons, some modules that come with CMake do not follow +this prefix convention. When adding new functions to these modules, +discussion during review can decide whether to follow their existing +convention or to use the module name prefix. + +Documentation of public functions and macros should be provided in +the module, typically in the main `module documentation`_ at the top. +For example, a ``MyModule`` module may document a function like this:: + + #[=======================================================================[.rst: + MyModule + -------- + + This is my module. It provides some functions. + + .. command:: MyModule_Some_Function + + This is some function: + + .. code-block:: cmake + + MyModule_Some_Function(...) + #]=======================================================================] + +Documentation may alternatively be placed just before each definition. +For example, a ``MyModule`` module may document another function like this:: + + #[=======================================================================[.rst: + .. command:: MyModule_Other_Function + + This is another function: + + .. code-block:: cmake + + MyModule_Other_Function(...) + #]=======================================================================] + function(MyModule_Other_Function ...) + # ... + endfunction() + +.. _`function()`: https://cmake.org/cmake/help/latest/command/function.html +.. _`macro()`: https://cmake.org/cmake/help/latest/command/macro.html diff --git a/Help/dev/experimental.rst b/Help/dev/experimental.rst index 2380de4..7638d22 100644 --- a/Help/dev/experimental.rst +++ b/Help/dev/experimental.rst @@ -36,7 +36,14 @@ For example, add code like the following to a test project: The tool specified by ``CMAKE_EXPERIMENTAL_CXX_SCANDEP_SOURCE`` is expected to process the translation unit, write preprocessor dependencies to the file specified by the ``<DEP_FILE>`` placeholder, and write module -dependencies to the file specified by the ``<DYNDEP_FILE>`` placeholder. +dependencies to the file specified by the ``<DYNDEP_FILE>`` placeholder. The +``CMAKE_EXPERIMENTAL_CXX_SCANDEP_DEPFILE_FORMAT`` file may be set to ``msvc`` +for scandep rules which use ``msvc``-style dependency reporting. + +For tools which need to know the file set the source belongs to, the +``CMAKE_EXPERIMENTAL_CXX_MODULE_SOURCE_TYPE_FLAG_<FILE_SET_TYPE>`` flag may +be provided so that different source types can be distinguished prior to +scanning. The module dependencies should be written in the format described by the `P1689r4`_ paper. diff --git a/Help/dev/maint.rst b/Help/dev/maint.rst index 4c2b6a1..53be91f 100644 --- a/Help/dev/maint.rst +++ b/Help/dev/maint.rst @@ -256,8 +256,8 @@ Update ``Source/CMakeVersion.cmake`` to set the version to set(CMake_VERSION_PATCH 0) set(CMake_VERSION_RC 0) -Update uses of ``DEVEL_CMAKE_VERSION`` in the source tree to mention the -actual version number: +Replace uses of ``DEVEL_CMAKE_VERSION`` in the source tree with +the literal release version number string ``"$major.$minor.0"``: .. code-block:: shell diff --git a/Help/dev/source.rst b/Help/dev/source.rst index 9be4451..f488b3e 100644 --- a/Help/dev/source.rst +++ b/Help/dev/source.rst @@ -35,6 +35,18 @@ Available features are: * From ``C++14``: + * ``<cm/array>``: + ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``, + ``cm::crbegin``, ``cm::crend`` + + * ``<cm/deque>``: + ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``, + ``cm::crbegin``, ``cm::crend`` + + * ``<cm/forward_list>``: + ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``, + ``cm::crbegin``, ``cm::crend`` + * ``<cm/iomanip>``: ``cm::quoted`` @@ -42,68 +54,142 @@ Available features are: ``cm::make_reverse_iterator``, ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``, ``cm::crbegin``, ``cm::crend`` + * ``<cm/list>``: + ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``, + ``cm::crbegin``, ``cm::crend`` + + * ``<cm/map>``: + ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``, + ``cm::crbegin``, ``cm::crend`` + * ``<cm/memory>``: ``cm::make_unique`` + * ``<cm/set>``: + ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``, + ``cm::crbegin``, ``cm::crend`` + + * ``<cm/string>``: + ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``, + ``cm::crbegin``, ``cm::crend`` + + * ``<cm/string_view>``: + ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``, + ``cm::crbegin``, ``cm::crend`` + * ``<cm/shared_mutex>``: ``cm::shared_lock`` * ``<cm/type_traits>``: ``cm::enable_if_t`` + * ``<cm/unordered_map>``: + ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``, + ``cm::crbegin``, ``cm::crend`` + + * ``<cm/unordered_set>``: + ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``, + ``cm::crbegin``, ``cm::crend`` + + * ``<cm/vector>``: + ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``, + ``cm::crbegin``, ``cm::crend`` + * From ``C++17``: * ``<cm/algorithm>``: ``cm::clamp`` + * ``<cm/array>``: + ``cm::size``, ``cm::empty``, ``cm::data`` + + * ``<cm/deque>``: + ``cm::size``, ``cm::empty``, ``cm::data`` + * ``cm/filesystem>``: ``cm::filesystem::path`` + * ``<cm/forward_list>``: + ``cm::size``, ``cm::empty``, ``cm::data`` + * ``<cm/iterator>``: ``cm::size``, ``cm::empty``, ``cm::data`` + * ``<cm/list>``: + ``cm::size``, ``cm::empty``, ``cm::data`` + + * ``<cm/map>``: + ``cm::size``, ``cm::empty``, ``cm::data`` + * ``<cm/optional>``: ``cm::nullopt_t``, ``cm::nullopt``, ``cm::optional``, ``cm::make_optional``, ``cm::bad_optional_access`` + * ``<cm/set>``: + ``cm::size``, ``cm::empty``, ``cm::data`` + * ``<cm/shared_mutex>``: ``cm::shared_mutex`` + * ``<cm/string>``: + ``cm::size``, ``cm::empty``, ``cm::data`` + * ``<cm/string_view>``: - ``cm::string_view`` + ``cm::string_view``, ``cm::size``, ``cm::empty``, ``cm::data`` * ``<cm/type_traits>``: ``cm::bool_constant``, ``cm::invoke_result_t``, ``cm::invoke_result``, ``cm::void_t`` + * ``<cm/unordered_map>``: + ``cm::size``, ``cm::empty``, ``cm::data`` + + * ``<cm/unordered_set>``: + ``cm::size``, ``cm::empty``, ``cm::data`` + * ``<cm/utility>``: ``cm::in_place_t``, ``cm::in_place`` + * ``<cm/vector>``: + ``cm::size``, ``cm::empty``, ``cm::data`` + * From ``C++20``: + * ``<cm/array>``: + ``cm::ssize`` + * ``<cm/deque>``: - ``cm::erase``, ``cm::erase_if`` + ``cm::erase``, ``cm::erase_if``, ``cm::ssize`` + + * ``<cm/forward_list>``: + ``cm::ssize`` + + * ``<cm/iterator>``: + ``cm::ssize`` * ``<cm/list>``: - ``cm::erase``, ``cm::erase_if`` + ``cm::erase``, ``cm::erase_if``, ``cm::ssize`` * ``<cm/map>`` : - ``cm::erase_if`` + ``cm::erase_if``, ``cm::ssize`` * ``<cm/set>`` : - ``cm::erase_if`` + ``cm::erase_if``, ``cm::ssize`` + + * ``<cm/string_view>``: + ``cm::ssize`` * ``<cm/string>``: - ``cm::erase``, ``cm::erase_if`` + ``cm::erase``, ``cm::erase_if``, ``cm::ssize`` * ``<cm/unordered_map>``: - ``cm::erase_if`` + ``cm::erase_if``, ``cm::ssize`` * ``<cm/unordered_set>``: - ``cm::erase_if`` + ``cm::erase_if``, ``cm::ssize`` * ``<cm/vector>``: - ``cm::erase``, ``cm::erase_if`` + ``cm::erase``, ``cm::erase_if``, ``cm::ssize`` Additionally, some useful non-standard extensions to the C++ standard library are available in headers under the directory ``cmext/`` in namespace ``cm``. @@ -117,6 +203,11 @@ These are: * ``cm::contains``: Checks if element or key is contained in container. +* ``<cmext/enum_set>`` + + * ``cm::enum_set``: + Container to manage set of elements from an ``enum class`` definition. + * ``<cmext/iterator>``: * ``cm::is_terator``: diff --git a/Help/envvar/ADSP_ROOT.rst b/Help/envvar/ADSP_ROOT.rst new file mode 100644 index 0000000..fabf1bb --- /dev/null +++ b/Help/envvar/ADSP_ROOT.rst @@ -0,0 +1,8 @@ +ADSP_ROOT +--------- + +.. include:: ENV_VAR.txt + +The ``ADSP_ROOT`` environment variable specifies a default value +for the :variable:`CMAKE_ADSP_ROOT` variable when there is no explicit +configuration given on the first run while creating a new build tree. diff --git a/Help/envvar/CMAKE_COLOR_DIAGNOSTICS.rst b/Help/envvar/CMAKE_COLOR_DIAGNOSTICS.rst new file mode 100644 index 0000000..d3d0aa9 --- /dev/null +++ b/Help/envvar/CMAKE_COLOR_DIAGNOSTICS.rst @@ -0,0 +1,9 @@ +CMAKE_COLOR_DIAGNOSTICS +----------------------- + +.. versionadded:: 3.24 + +.. include:: ENV_VAR.txt + +Specifies a default value for the :variable:`CMAKE_COLOR_DIAGNOSTICS` variable +when there is no explicit value given on the first run. diff --git a/Help/envvar/CUDAARCHS.rst b/Help/envvar/CUDAARCHS.rst index 82369cd..e9e6a42 100644 --- a/Help/envvar/CUDAARCHS.rst +++ b/Help/envvar/CUDAARCHS.rst @@ -6,8 +6,7 @@ CUDAARCHS .. include:: ENV_VAR.txt Value used to initialize :variable:`CMAKE_CUDA_ARCHITECTURES` on the first -configuration if it's not already defined. Subsequent runs will use the value -stored in the cache. +configuration. Subsequent runs will use the value stored in the cache. This is a semicolon-separated list of architectures as described in :prop_tgt:`CUDA_ARCHITECTURES`. diff --git a/Help/envvar/CUDAHOSTCXX.rst b/Help/envvar/CUDAHOSTCXX.rst index cf65927..74f5d48 100644 --- a/Help/envvar/CUDAHOSTCXX.rst +++ b/Help/envvar/CUDAHOSTCXX.rst @@ -8,9 +8,8 @@ CUDAHOSTCXX Preferred executable for compiling host code when compiling ``CUDA`` language files. Will only be used by CMake on the first configuration to determine ``CUDA`` host compiler, after which the value for ``CUDAHOSTCXX`` is -stored in the cache as :variable:`CMAKE_CUDA_HOST_COMPILER`. For any -configuration run (including the first), the environment variable will be -ignored if the :variable:`CMAKE_CUDA_HOST_COMPILER` variable is defined. +stored in the cache as :variable:`CMAKE_CUDA_HOST_COMPILER`. This environment +variable is preferred over :variable:`CMAKE_CUDA_HOST_COMPILER`. This environment variable is primarily meant for use with projects that enable ``CUDA`` as a first-class language. diff --git a/Help/envvar/DESTDIR.rst b/Help/envvar/DESTDIR.rst index d2144ae..94cae4a 100644 --- a/Help/envvar/DESTDIR.rst +++ b/Help/envvar/DESTDIR.rst @@ -5,17 +5,26 @@ DESTDIR On UNIX one can use the ``DESTDIR`` mechanism in order to relocate the whole installation. ``DESTDIR`` means DESTination DIRectory. It is -commonly used by makefile users in order to install software at -non-default location. It is usually invoked like this: +commonly used by packagers to install software in a staging directory. -:: +For example, running - make DESTDIR=/home/john install +.. code-block:: shell -which will install the concerned software using the installation -prefix, e.g. ``/usr/local`` prepended with the ``DESTDIR`` value which -finally gives ``/home/john/usr/local``. + make DESTDIR=/package/stage install -WARNING: ``DESTDIR`` may not be used on Windows because installation -prefix usually contains a drive letter like in ``C:/Program Files`` -which cannot be prepended with some other prefix. +will install the software using the installation prefix, e.g. ``/usr/local``, +prepended with the ``DESTDIR`` value which gives ``/package/stage/usr/local``. +The packaging tool may then construct the package from the content of the +``/package/stage`` directory. + +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 ``--install`` mode, +one may specify a different prefix using the ``--prefix`` option. + +.. note:: + + ``DESTDIR`` may not be used on Windows because installation + prefix usually contains a drive letter like in ``C:/Program Files`` + which cannot be prepended with some other prefix. diff --git a/Help/generator/Green Hills MULTI.rst b/Help/generator/Green Hills MULTI.rst index 5d2b1cd..1b4739b 100644 --- a/Help/generator/Green Hills MULTI.rst +++ b/Help/generator/Green Hills MULTI.rst @@ -8,70 +8,125 @@ Green Hills MULTI Generates Green Hills MULTI project files (experimental, work-in-progress). -Customizations are available through the following cache variables: - -* ``GHS_CUSTOMIZATION`` -* ``GHS_GPJ_MACROS`` - -.. versionadded:: 3.14 The buildsystem has predetermined build-configuration settings that can be controlled via the :variable:`CMAKE_BUILD_TYPE` variable. -Toolset and Platform Selection -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Platform Selection +^^^^^^^^^^^^^^^^^^ .. versionadded:: 3.13 -Customizations that are used to pick toolset and target system: +The variable ``GHS_PRIMARY_TARGET`` can be used to select the target platform. + + | Sets ``primaryTarget`` entry in project file. + +For example: -* The ``-A <arch>`` can be supplied for setting the target architecture. - ``<arch>`` usually is one of ``arm``, ``ppc``, ``86``, etcetera. - If the target architecture is not specified then - the default architecture of ``arm`` will be used. +* ``cmake -G "Green Hills MULTI" -D GHS_PRIMARY_TARGET=ppc_integrity.tgt`` -* The ``-T <toolset>`` option can be used to set the directory location of the toolset. - Both absolute and relative paths are valid. Relative paths use ``GHS_TOOLSET_ROOT`` - as the root. If the toolset is not specified then the latest toolset found in - ``GHS_TOOLSET_ROOT`` will be used. +Otherwise the ``primaryTarget`` will be composed from the values of :variable:`CMAKE_GENERATOR_PLATFORM` +and ``GHS_TARGET_PLATFORM``. Defaulting to the value of ``arm_integrity.tgt`` -Cache variables that are used for toolset and target system customization: +* The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps + via the :manual:`cmake(1)` ``-A`` option. -* ``GHS_TARGET_PLATFORM`` + | Typical values of ``arm``, ``ppc``, ``86``, etcetera, are used. + +* The variable ``GHS_TARGET_PLATFORM`` may be set, perhaps via the :manual:`cmake(1)` + ``-D`` option. | Defaults to ``integrity``. | Usual values are ``integrity``, ``threadx``, ``uvelosity``, ``velosity``, ``vxworks``, ``standalone``. -* ``GHS_PRIMARY_TARGET`` +For example: - | Sets ``primaryTarget`` entry in project file. - | Defaults to ``<arch>_<GHS_TARGET_PLATFORM>.tgt``. +* ``cmake -G "Green Hills MULTI"`` for ``arm_integrity.tgt``. +* ``cmake -G "Green Hills MULTI" -A 86`` for ``86_integrity.tgt``. +* ``cmake -G "Green Hills MULTI" -D GHS_TARGET_PLATFORM=standalone`` for ``arm_standalone.tgt``. +* ``cmake -G "Green Hills MULTI" -A ppc -D GHS_TARGET_PLATFORM=standalone`` for ``ppc_standalone.tgt``. -* ``GHS_TOOLSET_ROOT`` +Toolset Selection +^^^^^^^^^^^^^^^^^ - | Root path for ``toolset`` searches. - | Defaults to ``C:/ghs`` in Windows or ``/usr/ghs`` in Linux. +.. versionadded:: 3.13 -* ``GHS_OS_ROOT`` +The generator searches for the latest compiler or can be given a location to use. +``GHS_TOOLSET_ROOT`` is the directory that is checked for the latest compiler. - | Root path for RTOS searches. +* The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps + via the :manual:`cmake(1)` ``-T`` option, to specify the location of the toolset. + Both absolute and relative paths are valid. Paths are relative to ``GHS_TOOLSET_ROOT``. + +* The variable ``GHS_TOOLSET_ROOT`` may be set, perhaps via the :manual:`cmake(1)` + ``-D`` option. + + | Root path for toolset searches and relative paths. | Defaults to ``C:/ghs`` in Windows or ``/usr/ghs`` in Linux. +For example, setting a specific compiler: + +* ``cmake -G "Green Hills MULTI" -T comp_201754`` for ``/usr/ghs/comp_201754``. +* ``cmake -G "Green Hills MULTI" -T comp_201754 -D GHS_TOOLSET_ROOT=/opt/ghs`` for ``/opt/ghs/comp_201754``. +* ``cmake -G "Green Hills MULTI" -T /usr/ghs/comp_201554`` +* ``cmake -G "Green Hills MULTI" -T C:/ghs/comp_201754`` + +For example, searching for latest compiler: + +* ``cmake -G "Green Hills MULTI"`` for searching ``/usr/ghs``. +* ``cmake -G "Green Hills MULTI -D GHS_TOOLSET_ROOT=/opt/ghs"`` for searching ``/opt/ghs``. + +.. note:: + The :variable:`CMAKE_GENERATOR_TOOLSET` should use CMake style paths. + +OS and BSP Selection +^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.3 + +Certain target platforms, like Integrity, require an OS. The RTOS directory path +can be explicitly set using ``GHS_OS_DIR``. Otherwise ``GHS_OS_ROOT`` will be +searched for the latest Integrity RTOS. + +If the target platform, like Integrity, requires a BSP name then it can be set via +the ``GHS_BSP_NAME`` variable. + * ``GHS_OS_DIR`` and ``GHS_OS_DIR_OPTION`` | Sets ``-os_dir`` entry in project file. - | Defaults to latest platform OS installation at ``GHS_OS_ROOT``. Set this value if - a specific RTOS is to be used. + | ``GHS_OS_DIR_OPTION`` default value is ``-os_dir``. .. versionadded:: 3.15 The ``GHS_OS_DIR_OPTION`` variable. + For example: + + * ``cmake -G "Green Hills MULTI" -D GHS_OS_DIR=/usr/ghs/int1144`` + +* ``GHS_OS_ROOT`` + + | Root path for RTOS searches. + | Defaults to ``C:/ghs`` in Windows or ``/usr/ghs`` in Linux. + + For example: + + * ``cmake -G "Green Hills MULTI" -D GHS_OS_ROOT=/opt/ghs`` + * ``GHS_BSP_NAME`` | Sets ``-bsp`` entry in project file. | Defaults to ``sim<arch>`` for ``integrity`` platforms. + For example: + + * ``cmake -G "Green Hills MULTI"`` for ``simarm`` on ``arm_integrity.tgt``. + * ``cmake -G "Green Hills MULTI" -A 86`` for ``sim86`` on ``86_integrity.tgt``. + * ``cmake -G "Green Hills MULTI" -A ppc -D GHS_BSP_NAME=sim800`` for ``sim800`` + on ``ppc_integrity.tgt``. + * ``cmake -G "Green Hills MULTI" -D GHS_PRIMARY_TARGET=ppc_integrity.tgt -D GHS_BSP_NAME=fsl-t1040`` + for ``fsl-t1040`` on ``ppc_integrity.tgt``. + Target Properties ^^^^^^^^^^^^^^^^^ @@ -82,6 +137,17 @@ The following properties are available: * :prop_tgt:`GHS_INTEGRITY_APP` * :prop_tgt:`GHS_NO_SOURCE_GROUP_FILE` +MULTI Project Variables +^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.3 + +Adding a Customization file and macros are available through the use of the following +variables: + +* ``GHS_CUSTOMIZATION`` - CMake path name to Customization File. +* ``GHS_GPJ_MACROS`` - CMake list of Macros. + .. note:: This generator is deemed experimental as of CMake |release| and is still a work in progress. Future versions of CMake diff --git a/Help/generator/Visual Studio 15 2017.rst b/Help/generator/Visual Studio 15 2017.rst index b4d6f6d..912afad 100644 --- a/Help/generator/Visual Studio 15 2017.rst +++ b/Help/generator/Visual Studio 15 2017.rst @@ -17,18 +17,8 @@ Instance Selection .. versionadded:: 3.11 -VS 2017 supports multiple installations on the same machine. -The :variable:`CMAKE_GENERATOR_INSTANCE` variable may be set as a -cache entry containing the absolute path to a Visual Studio instance. -If the value is not specified explicitly by the user or a toolchain file, -CMake queries the Visual Studio Installer to locate VS instances, chooses -one, and sets the variable as a cache entry to hold the value persistently. - -When CMake first chooses an instance, if the ``VS150COMNTOOLS`` environment -variable is set and points to the ``Common7/Tools`` directory within -one of the instances, that instance will be used. Otherwise, if more -than one instance is installed we do not define which one is chosen -by default. +VS 2017 supports multiple installations on the same machine. The +:variable:`CMAKE_GENERATOR_INSTANCE` variable may be used to select one. Platform Selection ^^^^^^^^^^^^^^^^^^ diff --git a/Help/generator/Visual Studio 16 2019.rst b/Help/generator/Visual Studio 16 2019.rst index 72399e0..6cefe6d 100644 --- a/Help/generator/Visual Studio 16 2019.rst +++ b/Help/generator/Visual Studio 16 2019.rst @@ -15,18 +15,8 @@ Powershell, Python, etc.) are not supported. Instance Selection ^^^^^^^^^^^^^^^^^^ -VS 2019 supports multiple installations on the same machine. -The :variable:`CMAKE_GENERATOR_INSTANCE` variable may be set as a -cache entry containing the absolute path to a Visual Studio instance. -If the value is not specified explicitly by the user or a toolchain file, -CMake queries the Visual Studio Installer to locate VS instances, chooses -one, and sets the variable as a cache entry to hold the value persistently. - -When CMake first chooses an instance, if the ``VS160COMNTOOLS`` environment -variable is set and points to the ``Common7/Tools`` directory within -one of the instances, that instance will be used. Otherwise, if more -than one instance is installed we do not define which one is chosen -by default. +VS 2019 supports multiple installations on the same machine. The +:variable:`CMAKE_GENERATOR_INSTANCE` variable may be used to select one. Platform Selection ^^^^^^^^^^^^^^^^^^ diff --git a/Help/generator/Visual Studio 17 2022.rst b/Help/generator/Visual Studio 17 2022.rst index b3f49f3..edf9d60 100644 --- a/Help/generator/Visual Studio 17 2022.rst +++ b/Help/generator/Visual Studio 17 2022.rst @@ -15,18 +15,8 @@ Powershell, Python, etc.) are not supported. Instance Selection ^^^^^^^^^^^^^^^^^^ -VS 2022 supports multiple installations on the same machine. -The :variable:`CMAKE_GENERATOR_INSTANCE` variable may be set as a -cache entry containing the absolute path to a Visual Studio instance. -If the value is not specified explicitly by the user or a toolchain file, -CMake queries the Visual Studio Installer to locate VS instances, chooses -one, and sets the variable as a cache entry to hold the value persistently. - -When CMake first chooses an instance, if the ``VS170COMNTOOLS`` environment -variable is set and points to the ``Common7/Tools`` directory within -one of the instances, that instance will be used. Otherwise, if more -than one instance is installed we do not define which one is chosen -by default. +VS 2022 supports multiple installations on the same machine. The +:variable:`CMAKE_GENERATOR_INSTANCE` variable may be used to select one. Platform Selection ^^^^^^^^^^^^^^^^^^ diff --git a/Help/guide/ide-integration/index.rst b/Help/guide/ide-integration/index.rst index 779883b..8473481 100644 --- a/Help/guide/ide-integration/index.rst +++ b/Help/guide/ide-integration/index.rst @@ -65,6 +65,12 @@ run: cmake -S /path/to/source -B /path/to/source/build -G Ninja +In cases where a preset contains lots of cache variables, and passing all of +them as ``-D`` flags would cause the command line length limit of the platform +to be exceeded, the IDE should instead construct a temporary cache script and +pass it with the ``-C`` flag. See :ref:`CMake Options` for details on how the +``-C`` flag is used. + While reading, parsing, and evaluating the contents of ``CMakePresets.json`` is straightforward, it is not trivial. In addition to the documentation, IDE vendors may also wish to refer to the CMake source code and test cases for a @@ -124,3 +130,31 @@ obtain this information and use it to present the user with a list of tests. IDEs should not invoke the ``test`` target of the generated buildsystem. Instead, they should invoke :manual:`ctest(1)` directly. + +IDEs with CMake integration +=========================== + +The following IDEs support CMake natively: + +* `CLion`_ +* `KDevelop`_ +* `QtCreator`_ +* `Vim`_ (via a plugin) +* `Visual Studio`_ +* `VSCode`_ (via a plugin) + +.. _CLion: https://www.jetbrains.com/clion/ +.. _KDevelop: https://www.kdevelop.org/ +.. _QtCreator: https://www.qt.io/product/development-tools +.. _Vim: https://www.vim.org/ +.. _Visual Studio: https://visualstudio.microsoft.com/ +.. _VSCode: https://code.visualstudio.com/ + +Additionally, CMake has builtin support for some IDEs: + +* :ref:`IDE Build Tool Generators`: + Generate IDE native build systems such as Visual Studio or Xcode. +* :ref:`Extra Generators`: + Extend :ref:`Command-Line Build Tool Generators` to generate IDE + project files that hook into the command-line build system. + Superseded by the :manual:`File API <cmake-file-api(7)>`. diff --git a/Help/guide/importing-exporting/MathFunctionsComponents/Config.cmake.in b/Help/guide/importing-exporting/MathFunctionsComponents/Config.cmake.in index 09f6c35..a535969 100644 --- a/Help/guide/importing-exporting/MathFunctionsComponents/Config.cmake.in +++ b/Help/guide/importing-exporting/MathFunctionsComponents/Config.cmake.in @@ -1,9 +1,9 @@ @PACKAGE_INIT@ -set(_supported_components Addition SquareRoot) +set(_MathFunctions_supported_components Addition SquareRoot) foreach(_comp ${MathFunctions_FIND_COMPONENTS}) - if (NOT _comp IN_LIST _supported_components) + if (NOT _comp IN_LIST _MathFunctions_supported_components) set(MathFunctions_FOUND False) set(MathFunctions_NOT_FOUND_MESSAGE "Unsupported component: ${_comp}") endif() diff --git a/Help/guide/tutorial/Adding a Library.rst b/Help/guide/tutorial/Adding a Library.rst index ed03448..71755be 100644 --- a/Help/guide/tutorial/Adding a Library.rst +++ b/Help/guide/tutorial/Adding a Library.rst @@ -23,8 +23,9 @@ directory: To make use of the new library we will add an :command:`add_subdirectory` call in the top-level ``CMakeLists.txt`` file so that the library will get built. We add the new library to the executable, and add ``MathFunctions`` as -an include directory so that the ``mysqrt.h`` header file can be found. The -last few lines of the top-level ``CMakeLists.txt`` file should now look like: +an include directory so that the ``MathFunctions.h`` header file can be found. +The last few lines of the top-level ``CMakeLists.txt`` file should now look +like: .. code-block:: cmake :caption: CMakeLists.txt diff --git a/Help/guide/tutorial/Complete/CMakeLists.txt b/Help/guide/tutorial/Complete/CMakeLists.txt index ac1d083..41baf64 100644 --- a/Help/guide/tutorial/Complete/CMakeLists.txt +++ b/Help/guide/tutorial/Complete/CMakeLists.txt @@ -10,7 +10,7 @@ target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) # add compiler warning flags just when building this project via # the BUILD_INTERFACE genex -set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU>") +set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>") set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") target_compile_options(tutorial_compiler_flags INTERFACE "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" @@ -88,6 +88,7 @@ include(InstallRequiredSystemLibraries) set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") +set(CPACK_SOURCE_GENERATOR "TGZ") include(CPack) # install the configuration targets diff --git a/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt index a47d5e0..40b9fd2 100644 --- a/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt @@ -62,6 +62,6 @@ if(TARGET SqrtLibrary) list(APPEND installable_libs SqrtLibrary) endif() install(TARGETS ${installable_libs} - DESTINATION lib - EXPORT MathFunctionsTargets) + EXPORT MathFunctionsTargets + DESTINATION lib) install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Packaging an Installer.rst b/Help/guide/tutorial/Packaging an Installer.rst index 5eb3e3e..0ee5db2 100644 --- a/Help/guide/tutorial/Packaging an Installer.rst +++ b/Help/guide/tutorial/Packaging an Installer.rst @@ -22,8 +22,9 @@ That is all there is to it. We start by including libraries that are needed by the project for the current platform. Next we set some CPack variables to where we have stored the license and version information for this project. The version information was set earlier in this -tutorial and the ``license.txt`` has been included in the top-level source -directory for this step. +tutorial and the ``License.txt`` has been included in the top-level source +directory for this step. The :variable:`CPACK_SOURCE_GENERATOR` variable +selects a file format for the source package. Finally we include the :module:`CPack module <CPack>` which will use these variables and some other properties of the current system to setup an @@ -44,7 +45,11 @@ To specify the generator, use the ``-G`` option. For multi-config builds, use cpack -G ZIP -C Debug -To create a source distribution you would type: +For a list of available generators, see :manual:`cpack-generators(7)` or call +``cpack --help``. An :cpack_gen:`archive generator <CPack Archive Generator>` +like ZIP creates a compressed archive of all *installed* files. + +To create an archive of the *full* source tree you would type: .. code-block:: console diff --git a/Help/guide/tutorial/Step10/CMakeLists.txt b/Help/guide/tutorial/Step10/CMakeLists.txt index dc9a0e8..55dc409 100644 --- a/Help/guide/tutorial/Step10/CMakeLists.txt +++ b/Help/guide/tutorial/Step10/CMakeLists.txt @@ -70,4 +70,5 @@ include(InstallRequiredSystemLibraries) set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") +set(CPACK_SOURCE_GENERATOR "TGZ") include(CPack) diff --git a/Help/guide/tutorial/Step11/CMakeLists.txt b/Help/guide/tutorial/Step11/CMakeLists.txt index 10f35ce..1044748 100644 --- a/Help/guide/tutorial/Step11/CMakeLists.txt +++ b/Help/guide/tutorial/Step11/CMakeLists.txt @@ -8,7 +8,7 @@ target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) # add compiler warning flags just when building this project via # the BUILD_INTERFACE genex -set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU>") +set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>") set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") target_compile_options(tutorial_compiler_flags INTERFACE "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" @@ -78,4 +78,5 @@ include(InstallRequiredSystemLibraries) set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") +set(CPACK_SOURCE_GENERATOR "TGZ") include(CPack) diff --git a/Help/guide/tutorial/Step12/CMakeLists.txt b/Help/guide/tutorial/Step12/CMakeLists.txt index 634b84c..63f9643 100644 --- a/Help/guide/tutorial/Step12/CMakeLists.txt +++ b/Help/guide/tutorial/Step12/CMakeLists.txt @@ -8,7 +8,7 @@ target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) # add compiler warning flags just when building this project via # the BUILD_INTERFACE genex -set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU>") +set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>") set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") target_compile_options(tutorial_compiler_flags INTERFACE "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" diff --git a/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt index ea3861c..d5961da 100644 --- a/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt @@ -58,6 +58,6 @@ if(TARGET SqrtLibrary) list(APPEND installable_libs SqrtLibrary) endif() install(TARGETS ${installable_libs} - DESTINATION lib - EXPORT MathFunctionsTargets) + EXPORT MathFunctionsTargets + DESTINATION lib) install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step8/CMakeLists.txt b/Help/guide/tutorial/Step8/CMakeLists.txt index 4ae898f..4c78b94 100644 --- a/Help/guide/tutorial/Step8/CMakeLists.txt +++ b/Help/guide/tutorial/Step8/CMakeLists.txt @@ -70,4 +70,5 @@ include(InstallRequiredSystemLibraries) set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") +set(CPACK_SOURCE_GENERATOR "TGZ") include(CPack) diff --git a/Help/guide/tutorial/Step9/CMakeLists.txt b/Help/guide/tutorial/Step9/CMakeLists.txt index 130bc9a..6bae26e 100644 --- a/Help/guide/tutorial/Step9/CMakeLists.txt +++ b/Help/guide/tutorial/Step9/CMakeLists.txt @@ -69,4 +69,5 @@ include(InstallRequiredSystemLibraries) set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") +set(CPACK_SOURCE_GENERATOR "TGZ") include(CPack) diff --git a/Help/guide/tutorial/index.rst b/Help/guide/tutorial/index.rst index 8b20a2d..09553cb 100644 --- a/Help/guide/tutorial/index.rst +++ b/Help/guide/tutorial/index.rst @@ -11,8 +11,9 @@ work together in an example project can be very helpful. Steps ===== -The tutorial documentation and source code for examples can be found in -the ``Help/guide/tutorial`` directory of the CMake source code tree. +.. include:: source.txt + +|tutorial_source| Each step has its own subdirectory containing code that may be used as a starting point. The tutorial examples are progressive so that each step provides the complete solution for the previous step. diff --git a/Help/guide/tutorial/source.txt b/Help/guide/tutorial/source.txt new file mode 100644 index 0000000..bb45e86 --- /dev/null +++ b/Help/guide/tutorial/source.txt @@ -0,0 +1,3 @@ +.. |tutorial_source| replace:: + The tutorial documentation and source code examples can be found in + the ``Help/guide/tutorial`` directory of the CMake source code tree. diff --git a/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt b/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt index a54d728..73e1907 100644 --- a/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt +++ b/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt @@ -1,11 +1,11 @@ -Note that it is not advisable to populate the ``INSTALL_INTERFACE`` of the -|INTERFACE_PROPERTY_LINK| of a target with absolute paths to the include +Note that it is not advisable to populate the :genex:`INSTALL_INTERFACE` of +the |INTERFACE_PROPERTY_LINK| of a target with absolute paths to the include directories of dependencies. That would hard-code into installed packages the include directory paths for dependencies **as found on the machine the package was made on**. -The ``INSTALL_INTERFACE`` of the |INTERFACE_PROPERTY_LINK| is only +The :genex:`INSTALL_INTERFACE` of the |INTERFACE_PROPERTY_LINK| is only suitable for specifying the required include directories for headers provided with the target itself, not those provided by the transitive dependencies listed in its :prop_tgt:`INTERFACE_LINK_LIBRARIES` target diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 2f43070..bceff2d 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -675,7 +675,9 @@ listed in the :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` of the dependency. This can result in omission of compiler warnings for headers found in those directories. This behavior for :ref:`imported targets` may be controlled by setting the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target -property on the *consumers* of imported targets. +property on the *consumers* of imported targets, or by setting the +:prop_tgt:`IMPORTED_NO_SYSTEM` target property on the imported targets +themselves. If a binary target is linked transitively to a macOS :prop_tgt:`FRAMEWORK`, the ``Headers`` directory of the framework is also treated as a usage requirement. @@ -1038,24 +1040,26 @@ Additionally, IDEs will show the source files as part of the target for interactive reading and editing. A primary use-case for ``INTERFACE`` libraries is header-only libraries. +Since CMake 3.23, header files may be associated with a library by adding +them to a header set using the :command:`target_sources` command: .. code-block:: cmake - add_library(Eigen INTERFACE - src/eigen.h - src/vector.h - src/matrix.h - ) - target_include_directories(Eigen INTERFACE - $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src> - $<INSTALL_INTERFACE:include/Eigen> + add_library(Eigen INTERFACE) + + target_sources(Eigen INTERFACE + FILE_SET HEADERS + BASE_DIRS src + FILES src/eigen.h src/vector.h src/matrix.h ) add_executable(exe1 exe1.cpp) target_link_libraries(exe1 Eigen) -Here, the usage requirements from the ``Eigen`` target are consumed and used -when compiling, but it has no effect on linking. +When we specify the ``FILE_SET`` here, the ``BASE_DIRS`` we define automatically +become include directories in the usage requirements for the target ``Eigen``. +The usage requirements from the target are consumed and used when compiling, but +have no effect on linking. Another use-case is to employ an entirely target-focussed design for usage requirements: @@ -1079,26 +1083,25 @@ This way, the build specification of ``exe1`` is expressed entirely as linked targets, and the complexity of compiler-specific flags is encapsulated in an ``INTERFACE`` library target. -``INTERFACE`` libraries may be installed and exported. Any content they refer -to must be installed separately: +``INTERFACE`` libraries may be installed and exported. We can install the +default header set along with the target: .. code-block:: cmake - set(Eigen_headers - src/eigen.h - src/vector.h - src/matrix.h - ) - add_library(Eigen INTERFACE ${Eigen_headers}) - target_include_directories(Eigen INTERFACE - $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src> - $<INSTALL_INTERFACE:include/Eigen> + add_library(Eigen INTERFACE) + + target_sources(Eigen INTERFACE + FILE_SET HEADERS + BASE_DIRS src + FILES src/eigen.h src/vector.h src/matrix.h ) - install(TARGETS Eigen EXPORT eigenExport) + install(TARGETS Eigen EXPORT eigenExport + FILE_SET HEADERS DESTINATION include/Eigen) install(EXPORT eigenExport NAMESPACE Upstream:: DESTINATION lib/cmake/Eigen ) - install(FILES ${Eigen_headers} - DESTINATION include/Eigen - ) + +Here, the headers defined in the header set are installed to ``include/Eigen``. +The install destination automatically becomes an include directory that is a +usage requirement for consumers. diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index 67b0f6e..8073511 100644 --- a/Help/manual/cmake-compile-features.7.rst +++ b/Help/manual/cmake-compile-features.7.rst @@ -115,6 +115,8 @@ of at-least C++ 11 (or C++ 14, C++ 17, ...), adding flags such as ``-std=gnu++11`` if necessary. This applies to sources within ``mylib`` as well as any dependents (that may include headers from ``mylib``). +.. include:: ../prop_gbl/CMAKE_LANG_STD_FLAGS.txt + Availability of Compiler Extensions ----------------------------------- diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index fe146de..2c6cd96 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -242,6 +242,69 @@ backwards compatibility for any old names that were actually in use. Make sure you comment them as deprecated, so that no-one starts using them. +.. _`Find Using Windows Registry`: + +Find Using Windows Registry +--------------------------- + +.. versionchanged:: 3.24 + +Options ``HINTS`` and ``PATHS`` of :command:`find_file`, +:command:`find_library`, :command:`find_path`, :command:`find_program`, and +:command:`find_package` commands offer the possibility, on ``Windows`` +platform, to query the registry. + +The formal syntax, as specified using +`BNF <https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form>`_ notation with +the regular extensions, for registry query is the following: + +.. raw:: latex + + \begin{small} + +.. productionlist:: + registry_query: '[' `sep_definition`? `root_key` + : ((`key_separator` `sub_key`)? (`value_separator` `value_name`_)?)? ']' + sep_definition: '{' `value_separator` '}' + root_key: 'HKLM' | 'HKEY_LOCAL_MACHINE' | 'HKCU' | 'HKEY_CURRENT_USER' | + : 'HKCR' | 'HKEY_CLASSES_ROOT' | 'HKCC' | 'HKEY_CURRENT_CONFIG' | + : 'HKU' | 'HKEY_USERS' + sub_key: `element` (`key_separator` `element`)* + key_separator: '/' | '\\' + value_separator: `element` | ';' + value_name: `element` | '(default)' + element: `character`\+ + character: <any character except `key_separator` and `value_separator`> + +.. raw:: latex + + \end{small} + +The :token:`sep_definition` optional item offers the possibility to specify +the string used to separate the :token:`sub_key` from the :token:`value_name` +item. If not specified, the character ``;`` is used. Multiple +:token:`registry_query` items can be specified as part of a path. + +.. code-block:: cmake + + # example using default separator + find_file(... PATHS "/root/[HKLM/Stuff;InstallDir]/lib[HKLM\\\\Stuff;Architecture]") + + # example using different specified separators + find_library(... HINTS "/root/[{|}HKCU/Stuff|InstallDir]/lib[{@@}HKCU\\\\Stuff@@Architecture]") + +If the :token:`value_name` item is not specified or has the special name +``(default)``, the content of the default value, if any, will be returned. The +supported types for the :token:`value_name` are: + +* ``REG_SZ``. +* ``REG_EXPAND_SZ``. The returned data is expanded. +* ``REG_DWORD``. +* ``REG_QWORD``. + +When the registry query failed, typically because the key does not exist or +the data type is not supported, the string ``/REGISTRY-NOTFOUND`` is substituted +to the ``[]`` query expression. A Sample Find Module -------------------- diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index 0799fdd..737b22c 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -28,9 +28,11 @@ Environment Variables that Control the Build .. toctree:: :maxdepth: 1 + /envvar/ADSP_ROOT /envvar/CMAKE_APPLE_SILICON_PROCESSOR /envvar/CMAKE_BUILD_PARALLEL_LEVEL /envvar/CMAKE_BUILD_TYPE + /envvar/CMAKE_COLOR_DIAGNOSTICS /envvar/CMAKE_CONFIGURATION_TYPES /envvar/CMAKE_CONFIG_TYPE /envvar/CMAKE_EXPORT_COMPILE_COMMANDS diff --git a/Help/manual/cmake-file-api.7.rst b/Help/manual/cmake-file-api.7.rst index 5e22ea9..4b8ac65 100644 --- a/Help/manual/cmake-file-api.7.rst +++ b/Help/manual/cmake-file-api.7.rst @@ -425,7 +425,7 @@ Version 1 does not exist to avoid confusion with that from { "kind": "codemodel", - "version": { "major": 2, "minor": 2 }, + "version": { "major": 2, "minor": 4 }, "paths": { "source": "/path/to/top-level-source-dir", "build": "/path/to/top-level-build-dir" @@ -758,6 +758,15 @@ with members: ``destination`` member is populated. This type has additional members ``runtimeDependencySetName`` and ``runtimeDependencySetType``. + ``fileSet`` + An :command:`install(TARGETS)` call with ``FILE_SET``. + The ``destination`` and ``paths`` members are populated. + The ``isOptional`` member may exist. + This type has additional members ``fileSetName``, ``fileSetType``, + ``fileSetDirectories``, and ``fileSetTarget``. + + This type was added in codemodel version 2.4. + ``isExcludeFromAll`` Optional member that is present with boolean value ``true`` when :command:`install` is called with the ``EXCLUDE_FROM_ALL`` option. @@ -835,6 +844,41 @@ with members: Indicates that this installer installs dependencies that are macOS frameworks. + ``fileSetName`` + Optional member that is present when ``type`` is ``fileSet``. The value is + a string with the name of the file set. + + This field was added in codemodel version 2.4. + + ``fileSetType`` + Optional member that is present when ``type`` is ``fileSet``. The value is + a string with the type of the file set. + + This field was added in codemodel version 2.4. + + ``fileSetDirectories`` + Optional member that is present when ``type`` is ``fileSet``. The value + is a list of strings with the file set's base directories (determined by + genex-evaluation of :prop_tgt:`HEADER_DIRS` or + :prop_tgt:`HEADER_DIRS_<NAME>`). + + This field was added in codemodel version 2.4. + + ``fileSetTarget`` + Optional member that is present when ``type`` is ``fileSet``. The value + is a JSON object with members: + + ``id`` + A string uniquely identifying the target. This matches + the ``id`` member of the target in the main "codemodel" + object's ``targets`` array. + + ``index`` + An unsigned integer 0-based index into the main "codemodel" + object's ``targets`` array for the target. + + This field was added in codemodel version 2.4. + ``scriptFile`` Optional member that is present when ``type`` is ``script``. The value is a string specifying the path to the script file on disk, diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index df13dd0..22c14df 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -599,7 +599,9 @@ String Transformations .. versionadded:: 3.15 - Removes duplicated items in the given ``list``. + Removes duplicated items in the given ``list``. The relative order of items + is preserved, but if duplicates are encountered, only the first instance is + preserved. .. genex:: $<FILTER:list,INCLUDE|EXCLUDE,regex> @@ -1019,8 +1021,19 @@ which is just the string ``tgt``. .. versionadded:: 3.9 - Full path to the bundle directory (``my.app``, ``my.framework``, or - ``my.bundle``) where ``tgt`` is the name of a target. + Full path to the bundle directory (``/path/to/my.app``, + ``/path/to/my.framework``, or ``/path/to/my.bundle``), + where ``tgt`` is the name of a target. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). + +.. genex:: $<TARGET_BUNDLE_DIR_NAME:tgt> + + .. versionadded:: 3.24 + + Name of the bundle directory (``my.app``, ``my.framework``, or + ``my.bundle``), where ``tgt`` is the name of a target. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). @@ -1030,10 +1043,11 @@ which is just the string ``tgt``. .. versionadded:: 3.9 Full path to the bundle content directory where ``tgt`` is the name of a - target. For the macOS SDK it leads to ``my.app/Contents``, ``my.framework``, - or ``my.bundle/Contents``. For all other SDKs (e.g. iOS) it leads to - ``my.app``, ``my.framework``, or ``my.bundle`` due to the flat bundle - structure. + target. For the macOS SDK it leads to ``/path/to/my.app/Contents``, + ``/path/to/my.framework``, or ``/path/to/my.bundle/Contents``. + For all other SDKs (e.g. iOS) it leads to ``/path/to/my.app``, + ``/path/to/my.framework``, or ``/path/to/my.bundle`` due to the flat + bundle structure. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). @@ -1057,10 +1071,10 @@ which is just the string ``tgt``. .. versionadded:: 3.21 List of DLLs that the target depends on at runtime. This is determined by - the locations of all the ``SHARED`` and ``MODULE`` targets in the target's - transitive dependencies. Using this generator expression on targets other - than executables, ``SHARED`` libraries, and ``MODULE`` libraries is an error. - On non-DLL platforms, it evaluates to an empty string. + the locations of all the ``SHARED`` targets in the target's transitive + dependencies. Using this generator expression on targets other than + executables, ``SHARED`` libraries, and ``MODULE`` libraries is an error. On + non-DLL platforms, it evaluates to an empty string. This generator expression can be used to copy all of the DLLs that a target depends on into its output directory in a ``POST_BUILD`` custom command. For @@ -1080,9 +1094,9 @@ which is just the string ``tgt``. .. note:: :ref:`Imported Targets` are supported only if they know the location - of their ``.dll`` files. An imported ``SHARED`` or ``MODULE`` library - must have :prop_tgt:`IMPORTED_LOCATION` set to its ``.dll`` file. See - the :ref:`add_library imported libraries <add_library imported libraries>` + of their ``.dll`` files. An imported ``SHARED`` library must have + :prop_tgt:`IMPORTED_LOCATION` set to its ``.dll`` file. See the + :ref:`add_library imported libraries <add_library imported libraries>` section for details. Many :ref:`Find Modules` produce imported targets with the ``UNKNOWN`` type and therefore will be ignored. @@ -1106,12 +1120,243 @@ Output-Related Expressions .. versionadded:: 3.1 - Content of ``...`` except when evaluated in a link interface while - propagating :ref:`Target Usage Requirements`, in which case it is the - empty string. - Intended for use only in an :prop_tgt:`INTERFACE_LINK_LIBRARIES` target - property, perhaps via the :command:`target_link_libraries` command, - to specify private link dependencies without other usage requirements. + Content of ``...``, except while collecting :ref:`Target Usage Requirements`, + in which case it is the empty string. This is intended for use in an + :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property, typically populated + via the :command:`target_link_libraries` command, to specify private link + dependencies without other usage requirements. + + .. versionadded:: 3.24 + ``LINK_ONLY`` may also be used in a :prop_tgt:`LINK_LIBRARIES` target + property. See policy :policy:`CMP0131`. + +.. genex:: $<LINK_LIBRARY:feature,library-list> + + .. versionadded:: 3.24 + + Manage how libraries are specified during the link step. + This expression may be used to specify how to link libraries in a target. + For example: + + .. code-block:: cmake + + add_library(lib1 STATIC ...) + add_library(lib2 ...) + target_link_libraries(lib2 PRIVATE "$<LINK_LIBRARY:load_archive,lib1>") + + This specify to use the ``lib1`` target with feature ``load_archive`` for + linking target ``lib2``. The feature must have be defined by + :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` variable or, if + :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` is false, + by :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variable. + + .. note:: + + The evaluation of this generator expression will use, for the following + variables, the values defined at the level of the creation of the target: + + * :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` + * :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` + * :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` + * :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` + + This expression can only be used to specify link libraries (i.e. part of + :command:`link_libraries` or :command:`target_link_libraries` commands and + :prop_tgt:`LINK_LIBRARIES` or :prop_tgt:`INTERFACE_LINK_LIBRARIES` target + properties). + + .. note:: + + If this expression appears in the :prop_tgt:`INTERFACE_LINK_LIBRARIES` + property of a target, it will be included in the imported target generated + by :command:`install(EXPORT)` command. It is the responsibility of the + environment consuming this import to define the link feature used by this + expression. + + The ``library-list`` argument can hold CMake targets or external libraries. + Any CMake target of type :ref:`OBJECT <Object Libraries>` or + :ref:`INTERFACE <Interface Libraries>` will be ignored by this expression and + will be handled in the standard way. + + Each target or external library involved in the link step must have only one + kind of feature (the absence of feature is also incompatible with any + feature). For example: + + .. code-block:: cmake + + add_library(lib1 ...) + + add_library(lib2 ...) + target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature1,lib1>") + + add_library(lib3 ...) + target_link_libraries(lib3 PRIVATE lib1 lib2) + # an error will be raised here because lib1 has two different features + + To resolve such incompatibilities, the :prop_tgt:`LINK_LIBRARY_OVERRIDE` + and :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties can be + used. + + .. note:: + + This expression does not guarantee that the list of specified libraries + will be kept grouped. So, to manage constructs like ``start-group`` and + ``end-group``, as supported by ``GNU ld``, the :genex:`LINK_GROUP` + generator expression can be used. + + CMake pre-defines some features of general interest: + + .. include:: ../variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt + +.. genex:: $<LINK_GROUP:feature,library-list> + + .. versionadded:: 3.24 + + Manage the grouping of libraries during the link step. + This expression may be used to specify how to kept groups of libraries during + the link of a target. + For example: + + .. code-block:: cmake + + add_library(lib1 STATIC ...) + add_library(lib2 ...) + target_link_libraries(lib2 PRIVATE "$<LINK_GROUP:cross_refs,lib1,external>") + + This specify to use the ``lib1`` target and ``external`` library with the + group feature ``cross_refs`` for linking target ``lib2``. The feature must + have be defined by :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` + variable or, if :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` + is false, by :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` variable. + + .. note:: + + The evaluation of this generator expression will use, for the following + variables, the values defined at the level of the creation of the target: + + * :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` + * :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` + * :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED` + * :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` + + This expression can only be used to specify link libraries (i.e. part of + :command:`link_libraries` or :command:`target_link_libraries` commands and + :prop_tgt:`LINK_LIBRARIES` or :prop_tgt:`INTERFACE_LINK_LIBRARIES` target + properties). + + .. note:: + + If this expression appears in the :prop_tgt:`INTERFACE_LINK_LIBRARIES` + property of a target, it will be included in the imported target generated + by :command:`install(EXPORT)` command. It is the responsibility of the + environment consuming this import to define the link feature used by this + expression. + + The ``library-list`` argument can hold CMake targets or external libraries. + Any CMake target of type :ref:`OBJECT <Object Libraries>` or + :ref:`INTERFACE <Interface Libraries>` will be ignored by this expression and + will be handled in the standard way. + + .. note:: + + This expression is compatible with the :genex:`LINK_LIBRARY` generator + expression. The libraries involved in a group can be specified using the + :genex:`LINK_LIBRARY` generator expression. + + Each target or external library involved in the link step can be part of + different groups as far as these groups use the same feature, so mixing + different group features for the same target or library is forbidden. The + different groups will be part of the link step. + + .. code-block:: cmake + + add_library(lib1 ...) + add_library(lib2 ...) + + add_library(lib3 ...) + target_link_libraries(lib3 PUBLIC "$<LINK_GROUP:feature1,lib1,lib2>") + + add_library(lib4 ...) + target_link_libraries(lib4 PRIVATE "$<LINK_GROUP:feature1,lib1,lib3>") + # lib4 will be linked with the groups {lib1,lib2} and {lib1,lib3} + + add_library(lib5 ...) + target_link_libraries(lib5 PRIVATE "$<LINK_GROUP:feature2,lib1,lib3>") + # an error will be raised here because lib1 is part of two groups with + # different features + + When a target or an external library is involved in the link step as part of + a group and also as standalone, any occurrence of the standalone link item + will be replaced by the group or groups it belong to. + + .. code-block:: cmake + + add_library(lib1 ...) + add_library(lib2 ...) + + add_library(lib3 ...) + target_link_libraries(lib3 PUBLIC lib1) + + add_library(lib4 ...) + target_link_libraries(lib4 PRIVATE lib3 "$<LINK_GROUP:feature1,lib1,lib2>") + # lib4 will only be linked with lib3 and the group {lib1,lib2} + + This example will be "re-written" by CMake in the following form: + + .. code-block:: cmake + + add_library(lib1 ...) + add_library(lib2 ...) + + add_library(lib3 ...) + target_link_libraries(lib3 PUBLIC "$<LINK_GROUP:feature1,lib1,lib2>") + + add_library(lib4 ...) + target_link_libraries(lib4 PRIVATE lib3 "$<LINK_GROUP:feature1,lib1,lib2>") + # lib4 will only be linked with lib3 and the group {lib1,lib2} + + Be aware that the precedence of the group over the standalone link item can + result in some circular dependency between groups, which will raise an + error because circular dependencies are not allowed for groups. + + .. code-block:: cmake + + add_library(lib1A ...) + add_library(lib1B ...) + + add_library(lib2A ...) + add_library(lib2B ...) + + target_link_libraries(lib1A PUBLIC lib2A) + target_link_libraries(lib2B PUBLIC lib1B) + + add_library(lib ...) + target_link_libraries(lib3 PRIVATE "$<LINK_GROUP:feat,lib1A,lib1B>" + "$<LINK_GROUP:feat,lib2A,lib2B>") + + This example will be "re-written" by CMake in the following form: + + .. code-block:: cmake + + add_library(lib1A ...) + add_library(lib1B ...) + + add_library(lib2A ...) + add_library(lib2B ...) + + target_link_libraries(lib1A PUBLIC "$<LINK_GROUP:feat,lib2A,lib2B>") + target_link_libraries(lib2B PUBLIC "$<LINK_GROUP:feat,lib1A,lib1B>") + + add_library(lib ...) + target_link_libraries(lib3 PRIVATE "$<LINK_GROUP:feat,lib1A,lib1B>" + "$<LINK_GROUP:feat,lib2A,lib2B>") + + So, we have a circular dependency between groups ``{lib1A,lib1B}`` and + ``{lib2A,lib2B}``. + + CMake pre-defines some features of general interest: + + .. include:: ../variable/LINK_GROUP_PREDEFINED_FEATURES.txt .. genex:: $<INSTALL_INTERFACE:...> diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index 663b18d..034e218 100644 --- a/Help/manual/cmake-generators.7.rst +++ b/Help/manual/cmake-generators.7.rst @@ -102,6 +102,8 @@ Other Generators /generator/Green Hills MULTI /generator/Xcode +.. _`Extra Generators`: + Extra Generators ================ diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index b7f0861..02cfa7e 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -582,7 +582,8 @@ Scope They are never cached. References - `Variable References`_ have the form ``$ENV{<variable>}``. + `Variable References`_ have the form ``$ENV{<variable>}``, using the + :variable:`ENV` operator. Initialization Initial values of the CMake environment variables are those of @@ -594,6 +595,13 @@ Initialization Changed values are not written back to the calling process, and they are not seen by subsequent build or test processes. + See the :ref:`cmake -E env <Run a Command-Line Tool>` command-line + tool to run a command in a modified environment. + +Inspection + See the :ref:`cmake -E environment <Run a Command-Line Tool>` command-line + tool to display all current environment variables. + The :manual:`cmake-env-variables(7)` manual documents environment variables that have special meaning to CMake. @@ -627,3 +635,45 @@ in list elements, thus flattening nested lists: .. code-block:: cmake set(x a "b;c") # sets "x" to "a;b;c", not "a;b\;c" + +In general, lists do not support elements containing ``;`` characters. +To avoid problems, consider the following advice: + +* The interfaces of many CMake commands, variables, and properties accept + semicolon-separated lists. Avoid passing lists with elements containing + semicolons to these interfaces unless they document either direct support + or some way to escape or encode semicolons. + +* When constructing a list, substitute an otherwise-unused placeholder + for ``;`` in elements when. Then substitute ``;`` for the placeholder + when processing list elements. + For example, the following code uses ``|`` in place of ``;`` characters: + + .. code-block:: cmake + + set(mylist a "b|c") + foreach(entry IN LISTS mylist) + string(REPLACE "|" ";" entry "${entry}") + # use "${entry}" normally + endforeach() + + The :module:`ExternalProject` module's ``LIST_SEPARATOR`` option is an + example of an interface built using this approach. + +* In lists of :manual:`generator expressions <cmake-generator-expressions(7)>`, + use the :genex:`$<SEMICOLON>` generator expression. + +* In command calls, use `Quoted Argument`_ syntax whenever possible. + The called command will receive the content of the argument with + semicolons preserved. An `Unquoted Argument`_ will be split on + semicolons. + +* In :command:`function` implementations, avoid ``ARGV`` and ``ARGN``, + which do not distinguish semicolons in values from those separating values. + Instead, prefer using named positional arguments and the ``ARGC`` and + ``ARGV#`` variables. + When using :command:`cmake_parse_arguments` to parse arguments, prefer + its ``PARSE_ARGV`` signature, which uses the ``ARGV#`` variables. + + Note that this approach does not apply to :command:`macro` implementations + because they reference arguments using placeholders, not real variables. diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 141eeaa..93beea9 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -317,7 +317,6 @@ used directly. /module/CPackFreeBSD /module/CPackNSIS /module/CPackNuGet - /module/CPackPackageMaker /module/CPackProductBuild /module/CPackRPM /module/CPackWIX diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst index 5c109ff..ed85dc4 100644 --- a/Help/manual/cmake-packages.7.rst +++ b/Help/manual/cmake-packages.7.rst @@ -446,10 +446,10 @@ be true. This can be tested with logic in the package configuration file: include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake") include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsMacros.cmake") - set(_supported_components Plot Table) + set(_ClimbingStats_supported_components Plot Table) foreach(_comp ${ClimbingStats_FIND_COMPONENTS}) - if (NOT ";${_supported_components};" MATCHES ";${_comp};") + if (NOT ";${_ClimbingStats_supported_components};" MATCHES ";${_comp};") set(ClimbingStats_FOUND False) set(ClimbingStats_NOT_FOUND_MESSAGE "Unsupported component: ${_comp}") endif() diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 3df4f9f..788d086 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,30 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used to determine whether to report an error on use of deprecated macros or functions. + +Policies Introduced by CMake 3.24 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0137: try_compile() passes platform variables in project mode. </policy/CMP0137> + CMP0136: Watcom runtime library flags are selected by an abstraction. </policy/CMP0136> + CMP0135: ExternalProject ignores timestamps in archives by default for the URL download method. </policy/CMP0135> + CMP0134: Fallback to \"HOST\" Windows registry view when \"TARGET\" view is not usable. </policy/CMP0134> + CMP0133: The CPack module disables SLA by default in the CPack DragNDrop Generator. </policy/CMP0133> + CMP0132: Do not set compiler environment variables on first run. </policy/CMP0132> + CMP0131: LINK_LIBRARIES supports the LINK_ONLY generator expression. </policy/CMP0131> + CMP0130: while() diagnoses condition evaluation errors. </policy/CMP0130> + +Policies Introduced by CMake 3.23 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0129: Compiler id for MCST LCC compilers is now LCC, not GNU. </policy/CMP0129> + Policies Introduced by CMake 3.22 ================================= diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst index 74e9fae..948d87a 100644 --- a/Help/manual/cmake-presets.7.rst +++ b/Help/manual/cmake-presets.7.rst @@ -12,18 +12,21 @@ Introduction One problem that CMake users often face is sharing settings with other people for common ways to configure a project. This may be done to support CI builds, -or for users who frequently use the same build. CMake supports two files, +or for users who frequently use the same build. CMake supports two main files, ``CMakePresets.json`` and ``CMakeUserPresets.json``, that allow users to -specify common configure options and share them with others. +specify common configure options and share them with others. CMake also +supports files included with the ``include`` field. ``CMakePresets.json`` and ``CMakeUserPresets.json`` live in the project's root directory. They both have exactly the same format, and both are optional -(though at least one must be present if ``--preset`` is specified.) -``CMakePresets.json`` is meant to save project-wide builds, while -``CMakeUserPresets.json`` is meant for developers to save their own local -builds. ``CMakePresets.json`` may be checked into a version control system, and -``CMakeUserPresets.json`` should NOT be checked in. For example, if a project -is using Git, ``CMakePresets.json`` may be tracked, and +(though at least one must be present if ``--preset`` is specified). +``CMakePresets.json`` is meant to specify project-wide build details, while +``CMakeUserPresets.json`` is meant for developers to specify their own local +build details. + +``CMakePresets.json`` may be checked into a version control system, and +``CMakeUserPresets.json`` should NOT be checked in. For example, if a +project is using Git, ``CMakePresets.json`` may be tracked, and ``CMakeUserPresets.json`` should be added to the ``.gitignore``. Format @@ -39,7 +42,7 @@ The root object recognizes the following fields: ``version`` A required integer representing the version of the JSON schema. - The supported versions are ``1``, ``2``, and ``3``. + The supported versions are ``1``, ``2``, ``3``, ``4``, and ``5``. ``cmakeMinimumRequired`` @@ -58,6 +61,13 @@ The root object recognizes the following fields: An optional integer representing the patch version. +``include`` + + An optional array of strings representing files to include. If the filenames + are not absolute, they are considered relative to the current file. + This is allowed in preset files specifying version ``4`` or above. + See `Includes`_ for discussion of the constraints on included files. + ``vendor`` An optional map containing vendor-specific information. CMake does not @@ -82,6 +92,26 @@ The root object recognizes the following fields: An optional array of `Test Preset`_ objects. This is allowed in preset files specifying version ``2`` or above. +Includes +^^^^^^^^ + +``CMakePresets.json`` and ``CMakeUserPresets.json`` can include other files +with the ``include`` field in file version ``4`` and later. Files included +by these files can also include other files. If ``CMakePresets.json`` and +``CMakeUserPresets.json`` are both present, ``CMakeUserPresets.json`` +implicitly includes ``CMakePresets.json``, even with no ``include`` field, +in all versions of the format. + +If a preset file contains presets that inherit from presets in another file, +the file must include the other file either directly or indirectly. +Include cycles are not allowed among files. If ``a.json`` includes +``b.json``, ``b.json`` cannot include ``a.json``. However, a file may be +included multiple times from the same file or from different files. + +Files directly or indirectly included from ``CMakePresets.json`` should be +guaranteed to be provided by the project. ``CMakeUserPresets.json`` may +include files from anywhere. + Configure Preset ^^^^^^^^^^^^^^^^ @@ -108,16 +138,20 @@ that may contain the following fields: ``inherits`` An optional array of strings representing the names of presets to inherit - from. The preset will inherit all of the fields from the ``inherits`` + from. This field can also be a string, which is equivalent to an array + containing one string. + + The preset will inherit all of the fields from the ``inherits`` presets by default (except ``name``, ``hidden``, ``inherits``, ``description``, and ``displayName``), but can override them as desired. If multiple ``inherits`` presets provide conflicting values for the same field, the earlier preset in the ``inherits`` list will be - preferred. Presets in ``CMakePresets.json`` may not inherit from presets - in ``CMakeUserPresets.json``. + preferred. - This field can also be a string, which is equivalent to an array - containing one string. + A preset can only inherit from another preset that is defined in the + same file or in one of the files it includes (directly or indirectly). + Presets in ``CMakePresets.json`` may not inherit from presets in + ``CMakeUserPresets.json``. ``condition`` @@ -350,17 +384,21 @@ that may contain the following fields: ``inherits`` - An optional array of strings representing the names of presets to - inherit from. The preset will inherit all of the fields from the + An optional array of strings representing the names of presets to inherit + from. This field can also be a string, which is equivalent to an array + containing one string. + + The preset will inherit all of the fields from the ``inherits`` presets by default (except ``name``, ``hidden``, ``inherits``, ``description``, and ``displayName``), but can override them as desired. If multiple ``inherits`` presets provide conflicting values for the same field, the earlier preset in the ``inherits`` list - will be preferred. Presets in ``CMakePresets.json`` may not inherit from - presets in ``CMakeUserPresets.json``. + will be preferred. - This field can also be a string, which is equivalent to an array - containing one string. + A preset can only inherit from another preset that is defined in the + same file or in one of the files it includes (directly or indirectly). + Presets in ``CMakePresets.json`` may not inherit from presets in + ``CMakeUserPresets.json``. ``condition`` @@ -453,6 +491,42 @@ that may contain the following fields: An optional bool. If true, equivalent to passing ``--clean-first`` on the command line. +``resolvePackageReferences`` + + An optional string that specifies the package resolve mode. This is + allowed in preset files specifying version ``4`` or above. + + Package references are used to define dependencies to packages from + external package managers. Currently only NuGet in combination with the + Visual Studio generator is supported. If there are no targets that define + package references, this option does nothing. Valid values are: + + ``on`` + + Causes package references to be resolved before attempting a build. + + ``off`` + + Package references will not be resolved. Note that this may cause + errors in some build environments, such as .NET SDK style projects. + + ``only`` + + Only resolve package references, but do not perform a build. + + .. note:: + + The command line parameter ``--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 performed. + + When using the Visual Studio generator, package references are defined + using the :prop_tgt:`VS_PACKAGE_REFERENCES` property. Package references + are restored using NuGet. It can be disabled by setting the + ``CMAKE_VS_NUGET_PACKAGE_RESTORE`` variable to ``OFF``. This can also be + done from within a configure preset. + ``verbose`` An optional bool. If true, equivalent to passing ``--verbose`` on the @@ -487,17 +561,21 @@ that may contain the following fields: ``inherits`` - An optional array of strings representing the names of presets to - inherit from. The preset will inherit all of the fields from the + An optional array of strings representing the names of presets to inherit + from. This field can also be a string, which is equivalent to an array + containing one string. + + The preset will inherit all of the fields from the ``inherits`` presets by default (except ``name``, ``hidden``, ``inherits``, ``description``, and ``displayName``), but can override them as desired. If multiple ``inherits`` presets provide conflicting values for the same field, the earlier preset in the ``inherits`` list - will be preferred. Presets in ``CMakePresets.json`` may not inherit from - presets in ``CMakeUserPresets.json``. + will be preferred. - This field can also be a string, which is equivalent to an array - containing one string. + A preset can only inherit from another preset that is defined in the + same file or in one of the files it includes (directly or indirectly). + Presets in ``CMakePresets.json`` may not inherit from presets in + ``CMakeUserPresets.json``. ``condition`` @@ -637,6 +715,12 @@ that may contain the following fields: bytes. Equivalent to passing ``--test-output-size-failed`` on the command line. + ``testOutputTruncation`` + + An optional string specifying the test output truncation mode. Equivalent + to passing ``--test-output-truncation`` on the command line." + This is allowed in preset files specifying version ``5`` or above. + ``maxTestNameWidth`` An optional integer specifying the maximum width of a test name to @@ -947,7 +1031,8 @@ Recognized macros include: ``${sourceDir}`` - Path to the project source directory. + Path to the project source directory (i.e. the same as + :variable:`CMAKE_SOURCE_DIR`). ``${sourceParentDir}`` @@ -974,10 +1059,26 @@ Recognized macros include: :variable:`CMAKE_HOST_SYSTEM_NAME`. This is allowed in preset files specifying version ``3`` or above. +``${fileDir}`` + + Path to the directory containing the preset file which contains the macro. + This is allowed in preset files specifying version ``4`` or above. + ``${dollar}`` A literal dollar sign (``$``). +``${pathListSep}`` + + Native character for separating lists of paths, such as ``:`` or ``;``. + + For example, by setting ``PATH`` to + ``/path/to/ninja/bin${pathListSep}$env{PATH}``, ``${pathListSep}`` will + expand to the underlying operating system's character used for + concatenation in ``PATH``. + + This is allowed in preset files specifying version ``5`` or above. + ``$env{<variable-name>}`` Environment variable with name ``<variable-name>``. The variable name may diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index bb5dba3..7935ca3 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -171,6 +171,7 @@ Properties on Targets /prop_tgt/COMPILE_PDB_NAME_CONFIG /prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY /prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG + /prop_tgt/COMPILE_WARNING_AS_ERROR /prop_tgt/CONFIG_OUTPUT_NAME /prop_tgt/CONFIG_POSTFIX /prop_tgt/CROSSCOMPILING_EMULATOR @@ -191,6 +192,7 @@ Properties on Targets /prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY /prop_tgt/DEPRECATION /prop_tgt/DISABLE_PRECOMPILE_HEADERS + /prop_tgt/DOTNET_SDK /prop_tgt/DOTNET_TARGET_FRAMEWORK /prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION /prop_tgt/EchoString @@ -214,6 +216,11 @@ Properties on Targets /prop_tgt/GHS_NO_SOURCE_GROUP_FILE /prop_tgt/GNUtoMS /prop_tgt/HAS_CXX + /prop_tgt/HEADER_DIRS + /prop_tgt/HEADER_DIRS_NAME + /prop_tgt/HEADER_SET + /prop_tgt/HEADER_SET_NAME + /prop_tgt/HEADER_SETS /prop_tgt/HIP_ARCHITECTURES /prop_tgt/HIP_EXTENSIONS /prop_tgt/HIP_STANDARD @@ -239,6 +246,7 @@ Properties on Targets /prop_tgt/IMPORTED_LOCATION_CONFIG /prop_tgt/IMPORTED_NO_SONAME /prop_tgt/IMPORTED_NO_SONAME_CONFIG + /prop_tgt/IMPORTED_NO_SYSTEM /prop_tgt/IMPORTED_OBJECTS /prop_tgt/IMPORTED_OBJECTS_CONFIG /prop_tgt/IMPORTED_SONAME @@ -254,10 +262,13 @@ Properties on Targets /prop_tgt/INTERFACE_COMPILE_DEFINITIONS /prop_tgt/INTERFACE_COMPILE_FEATURES /prop_tgt/INTERFACE_COMPILE_OPTIONS + /prop_tgt/INTERFACE_HEADER_SETS /prop_tgt/INTERFACE_INCLUDE_DIRECTORIES /prop_tgt/INTERFACE_LINK_DEPENDS /prop_tgt/INTERFACE_LINK_DIRECTORIES /prop_tgt/INTERFACE_LINK_LIBRARIES + /prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT + /prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE /prop_tgt/INTERFACE_LINK_OPTIONS /prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE /prop_tgt/INTERFACE_PRECOMPILE_HEADERS @@ -297,6 +308,9 @@ Properties on Targets /prop_tgt/LINK_INTERFACE_MULTIPLICITY /prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG /prop_tgt/LINK_LIBRARIES + /prop_tgt/LINK_LIBRARIES_ONLY_TARGETS + /prop_tgt/LINK_LIBRARY_OVERRIDE + /prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY /prop_tgt/LINK_OPTIONS /prop_tgt/LINK_SEARCH_END_STATIC /prop_tgt/LINK_SEARCH_START_STATIC @@ -367,6 +381,7 @@ Properties on Targets /prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE /prop_tgt/UNITY_BUILD_MODE /prop_tgt/UNITY_BUILD_UNIQUE_ID + /prop_tgt/VERIFY_INTERFACE_HEADER_SETS /prop_tgt/VERSION /prop_tgt/VISIBILITY_INLINES_HIDDEN /prop_tgt/VS_CONFIGURATION_TYPE @@ -380,6 +395,7 @@ Properties on Targets /prop_tgt/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname /prop_tgt/VS_DOTNET_REFERENCES /prop_tgt/VS_DOTNET_REFERENCES_COPY_LOCAL + /prop_tgt/VS_DOTNET_STARTUP_OBJECT /prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION /prop_tgt/VS_DPI_AWARE /prop_tgt/VS_GLOBAL_KEYWORD @@ -391,6 +407,7 @@ Properties on Targets /prop_tgt/VS_JUST_MY_CODE_DEBUGGING /prop_tgt/VS_KEYWORD /prop_tgt/VS_MOBILE_EXTENSIONS_VERSION + /prop_tgt/VS_NO_COMPILE_BATCHING /prop_tgt/VS_NO_SOLUTION_DEPLOY /prop_tgt/VS_PACKAGE_REFERENCES /prop_tgt/VS_PLATFORM_TOOLSET @@ -407,6 +424,7 @@ Properties on Targets /prop_tgt/VS_WINRT_COMPONENT /prop_tgt/VS_WINRT_EXTENSIONS /prop_tgt/VS_WINRT_REFERENCES + /prop_tgt/WATCOM_RUNTIME_LIBRARY /prop_tgt/WIN32_EXECUTABLE /prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS /prop_tgt/XCODE_ATTRIBUTE_an-attribute @@ -425,6 +443,7 @@ Properties on Targets /prop_tgt/XCODE_SCHEME_ARGUMENTS /prop_tgt/XCODE_SCHEME_DEBUG_AS_ROOT /prop_tgt/XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING + /prop_tgt/XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE /prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER /prop_tgt/XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS /prop_tgt/XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE @@ -441,6 +460,7 @@ Properties on Targets /prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP /prop_tgt/XCODE_SCHEME_WORKING_DIRECTORY /prop_tgt/XCODE_SCHEME_ZOMBIE_OBJECTS + /prop_tgt/XCODE_XCCONFIG /prop_tgt/XCTEST .. _`Test Properties`: diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst index a941310..e194df0 100644 --- a/Help/manual/cmake-toolchains.7.rst +++ b/Help/manual/cmake-toolchains.7.rst @@ -301,6 +301,28 @@ Windows Store may look like this: set(CMAKE_SYSTEM_NAME WindowsStore) set(CMAKE_SYSTEM_VERSION 8.1) +.. _`Cross Compiling for ADSP SHARC/Blackfin`: + +Cross Compiling for ADSP SHARC/Blackfin +--------------------------------------- + +Cross-compiling for ADSP SHARC or Blackfin can be configured +by setting the :variable:`CMAKE_SYSTEM_NAME` variable to ``ADSP`` +and the :variable:`CMAKE_SYSTEM_PROCESSOR` variable +to the "part number", excluding the ``ADSP-`` prefix, +for example, ``21594``, ``SC589``, etc. +This value is case insensitive. + +CMake will automatically search for CCES or VDSP++ installs +in their default install locations +and select the most recent version found. +CCES will be selected over VDSP++ if both are installed. +Custom install paths can be set via the :variable:`CMAKE_ADSP_ROOT` variable +or the :envvar:`ADSP_ROOT` environment variable. + +The compiler (``cc21k`` vs. ``ccblkfn``) is selected automatically +based on the :variable:`CMAKE_SYSTEM_PROCESSOR` value provided. + .. _`Cross Compiling for Android`: Cross Compiling for Android diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 4ed0b2e..9fbb146 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -49,6 +49,7 @@ Variables that Provide Information /variable/CMAKE_DEBUG_TARGET_PROPERTIES /variable/CMAKE_DIRECTORY_LABELS /variable/CMAKE_DL_LIBS + /variable/CMAKE_DOTNET_SDK /variable/CMAKE_DOTNET_TARGET_FRAMEWORK /variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION /variable/CMAKE_EDIT_COMMAND @@ -58,6 +59,7 @@ Variables that Provide Information /variable/CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES /variable/CMAKE_FIND_DEBUG_MODE /variable/CMAKE_FIND_PACKAGE_NAME + /variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR /variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION /variable/CMAKE_FIND_PACKAGE_SORT_ORDER /variable/CMAKE_GENERATOR @@ -118,6 +120,7 @@ Variables that Provide Information /variable/CMAKE_VS_DEVENV_COMMAND /variable/CMAKE_VS_MSBUILD_COMMAND /variable/CMAKE_VS_NsightTegra_VERSION + /variable/CMAKE_VS_NUGET_PACKAGE_RESTORE /variable/CMAKE_VS_PLATFORM_NAME /variable/CMAKE_VS_PLATFORM_NAME_DEFAULT /variable/CMAKE_VS_PLATFORM_TOOLSET @@ -170,6 +173,7 @@ Variables that Change Behavior /variable/CMAKE_CODEBLOCKS_COMPILER_ID /variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES /variable/CMAKE_CODELITE_USE_TARGETS + /variable/CMAKE_COLOR_DIAGNOSTICS /variable/CMAKE_COLOR_MAKEFILE /variable/CMAKE_CONFIGURATION_TYPES /variable/CMAKE_DEPENDS_IN_PROJECT_ONLY @@ -195,6 +199,7 @@ Variables that Change Behavior /variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY /variable/CMAKE_FIND_PACKAGE_PREFER_CONFIG /variable/CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS + /variable/CMAKE_FIND_PACKAGE_TARGETS_GLOBAL /variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE /variable/CMAKE_FIND_ROOT_PATH /variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE @@ -202,6 +207,7 @@ Variables that Change Behavior /variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE /variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM /variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH + /variable/CMAKE_FIND_USE_INSTALL_PREFIX /variable/CMAKE_FIND_USE_CMAKE_PATH /variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH /variable/CMAKE_FIND_USE_PACKAGE_REGISTRY @@ -210,6 +216,7 @@ Variables that Change Behavior /variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY /variable/CMAKE_FRAMEWORK_PATH /variable/CMAKE_IGNORE_PATH + /variable/CMAKE_IGNORE_PREFIX_PATH /variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE /variable/CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE /variable/CMAKE_INCLUDE_PATH @@ -220,6 +227,7 @@ Variables that Change Behavior /variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT /variable/CMAKE_LIBRARY_PATH /variable/CMAKE_LINK_DIRECTORIES_BEFORE + /variable/CMAKE_LINK_LIBRARIES_ONLY_TARGETS /variable/CMAKE_MFC_FLAG /variable/CMAKE_MAXIMUM_RECURSION_DEPTH /variable/CMAKE_MESSAGE_CONTEXT @@ -235,6 +243,7 @@ Variables that Change Behavior /variable/CMAKE_PROJECT_INCLUDE_BEFORE /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE + /variable/CMAKE_PROJECT_TOP_LEVEL_INCLUDES /variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY /variable/CMAKE_STAGING_PREFIX @@ -247,6 +256,7 @@ Variables that Change Behavior /variable/CMAKE_SYSTEM_APPBUNDLE_PATH /variable/CMAKE_SYSTEM_FRAMEWORK_PATH /variable/CMAKE_SYSTEM_IGNORE_PATH + /variable/CMAKE_SYSTEM_IGNORE_PREFIX_PATH /variable/CMAKE_SYSTEM_INCLUDE_PATH /variable/CMAKE_SYSTEM_LIBRARY_PATH /variable/CMAKE_SYSTEM_PREFIX_PATH @@ -262,6 +272,7 @@ Variables that Change Behavior /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN /variable/CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING + /variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE /variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE @@ -277,6 +288,7 @@ Variables that Change Behavior /variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP /variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY /variable/CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS + /variable/CMAKE_XCODE_XCCONFIG /variable/PackageName_ROOT Variables that Describe the System @@ -307,7 +319,7 @@ Variables that Describe the System /variable/CMAKE_SYSTEM_PROCESSOR /variable/CMAKE_SYSTEM_VERSION /variable/CYGWIN - /variable/GHS-MULTI + /variable/GHSMULTI /variable/IOS /variable/MINGW /variable/MSVC @@ -338,6 +350,7 @@ Variables that Control the Build .. toctree:: :maxdepth: 1 + /variable/CMAKE_ADSP_ROOT /variable/CMAKE_AIX_EXPORT_ALL_SYMBOLS /variable/CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS /variable/CMAKE_ANDROID_API @@ -389,6 +402,7 @@ Variables that Control the Build /variable/CMAKE_BUILD_WITH_INSTALL_RPATH /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG + /variable/CMAKE_COMPILE_WARNING_AS_ERROR /variable/CMAKE_CONFIG_POSTFIX /variable/CMAKE_CROSS_CONFIGS /variable/CMAKE_CTEST_ARGUMENTS @@ -431,7 +445,11 @@ Variables that Control the Build /variable/CMAKE_LANG_CPPCHECK /variable/CMAKE_LANG_CPPLINT /variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE + /variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE + /variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE_SUPPORTED /variable/CMAKE_LANG_LINKER_LAUNCHER + /variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE + /variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE_SUPPORTED /variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LANG_LINK_LIBRARY_FLAG /variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG @@ -441,9 +459,13 @@ Variables that Control the Build /variable/CMAKE_LIBRARY_PATH_FLAG /variable/CMAKE_LINK_DEF_FILE_FLAG /variable/CMAKE_LINK_DEPENDS_NO_SHARED + /variable/CMAKE_LINK_GROUP_USING_FEATURE + /variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED /variable/CMAKE_LINK_INTERFACE_LIBRARIES /variable/CMAKE_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LINK_LIBRARY_FLAG + /variable/CMAKE_LINK_LIBRARY_USING_FEATURE + /variable/CMAKE_LINK_LIBRARY_USING_FEATURE_SUPPORTED /variable/CMAKE_LINK_WHAT_YOU_USE /variable/CMAKE_LINK_WHAT_YOU_USE_CHECK /variable/CMAKE_MACOSX_BUNDLE @@ -466,6 +488,7 @@ Variables that Control the Build /variable/CMAKE_PCH_INSTANTIATE_TEMPLATES /variable/CMAKE_PDB_OUTPUT_DIRECTORY /variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG + /variable/CMAKE_PLATFORM_NO_VERSIONED_SONAME /variable/CMAKE_POSITION_INDEPENDENT_CODE /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG @@ -480,12 +503,14 @@ Variables that Control the Build /variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_STATIC_LINKER_FLAGS_INIT /variable/CMAKE_TRY_COMPILE_CONFIGURATION + /variable/CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES /variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES /variable/CMAKE_TRY_COMPILE_TARGET_TYPE /variable/CMAKE_UNITY_BUILD /variable/CMAKE_UNITY_BUILD_BATCH_SIZE /variable/CMAKE_UNITY_BUILD_UNIQUE_ID /variable/CMAKE_USE_RELATIVE_PATHS + /variable/CMAKE_VERIFY_INTERFACE_HEADER_SETS /variable/CMAKE_VISIBILITY_INLINES_HIDDEN /variable/CMAKE_VS_GLOBALS /variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD @@ -499,6 +524,7 @@ Variables that Control the Build /variable/CMAKE_VS_SDK_REFERENCE_DIRECTORIES /variable/CMAKE_VS_SDK_SOURCE_DIRECTORIES /variable/CMAKE_VS_WINRT_BY_DEFAULT + /variable/CMAKE_WATCOM_RUNTIME_LIBRARY /variable/CMAKE_WIN32_EXECUTABLE /variable/CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS /variable/CMAKE_XCODE_ATTRIBUTE_an-attribute @@ -578,8 +604,6 @@ Variables for Languages /variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES /variable/CMAKE_LANG_LIBRARY_ARCHITECTURE /variable/CMAKE_LANG_LINK_EXECUTABLE - /variable/CMAKE_LANG_LINKER_PREFERENCE - /variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES /variable/CMAKE_LANG_LINKER_WRAPPER_FLAG /variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP /variable/CMAKE_LANG_OUTPUT_EXTENSION @@ -628,6 +652,7 @@ Variables for CTest /variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS /variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS /variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE + /variable/CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION /variable/CTEST_CUSTOM_MEMCHECK_IGNORE /variable/CTEST_CUSTOM_POST_MEMCHECK /variable/CTEST_CUSTOM_POST_TEST @@ -668,6 +693,7 @@ Variables for CTest /variable/CTEST_SCP_COMMAND /variable/CTEST_SCRIPT_DIRECTORY /variable/CTEST_SITE + /variable/CTEST_SUBMIT_INACTIVITY_TIMEOUT /variable/CTEST_SUBMIT_URL /variable/CTEST_SOURCE_DIRECTORY /variable/CTEST_SVN_COMMAND @@ -723,6 +749,8 @@ are subject to change, and not recommended for use in project code. /variable/CMAKE_LANG_COMPILER_ABI /variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID /variable/CMAKE_LANG_COMPILER_VERSION_INTERNAL + /variable/CMAKE_LANG_LINKER_PREFERENCE + /variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES /variable/CMAKE_LANG_PLATFORM_ID /variable/CMAKE_NOT_USING_CONFIG_FLAGS /variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index e23ddd8..38105dd 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -151,6 +151,33 @@ source and build trees and generate a buildsystem: In all cases the ``<options>`` may be zero or more of the `Options`_ below. +The above styles for specifying the source and build trees may be mixed. +Paths specified with ``-S`` or ``-B`` are always classified as source or +build trees, respectively. Paths specified with plain arguments are +classified based on their content and the types of paths given earlier. +If only one type of path is given, the current working directory (cwd) +is used for the other. For example: + +============================== ============ =========== + Command Line Source Dir Build Dir +============================== ============ =========== + ``cmake src`` ``src`` `cwd` + ``cmake build`` (existing) `loaded` ``build`` + ``cmake -S src`` ``src`` `cwd` + ``cmake -S src build`` ``src`` ``build`` + ``cmake -S src -B build`` ``src`` ``build`` + ``cmake -B build`` `cwd` ``build`` + ``cmake -B build src`` ``src`` ``build`` + ``cmake -B build -S src`` ``src`` ``build`` +============================== ============ =========== + +.. versionchanged:: 3.23 + + CMake warns when multiple source paths are specified. This has never + been officially documented or supported, but older versions accidentally + accepted multiple source paths and used the last path specified. + Avoid passing multiple source path arguments. + After generating a buildsystem one may use the corresponding native build tool to build the project. For example, after using the :generator:`Unix Makefiles` generator one may run ``make`` directly: @@ -170,6 +197,13 @@ Options .. include:: OPTIONS_BUILD.txt +``--fresh`` + .. versionadded:: 3.24 + + Perform a fresh configuration of the build tree. + This removes any existing ``CMakeCache.txt`` file and associated + ``CMakeFiles/`` directory, and recreates them from scratch. + ``-L[A][H]`` List non-advanced cached variables. @@ -250,6 +284,21 @@ Options See also the :variable:`CMAKE_FIND_DEBUG_MODE` variable for debugging a more local part of the project. +``--debug-find-pkg=<pkg>[,...]`` + Put cmake find commands in a debug mode when running under calls + to :command:`find_package(\<pkg\>) <find_package>`, where ``<pkg>`` + is an entry in the given comma-separated list of case-sensitive package + names. + + Like ``--debug-find``, but limiting scope to the specified packages. + +``--debug-find-var=<var>[,...]`` + Put cmake find commands in a debug mode when called with ``<var>`` + as the result variable, where ``<var>`` is an entry in the given + comma-separated list. + + Like ``--debug-find``, but limiting scope to the specified variable names. + ``--trace`` Put cmake in trace mode. @@ -284,7 +333,8 @@ Options "cmd": "add_executable", "args": ["foo", "bar"], "time": 1579512535.9687231, - "frame": 2 + "frame": 2, + "global_frame": 4 } The members are: @@ -294,7 +344,13 @@ Options was called. ``line`` - The line in ``file`` of the function call. + The line in ``file`` where the function call begins. + + ``line_end`` + If the function call spans multiple lines, this field will + be set to the line where the function call ends. If the function + calls spans a single line, this field will be unset. This field + was added in minor version 2 of the ``json-v1`` format. ``defer`` Optional member that is present when the function call was deferred @@ -311,7 +367,13 @@ Options Timestamp (seconds since epoch) of the function call. ``frame`` - Stack frame depth of the function that was called. + Stack frame depth of the function that was called, within the + context of the ``CMakeLists.txt`` being processed currently. + + ``global_frame`` + Stack frame depth of the function that was called, tracked globally + across all ``CMakeLists.txt`` files involved in the trace. This field + was added in minor version 2 of the ``json-v1`` format. Additionally, the first JSON document outputted contains the ``version`` key for the current major and minor version of the @@ -323,7 +385,7 @@ Options { "version": { "major": 1, - "minor": 1 + "minor": 2 } } @@ -364,6 +426,11 @@ Options in :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR`. This flag tells CMake to warn about other files as well. +``--compile-no-warning-as-error`` + Ignore target property :prop_tgt:`COMPILE_WARNING_AS_ERROR` and variable + :variable:`CMAKE_COMPILE_WARNING_AS_ERROR`, preventing warnings from being + treated as errors on compile. + ``--profiling-output=<path>`` Used in conjunction with ``--profiling-format`` to output to a given path. @@ -449,6 +516,29 @@ following options: Build target ``clean`` first, then build. (To clean only, use ``--target clean``.) +``--resolve-package-references=<on|off|only>`` + .. versionadded:: 3.23 + + Resolve remote package references from external package managers (e.g. NuGet) + before build. When set to ``on`` (default), packages will be restored before + building a target. When set to ``only``, the packages will be restored, but no + build will be performed. When set to ``off``, no packages will be restored. + + If the target does not define any package references, this option does nothing. + + This setting can be specified in a build preset (using + ``resolvePackageReferences``). The preset setting will be ignored, if this + command line option is specified. + + If no command line parameter or preset option are provided, an environment- + specific cache variable will be evaluated to decide, if package restoration + should be performed. + + When using the Visual Studio generator, package references are defined + using the :prop_tgt:`VS_PACKAGE_REFERENCES` property. Package references + are restored using NuGet. It can be disabled by setting the + ``CMAKE_VS_NUGET_PACKAGE_RESTORE`` variable to ``OFF``. + ``--use-stderr`` Ignored. Behavior is default in CMake >= 3.0. @@ -534,6 +624,8 @@ in the set of :variable:`CMAKE_ARGV<n> <CMAKE_ARGV0>` variables passed to the script (including the ``--`` itself). +.. _`Run a Command-Line Tool`: + Run a Command-Line Tool ======================= @@ -547,6 +639,8 @@ Run ``cmake -E`` or ``cmake -E help`` for a summary of commands. Available commands are: ``capabilities`` + .. versionadded:: 3.7 + Report cmake capabilities in JSON format. The output is a JSON object with the following keys: @@ -606,17 +700,28 @@ Available commands are: ``true`` if cmake supports server-mode and ``false`` otherwise. Always false since CMake 3.20. -``cat <files>...`` +``cat [--] <files>...`` + .. versionadded:: 3.18 + Concatenate files and print on the standard output. + .. versionadded:: 3.24 + Added support for the double dash argument ``--``. This basic implementation + of ``cat`` does not support any options, so using a option starting with + ``-`` will result in an error. Use ``--`` to indicate the end of options, in + case a file starts with ``-``. + ``chdir <dir> <cmd> [<arg>...]`` Change the current working directory and run a command. ``compare_files [--ignore-eol] <file1> <file2>`` Check if ``<file1>`` is same as ``<file2>``. If files are the same, then returns ``0``, if not it returns ``1``. In case of invalid - arguments, it returns 2. The ``--ignore-eol`` option - implies line-wise comparison and ignores LF/CRLF differences. + arguments, it returns 2. + + .. versionadded:: 3.14 + The ``--ignore-eol`` option implies line-wise comparison and ignores + LF/CRLF differences. ``copy <file>... <destination>`` Copy files to ``<destination>`` (either file or directory). @@ -625,11 +730,21 @@ Available commands are: ``copy`` does follow symlinks. That means it does not copy symlinks, but the files or directories it point to. + .. versionadded:: 3.5 + Support for multiple input files. + ``copy_directory <dir>... <destination>`` Copy content of ``<dir>...`` directories to ``<destination>`` directory. If ``<destination>`` directory does not exist it will be created. ``copy_directory`` does follow symlinks. + .. versionadded:: 3.5 + Support for multiple input directories. + + .. versionadded:: 3.15 + The command now fails when the source directory does not exist. + Previously it succeeded by creating an empty destination directory. + ``copy_if_different <file>... <destination>`` Copy files to ``<destination>`` (either file or directory) if they have changed. @@ -637,13 +752,21 @@ Available commands are: directory and it must exist. ``copy_if_different`` does follow symlinks. + .. versionadded:: 3.5 + Support for multiple input files. + ``create_symlink <old> <new>`` Create a symbolic link ``<new>`` naming ``<old>``. + .. versionadded:: 3.13 + Support for creating symlinks on Windows. + .. note:: Path to where ``<new>`` symbolic link will be created has to exist beforehand. ``create_hardlink <old> <new>`` + .. versionadded:: 3.19 + Create a hard link ``<new>`` naming ``<old>``. .. note:: @@ -656,13 +779,22 @@ Available commands are: ``echo_append [<string>...]`` Displays arguments as text but no new line. -``env [--unset=NAME]... [NAME=VALUE]... COMMAND [ARG]...`` +``env [--unset=NAME ...] [NAME=VALUE ...] [--] <command> [<arg>...]`` + .. versionadded:: 3.1 + Run command in a modified environment. + .. versionadded:: 3.24 + Added support for the double dash argument ``--``. Use ``--`` to stop + interpreting options/environment variables and treat the next argument as + the command, even if it start with ``-`` or contains a ``=``. + ``environment`` Display the current environment variables. ``false`` + .. versionadded:: 3.16 + Do nothing, with an exit code of 1. ``make_directory <dir>...`` @@ -670,6 +802,9 @@ Available commands are: directories too. If a directory already exists it will be silently ignored. + .. versionadded:: 3.5 + Support for multiple input directories. + ``md5sum <file>...`` Create MD5 checksum of files in ``md5sum`` compatible format:: @@ -677,30 +812,40 @@ Available commands are: 052f86c15bbde68af55c7f7b340ab639 file2.txt ``sha1sum <file>...`` + .. versionadded:: 3.10 + Create SHA1 checksum of files in ``sha1sum`` compatible format:: 4bb7932a29e6f73c97bb9272f2bdc393122f86e0 file1.txt 1df4c8f318665f9a5f2ed38f55adadb7ef9f559c file2.txt ``sha224sum <file>...`` + .. versionadded:: 3.10 + Create SHA224 checksum of files in ``sha224sum`` compatible format:: b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930 file1.txt 6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24 file2.txt ``sha256sum <file>...`` + .. versionadded:: 3.10 + Create SHA256 checksum of files in ``sha256sum`` compatible format:: 76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc file1.txt 15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea file2.txt ``sha384sum <file>...`` + .. versionadded:: 3.10 + Create SHA384 checksum of files in ``sha384sum`` compatible format:: acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434 file1.txt 668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d file2.txt ``sha512sum <file>...`` + .. versionadded:: 3.10 + Create SHA512 checksum of files in ``sha512sum`` compatible format:: 2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89 file1.txt @@ -723,26 +868,36 @@ Available commands are: .. deprecated:: 3.17 Remove ``<dir>`` directories and their contents. If a directory does - not exist it will be silently ignored. If ``<dir>`` is a symlink to - a directory, just the symlink will be removed. + not exist it will be silently ignored. Use ``rm`` instead. + .. versionadded:: 3.15 + Support for multiple directories. + + .. versionadded:: 3.16 + If ``<dir>`` is a symlink to a directory, just the symlink will be removed. + ``rename <oldname> <newname>`` Rename a file or directory (on one volume). If file with the ``<newname>`` name already exists, then it will be silently replaced. -``rm [-rRf] <file> <dir>...`` - Remove the files ``<file>`` or directories ``dir``. +``rm [-rRf] [--] <file|dir>...`` + .. versionadded:: 3.17 + + Remove the files ``<file>`` or directories ``<dir>``. Use ``-r`` or ``-R`` to remove directories and their contents recursively. If any of the listed files/directories do not exist, the command returns a non-zero exit code, but no message is logged. The ``-f`` option changes the behavior to return a zero exit code (i.e. success) in such - situations instead. + situations instead. Use ``--`` to stop interpreting options and treat all + remaining arguments as paths, even if they start with ``-``. ``server`` Launch :manual:`cmake-server(7)` mode. ``sleep <number>...`` + .. versionadded:: 3.0 + Sleep for given number of seconds. ``tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]`` @@ -751,45 +906,91 @@ Available commands are: ``c`` Create a new archive containing the specified files. If used, the ``<pathname>...`` argument is mandatory. + ``x`` Extract to disk from the archive. - The ``<pathname>...`` argument could be used to extract only selected files - or directories. - When extracting selected files or directories, you must provide their exact - names including the path, as printed by list (``-t``). + + .. versionadded:: 3.15 + The ``<pathname>...`` argument could be used to extract only selected files + or directories. + When extracting selected files or directories, you must provide their exact + names including the path, as printed by list (``-t``). + ``t`` List archive contents. - The ``<pathname>...`` argument could be used to list only selected files - or directories. + + .. versionadded:: 3.15 + The ``<pathname>...`` argument could be used to list only selected files + or directories. + ``v`` Produce verbose output. + ``z`` Compress the resulting archive with gzip. + ``j`` Compress the resulting archive with bzip2. + ``J`` + .. versionadded:: 3.1 + Compress the resulting archive with XZ. + ``--zstd`` + .. versionadded:: 3.15 + Compress the resulting archive with Zstandard. + ``--files-from=<file>`` + .. versionadded:: 3.1 + Read file names from the given file, one per line. Blank lines are ignored. Lines may not start in ``-`` except for ``--add-file=<name>`` to add files whose names start in ``-``. + ``--format=<format>`` + .. versionadded:: 3.3 + Specify the format of the archive to be created. Supported formats are: ``7zip``, ``gnutar``, ``pax``, ``paxr`` (restricted pax, default), and ``zip``. + ``--mtime=<date>`` + .. versionadded:: 3.1 + Specify modification time recorded in tarball entries. + + ``--touch`` + .. versionadded:: 3.24 + + Use current local timestamp instead of extracting file timestamps + from the archive. + ``--`` + .. versionadded:: 3.1 + Stop interpreting options and treat all remaining arguments as file names, even if they start with ``-``. + .. versionadded:: 3.1 + LZMA (7zip) support. + + .. versionadded:: 3.15 + The command now continues adding files to an archive even if some of the + files are not readable. This behavior is more consistent with the classic + ``tar`` tool. The command now also parses all flags, and if an invalid flag + was provided, a warning is issued. ``time <command> [<args>...]`` Run command and display elapsed time. + .. versionadded:: 3.5 + The command now properly passes arguments with spaces or special characters + through to the child process. This may break scripts that worked around the + bug with their own extra quoting or escaping. + ``touch <file>...`` Creates ``<file>`` if file do not exist. If ``<file>`` exists, it is changing ``<file>`` access and modification times. @@ -799,6 +1000,8 @@ Available commands are: not exist it will be silently ignored. ``true`` + .. versionadded:: 3.16 + Do nothing, with an exit code of 0. Windows-specific Command-Line Tools @@ -810,10 +1013,14 @@ The following ``cmake -E`` commands are available only on Windows: Delete Windows registry value. ``env_vs8_wince <sdkname>`` + .. versionadded:: 3.2 + Displays a batch file which sets the environment for the provided Windows CE SDK installed in VS2005. ``env_vs9_wince <sdkname>`` + .. versionadded:: 3.2 + Displays a batch file which sets the environment for the provided Windows CE SDK installed in VS2008. @@ -859,6 +1066,18 @@ To view the presets available for a project, use cmake <source-dir> --list-presets + +.. _`CMake Exit Code`: + +Return Value (Exit Code) +======================== + +Upon regular termination, the ``cmake`` executable returns the exit code ``0``. + +If termination is caused by the command :command:`message(FATAL_ERROR)`, +or another error condition, then a non-zero exit code is returned. + + See Also ======== diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index d66c5a9..06f0d4e 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -357,11 +357,21 @@ See `Build and Test Mode`_. Specify the directory in which to look for tests. ``--test-output-size-passed <size>`` + .. versionadded:: 3.4 + Limit the output for passed tests to ``<size>`` bytes. ``--test-output-size-failed <size>`` + .. versionadded:: 3.4 + Limit the output for failed tests to ``<size>`` bytes. +``--test-output-truncation <mode>`` + .. versionadded:: 3.24 + + Truncate ``tail`` (default), ``middle`` or ``head`` of test output once + maximum output size is reached. + ``--overwrite`` Overwrite CTest configuration option. @@ -1353,6 +1363,13 @@ Configuration settings include: * :module:`CTest` module variable: ``SUBMIT_URL`` if set, else ``CTEST_SUBMIT_URL`` +``SubmitInactivityTimeout`` + The time to wait for the submission after which it is canceled + if not completed. Specify a zero value to disable timeout. + + * `CTest Script`_ variable: :variable:`CTEST_SUBMIT_INACTIVITY_TIMEOUT` + * :module:`CTest` module variable: ``CTEST_SUBMIT_INACTIVITY_TIMEOUT`` + ``TriggerSite`` Legacy option. Not used. diff --git a/Help/manual/presets/example.json b/Help/manual/presets/example.json index b08445a..be5c791 100644 --- a/Help/manual/presets/example.json +++ b/Help/manual/presets/example.json @@ -1,10 +1,14 @@ { - "version": 3, + "version": 5, "cmakeMinimumRequired": { "major": 3, - "minor": 21, + "minor": 23, "patch": 0 }, + "include": [ + "otherThings.json", + "moreThings.json" + ], "configurePresets": [ { "name": "default", diff --git a/Help/manual/presets/schema.json b/Help/manual/presets/schema.json index 7852550..c96405c 100644 --- a/Help/manual/presets/schema.json +++ b/Help/manual/presets/schema.json @@ -42,6 +42,36 @@ "testPresets": { "$ref": "#/definitions/testPresetsV3"} }, "additionalProperties": false + }, + { + "properties": { + "version": { + "const": 4, + "description": "A required integer representing the version of the JSON schema." + }, + "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, + "vendor": { "$ref": "#/definitions/vendor" }, + "configurePresets": { "$ref": "#/definitions/configurePresetsV3"}, + "buildPresets": { "$ref": "#/definitions/buildPresetsV4"}, + "testPresets": { "$ref": "#/definitions/testPresetsV3"}, + "include": { "$ref": "#/definitions/include"} + }, + "additionalProperties": false + }, + { + "properties": { + "version": { + "const": 5, + "description": "A required integer representing the version of the JSON schema." + }, + "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, + "vendor": { "$ref": "#/definitions/vendor" }, + "configurePresets": { "$ref": "#/definitions/configurePresetsV3"}, + "buildPresets": { "$ref": "#/definitions/buildPresetsV4"}, + "testPresets": { "$ref": "#/definitions/testPresetsV5"}, + "include": { "$ref": "#/definitions/include"} + }, + "additionalProperties": false } ], "required": [ @@ -412,9 +442,25 @@ "additionalProperties": false } }, + "buildPresetsItemsV4": { + "type": "array", + "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 4 and higher.", + "items": { + "type": "object", + "properties": { + "resolvePackageReferences": { + "type": "string", + "description": "An optional string specifying the package resolve behavior. Valid values are \"on\" (packages are resolved prior to the build), \"off\" (packages are not resolved prior to the build), and \"only\" (packages are resolved, but no build will be performed).", + "enum": [ + "on", "off", "only" + ] + } + } + } + }, "buildPresetsItemsV3": { "type": "array", - "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.", + "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 3 and higher.", "items": { "type": "object", "properties": { @@ -543,9 +589,44 @@ ] } }, + "buildPresetsV4": { + "type": "array", + "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 4 and higher.", + "allOf": [ + { "$ref": "#/definitions/buildPresetsItemsV4" }, + { "$ref": "#/definitions/buildPresetsItemsV3" }, + { "$ref": "#/definitions/buildPresetsItemsV2" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "jobs": {}, + "targets": {}, + "configuration": {}, + "cleanFirst": {}, + "resolvePackageReferences": {}, + "verbose": {}, + "nativeToolOptions": {}, + "condition": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, "buildPresetsV3": { "type": "array", - "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.", + "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 3 and higher.", "allOf": [ { "$ref": "#/definitions/buildPresetsItemsV3" }, { "$ref": "#/definitions/buildPresetsItemsV2" } @@ -607,9 +688,31 @@ "additionalProperties": false } }, + "testPresetsItemsV5": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 5 and higher.", + "items": { + "type": "object", + "properties": { + "output": { + "type": "object", + "description": "An optional object specifying output options.", + "properties": { + "testOutputTruncation": { + "type": "string", + "description": "An optional string specifying the test output truncation mode. Equivalent to passing --test-output-truncation on the command line. Must be one of the following values: \"tail\", \"middle\", or \"head\".", + "enum": [ + "tail", "middle", "head" + ] + } + } + } + } + } + }, "testPresetsItemsV3": { "type": "array", - "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 3 and higher.", "items": { "type": "object", "properties": { @@ -755,8 +858,7 @@ "type": "integer", "description": "An optional integer specifying the maximum width of a test name to output. Equivalent to passing --max-width on the command line." } - }, - "additionalProperties": false + } }, "filter": { "type": "object", @@ -932,9 +1034,42 @@ ] } }, + "testPresetsV5": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 5 and higher.", + "allOf": [ + { "$ref": "#/definitions/testPresetsItemsV2" }, + { "$ref": "#/definitions/testPresetsItemsV3" }, + { "$ref": "#/definitions/testPresetsItemsV5" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "configuration": {}, + "overwriteConfigurationFile": {}, + "output": {}, + "filter": {}, + "execution": {}, + "condition": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, "testPresetsV3": { "type": "array", - "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 3 and higher.", "allOf": [ { "$ref": "#/definitions/testPresetsItemsV2" }, { "$ref": "#/definitions/testPresetsItemsV3" } @@ -1235,6 +1370,13 @@ "description": "Null indicates that the condition always evaluates to true and is not inherited." } ] + }, + "include": { + "type": "array", + "description": "An optional array of strings representing files to include. If the filenames are not absolute, they are considered relative to the current file.", + "items": { + "type": "string" + } } } } diff --git a/Help/module/CPackPackageMaker.rst b/Help/module/CPackPackageMaker.rst deleted file mode 100644 index 226b6fd..0000000 --- a/Help/module/CPackPackageMaker.rst +++ /dev/null @@ -1,4 +0,0 @@ -CPackPackageMaker ------------------ - -The documentation for the CPack PackageMaker generator has moved here: :cpack_gen:`CPack PackageMaker Generator` diff --git a/Help/policy/CMP0028.rst b/Help/policy/CMP0028.rst index ab38229..dcd39d8 100644 --- a/Help/policy/CMP0028.rst +++ b/Help/policy/CMP0028.rst @@ -13,6 +13,8 @@ on disk. Previously, if a target was not found with a matching name, the name was considered to refer to a file on disk. This can lead to confusing error messages if there is a typo in what should be a target name. +See also the :prop_tgt:`LINK_LIBRARIES_ONLY_TARGETS` target property. + The ``OLD`` behavior for this policy is to search for targets, then files on disk, even if the search term contains double-colons. The ``NEW`` behavior for this policy is to issue a ``FATAL_ERROR`` if a link dependency contains diff --git a/Help/policy/CMP0112.rst b/Help/policy/CMP0112.rst index 313a51e..25c3896 100644 --- a/Help/policy/CMP0112.rst +++ b/Help/policy/CMP0112.rst @@ -18,13 +18,16 @@ file name components no longer add a dependency on the evaluated target. - ``TARGET_PDB_FILE_NAME`` - ``TARGET_PDB_FILE_DIR`` - ``TARGET_BUNDLE_DIR`` + - ``TARGET_BUNDLE_DIR_NAME`` - ``TARGET_BUNDLE_CONTENT_DIR`` In CMake 3.18 and lower a dependency on the evaluated target of the above 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. +that have not been updated to expect the new behavior. The policy setting +is recorded on each target when it is created, and decides whether generator +expressions referencing that target imply a dependency on it. The ``OLD`` behavior for this policy is to add a dependency on the evaluated target for the above generator expressions. The ``NEW`` behavior of diff --git a/Help/policy/CMP0126.rst b/Help/policy/CMP0126.rst index 1b69957..a389512 100644 --- a/Help/policy/CMP0126.rst +++ b/Help/policy/CMP0126.rst @@ -14,6 +14,9 @@ current scope in the following situations: This can occur when the variable was set on the command line using a form like ``cmake -DMYVAR=blah`` instead of ``cmake -DMYVAR:STRING=blah``. +* The ``FORCE`` or ``INTERNAL`` keywords were used when setting the cache + variable. + Note that the ``NEW`` behavior has an important difference to the similar ``NEW`` behavior of policy :policy:`CMP0077`. The :command:`set(CACHE)` command always sets the cache variable if it did not exist previously, diff --git a/Help/policy/CMP0129.rst b/Help/policy/CMP0129.rst new file mode 100644 index 0000000..31a26e5 --- /dev/null +++ b/Help/policy/CMP0129.rst @@ -0,0 +1,34 @@ +CMP0129 +------- + +.. versionadded:: 3.23 + +Compiler id for MCST LCC compilers is now ``LCC``, not ``GNU``. + +CMake 3.23 and above recognize MCST LCC compiler as a different from ``GNU``, +with its own command line and set of capabilities. +CMake now prefers to present this to projects by setting the +:variable:`CMAKE_<LANG>_COMPILER_ID` variable to ``LCC`` instead +of ``GNU``. However, existing projects may assume the compiler id for +LCC is ``GNU`` as it was in CMake versions prior to 3.23. +Therefore this policy determines for MCST LCC compiler which +compiler id to report in the :variable:`CMAKE_<LANG>_COMPILER_ID` +variable after language ``<LANG>`` is enabled by the :command:`project` +or :command:`enable_language` command. The policy must be set prior +to the invocation of either command. + +The ``OLD`` behavior for this policy is to use compiler id ``GNU`` (and set +:variable:`CMAKE_<LANG>_COMPILER_VERSION` to the supported GNU compiler version.) +``NEW`` behavior for this policy is to use compiler id ``LCC``, and set +:variable:`CMAKE_<LANG>_SIMULATE_ID` to ``GNU``, and +:variable:`CMAKE_<LANG>_SIMULATE_VERSION` to the supported GNU compiler version. + +This policy was introduced in CMake version 3.23. Use the +:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW`` explicitly. +Unlike most policies, CMake version |release| does *not* warn +by default when this policy is not set and simply uses ``OLD`` behavior. +See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0129 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0130.rst b/Help/policy/CMP0130.rst new file mode 100644 index 0000000..0dd5623 --- /dev/null +++ b/Help/policy/CMP0130.rst @@ -0,0 +1,32 @@ +CMP0130 +------- + +.. versionadded:: 3.24 + +:command:`while` diagnoses condition evaluation errors. + +CMake 3.23 and below accidentally tolerated errors encountered while +evaluating the condition passed to the :command:`while` command +(but not the :command:`if` command). For example, the code + +.. code-block:: cmake + + set(paren "(") + while(${paren}) + endwhile() + +creates an unbalanced parenthesis during condition evaluation. + +CMake 3.24 and above prefer to diagnose such errors. This policy +provides compatibility for projects that have not been updated to +fix their condition errors. + +The ``OLD`` behavior for this policy is to ignore errors in +:command:`while` conditions. The ``NEW`` behavior for this +policy is to diagnose errors in :command:`while` conditions. + +This policy was introduced in CMake version 3.24. CMake version |release| +warns when the policy is not set and uses ``OLD`` behavior. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0131.rst b/Help/policy/CMP0131.rst new file mode 100644 index 0000000..e85b8ab --- /dev/null +++ b/Help/policy/CMP0131.rst @@ -0,0 +1,31 @@ +CMP0131 +------- + +.. versionadded:: 3.24 + +:prop_tgt:`LINK_LIBRARIES` supports the :genex:`$<LINK_ONLY:...>` +generator expression. + +CMake 3.23 and below documented the :genex:`$<LINK_ONLY:...>` generator +expression only for use in :prop_tgt:`INTERFACE_LINK_LIBRARIES`. +When used in :prop_tgt:`LINK_LIBRARIES`, the content guarded inside +:genex:`$<LINK_ONLY:...>` was always used, even when collecting non-linking +usage requirements such as :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`. + +CMake 3.24 and above prefer to support :genex:`$<LINK_ONLY:...>`, when +used in :prop_tgt:`LINK_LIBRARIES`, by using the guarded content only +for link dependencies and not other usage requirements. This policy +provides compatibility for projects that have not been updated to +account for this change. + +The ``OLD`` behavior for this policy is to use :prop_tgt:`LINK_LIBRARIES` +content guarded by :genex:`$<LINK_ONLY:...>` even for non-linking +usage requirements. The ``NEW`` behavior for this policy is to to use +the guarded content only for link dependencies. + +This policy was introduced in CMake version 3.24. Use the +:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW`` +explicitly. Unlike many policies, CMake version |release| does *not* +warn when this policy is not set, and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0132.rst b/Help/policy/CMP0132.rst new file mode 100644 index 0000000..fadbbdc --- /dev/null +++ b/Help/policy/CMP0132.rst @@ -0,0 +1,26 @@ +CMP0132 +------- + +.. versionadded:: 3.24 + +Apart from when using the Xcode generator and some Visual Studio generators, +CMake 3.23 and below will set environment variables like :envvar:`CC`, +:envvar:`CXX`, etc. when the corresponding language is enabled. +This only occurs on the very first time CMake is run in a build directory, +and the environment variables are only defined at configure time, not build +time. On subsequent CMake runs, these environment variables are not set, +opening up the opportunity for different behavior between the first and +subsequent CMake runs. CMake 3.24 and above prefer to not set these +environment variables when a language is enabled, even on the first run in +a build directory. + +The ``OLD`` behavior for this policy sets the relevant environment variable +on the first run when a language is enabled. The ``NEW`` behavior for this +policy does not set any such environment variables. + +This policy was introduced in CMake version 3.24. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike many policies, CMake version |release| does *not* warn +when this policy is not set and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0133.rst b/Help/policy/CMP0133.rst new file mode 100644 index 0000000..c19bcf9 --- /dev/null +++ b/Help/policy/CMP0133.rst @@ -0,0 +1,32 @@ +CMP0133 +------- + +.. versionadded:: 3.24 + +The :module:`CPack` module disables SLA by default in the +:cpack_gen:`CPack DragNDrop Generator`. + +The :cpack_gen:`CPack DragNDrop Generator` in CMake 3.22 and below attach a +Software License Agreement (SLA) to ``.dmg`` files using the file specified +by :variable:`CPACK_RESOURCE_FILE_LICENSE`, if set to a non-default value. +macOS 12.0 deprecated the tools used to do this, so CMake 3.23 added +the :variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` option to +control the behavior. CMake 3.23 enables that option by default for +compatibility with older versions. CMake 3.24 and above prefer to *not* +enable the :variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` option by +default. This policy provides compatibility with projects that have not +been updated to account for the lack of a SLA in their ``.dmg`` packages. + +The ``OLD`` behavior for this policy is to enable +:variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` by default. +The ``NEW`` behavior for this policy is to not enable it by default. + +This policy was introduced in CMake version 3.24. Use the +:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW`` +explicitly. Unlike many policies, CMake version |release| does *not* warn +by default when this policy is not set and simply uses ``OLD`` behavior. +See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0133 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0134.rst b/Help/policy/CMP0134.rst new file mode 100644 index 0000000..2b562bc --- /dev/null +++ b/Help/policy/CMP0134.rst @@ -0,0 +1,39 @@ +CMP0134 +------- + +.. versionadded:: 3.24 + +The default registry view is ``TARGET`` for the :command:`find_file`, +:command:`find_path`, :command:`find_library`, and :command:`find_package` +commands and ``BOTH`` for the :command:`find_program` command. + +The default registry views in CMake 3.23 and below are selected using the +following rules: + +* if :variable:`CMAKE_SIZEOF_VOID_P` has value ``8``: + + * Use view ``64`` for all ``find_*`` commands except :command:`find_program` + command. + * Use view ``64_32`` for :command:`find_program` command. + +* if :variable:`CMAKE_SIZEOF_VOID_P` has value ``4`` or is undefined: + + * Use view ``32`` for all ``find_*`` commands except :command:`find_program` + command. + * Use view ``32_64`` for :command:`find_program` command. + +The ``OLD`` behavior for this policy is to use registry views ``64`` and +``64_32`` or ``32_64`` and ``32`` as default, depending of +:variable:`CMAKE_SIZEOF_VOID_P` variable value. +The ``NEW`` behavior for this policy is to use registry views ``TARGET`` and +``BOTH`` as default. + +This policy was introduced in CMake version 3.24. Use the +:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW`` +explicitly. Unlike many policies, CMake version |release| does *not* warn +by default when this policy is not set and simply uses ``OLD`` behavior. +See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0133 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0135.rst b/Help/policy/CMP0135.rst new file mode 100644 index 0000000..1c0c134 --- /dev/null +++ b/Help/policy/CMP0135.rst @@ -0,0 +1,29 @@ +CMP0135 +------- + +.. versionadded:: 3.24 + +When using the ``URL`` download method with the :command:`ExternalProject_Add` +command, CMake 3.23 and below sets the timestamps of the extracted contents +to the same as the timestamps in the archive. When the ``URL`` changes, the +new archive is downloaded and extracted, but the timestamps of the extracted +contents might not be newer than the previous contents. Anything that depends +on the extracted contents might not be rebuilt, even though the contents may +change. + +CMake 3.24 and above prefers to set the timestamps of all extracted contents +to the time of the extraction. This ensures that anything that depends on the +extracted contents will be rebuilt whenever the ``URL`` changes. + +The ``DOWNLOAD_EXTRACT_TIMESTAMP`` option to the +:command:`ExternalProject_Add` command can be used to explicitly specify how +timestamps should be handled. When ``DOWNLOAD_EXTRACT_TIMESTAMP`` is not +given, this policy controls the default behavior. The ``OLD`` behavior for +this policy is to restore the timestamps from the archive. The ``NEW`` +behavior sets the timestamps of extracted contents to the time of extraction. + +This policy was introduced in CMake version 3.24. CMake version |release| +warns when the policy is not set and uses ``OLD`` behavior. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0136.rst b/Help/policy/CMP0136.rst new file mode 100644 index 0000000..5414278 --- /dev/null +++ b/Help/policy/CMP0136.rst @@ -0,0 +1,50 @@ +CMP0136 +------- + +.. versionadded:: 3.24 + +Watcom runtime library flags are selected by an abstraction. + +Compilers targeting the Watcom ABI have flags to select the Watcom runtime +library. + +In CMake 3.23 and below, Watcom runtime library selection flags are added to +the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache entries by CMake +automatically. This allows users to edit their cache entries to adjust the +flags. However, the presence of such default flags is problematic for +projects that want to choose a different runtime library programmatically. +In particular, it requires string editing of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variables with knowledge of the +CMake builtin defaults so they can be replaced. + +CMake 3.24 and above prefer to leave the Watcom runtime library selection flags +out of the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` values and instead +offer a first-class abstraction. The :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY` +variable and :prop_tgt:`WATCOM_RUNTIME_LIBRARY` target property may be set to +select the Watcom runtime library. If they are not set then CMake uses the +default value ``MultiThreadedDLL`` on Windows and ``SingleThreaded`` on other +platforms, which is equivalent to the original flags. + +This policy provides compatibility with projects that have not been updated +to be aware of the abstraction. The policy setting takes effect as of the +first :command:`project` or :command:`enable_language` command that enables +a language whose compiler targets the Watcom ABI. + +.. note:: + + Once the policy has taken effect at the top of a project, that choice + must be used throughout the tree. In projects that have nested projects + in subdirectories, be sure to convert everything together. + +The ``OLD`` behavior for this policy is to place Watcom runtime library +flags in the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache +entries and ignore the :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY` abstraction. +The ``NEW`` behavior for this policy is to *not* place Watcom runtime +library flags in the default cache entries and use the abstraction instead. + +This policy was introduced in CMake version 3.24. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike many policies, CMake version |release| does *not* warn +when this policy is not set and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0137.rst b/Help/policy/CMP0137.rst new file mode 100644 index 0000000..ba3cb9c --- /dev/null +++ b/Help/policy/CMP0137.rst @@ -0,0 +1,33 @@ +CMP0137 +------- + +.. versionadded:: 3.24 + +:command:`try_compile` passes platform variables in project mode. + +The :command:`try_compile` command :ref:`source file <Try Compiling Source +Files>` signature propagates CMake variables containing platform settings, +and those specified by the :variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES` +variable, into the generated test project. This helps the test project drive +the toolchain the same way the calling project will. In CMake 3.23 and below, +the :ref:`whole-project <Try Compiling Whole Projects>` signature does not +propagate platform variables automatically. CMake 3.24 and above prefer to +propagate platform variables in the :ref:`whole-project <Try Compiling Whole +Projects>` signature. This policy provides compatibility with projects that +have not been updated to expect the behavior. + +The ``OLD`` behavior for this policy is to not pass any additional variables to +the :ref:`whole-project <Try Compiling Whole Projects>` signature. +The ``NEW`` behavior for this policy is to pass the same variables that the +:ref:`source file <Try Compiling Source Files>` signature does. + +Regardless of the policy setting, the +:variable:`CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES` variable may be set +to suppress passing the platform variables through either signature. + +This policy was introduced in CMake version 3.24. Use the +:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW`` +explicitly. Unlike many policies, CMake version |release| does *not* warn +by default when this policy is not set and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst index 3a17973..d93a9c1 100644 --- a/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst @@ -35,3 +35,5 @@ The features known to this version of CMake are: .. versionadded:: 3.20 Compiler mode is at least CUDA/C++ 23. + +.. include:: CMAKE_LANG_STD_FLAGS.txt diff --git a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst index 1a913fb..6846850 100644 --- a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst @@ -46,6 +46,8 @@ but it does not necessarily imply complete conformance to that standard. Compiler mode is at least C++ 23. +.. include:: CMAKE_LANG_STD_FLAGS.txt + Low level individual compile features ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst index 97da697..7aca9e8 100644 --- a/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst @@ -39,6 +39,8 @@ High level meta features indicating C standard support Compiler mode is at least C 23. +.. include:: CMAKE_LANG_STD_FLAGS.txt + Low level individual compile features ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/prop_gbl/CMAKE_LANG_STD_FLAGS.txt b/Help/prop_gbl/CMAKE_LANG_STD_FLAGS.txt new file mode 100644 index 0000000..0de2d3d --- /dev/null +++ b/Help/prop_gbl/CMAKE_LANG_STD_FLAGS.txt @@ -0,0 +1,7 @@ +.. note:: + + If the compiler's default standard level is at least that + of the requested feature, CMake may omit the ``-std=`` flag. + The flag may still be added if the compiler's default extensions mode + does not match the :prop_tgt:`<LANG>_EXTENSIONS` target property, + or if the :prop_tgt:`<LANG>_STANDARD` target property is set. diff --git a/Help/prop_sf/LANGUAGE.rst b/Help/prop_sf/LANGUAGE.rst index a9b5638..92bd227 100644 --- a/Help/prop_sf/LANGUAGE.rst +++ b/Help/prop_sf/LANGUAGE.rst @@ -7,8 +7,8 @@ A property that can be set to indicate what programming language the source file is. If it is not set the language is determined based on the file extension. Typical values are ``CXX`` (i.e. C++), ``C``, ``CSharp``, ``CUDA``, ``Fortran``, ``HIP``, ``ISPC``, and ``ASM``. Setting -this property for a file means this file will be compiled. Do not set this -for headers or files that should not be compiled. +this property for a file means this file will be compiled, unless +:prop_sf:`HEADER_FILE_ONLY` is set. .. versionchanged:: 3.20 Setting this property causes the source file to be compiled as the diff --git a/Help/prop_test/ENVIRONMENT.rst b/Help/prop_test/ENVIRONMENT.rst index 43bcdbe..07b96bb 100644 --- a/Help/prop_test/ENVIRONMENT.rst +++ b/Help/prop_test/ENVIRONMENT.rst @@ -3,7 +3,7 @@ ENVIRONMENT Specify environment variables that should be defined for running a test. -If set to a list of environment variables and values of the form -``MYVAR=value`` those environment variables will be defined while running -the test. The environment changes from this property do not affect other -tests. +Set to a :ref:`semicolon-separated list <CMake Language Lists>` list +of environment variables and values of the form ``MYVAR=value``. +Those environment variables will be defined while running the test. +The environment changes from this property do not affect other tests. diff --git a/Help/prop_test/ENVIRONMENT_MODIFICATION.rst b/Help/prop_test/ENVIRONMENT_MODIFICATION.rst index 1e17329..ad3e190 100644 --- a/Help/prop_test/ENVIRONMENT_MODIFICATION.rst +++ b/Help/prop_test/ENVIRONMENT_MODIFICATION.rst @@ -7,10 +7,11 @@ Specify environment variables that should be modified for running a test. Note that the operations performed by this property are performed after the :prop_test:`ENVIRONMENT` property is already applied. -If set to a list of environment variables and values of the form -``MYVAR=OP:VALUE``, where ``MYVAR`` is the case-sensitive name of an -environment variable to be modified. Entries are considered in the -order specified in the property's value. The ``OP`` may be one of: +Set to a :ref:`semicolon-separated list <CMake Language Lists>` of +environment variables and values of the form ``MYVAR=OP:VALUE``, +where ``MYVAR`` is the case-sensitive name of an environment variable +to be modified. Entries are considered in the order specified in the +property's value. The ``OP`` may be one of: - ``reset``: Reset to the unmodified value, ignoring all modifications to ``MYVAR`` prior to this entry. Note that this will reset the variable to @@ -18,17 +19,19 @@ order specified in the property's value. The ``OP`` may be one of: to its state from the rest of the CTest execution. - ``set``: Replaces the current value of ``MYVAR`` with ``VALUE``. - ``unset``: Unsets the current value of ``MYVAR``. - - ``string_append``: Appends ``VALUE`` to the current value of ``MYVAR``. - - ``string_prepend``: Prepends ``VALUE`` to the current value of ``MYVAR``. - - ``path_list_append``: Appends ``VALUE`` to the current value of ``MYVAR`` - using the host platform's path list separator (``;`` on Windows and ``:`` - elsewhere). - - ``path_list_prepend``: Prepends ``VALUE`` to the current value of + - ``string_append``: Appends singular ``VALUE`` to the current value of + ``MYVAR``. + - ``string_prepend``: Prepends singular ``VALUE`` to the current value of + ``MYVAR``. + - ``path_list_append``: Appends singular ``VALUE`` to the current value of ``MYVAR`` using the host platform's path list separator (``;`` on Windows and ``:`` elsewhere). - - ``cmake_list_append``: Appends ``VALUE`` to the current value of ``MYVAR`` - using ``;`` as the separator. - - ``cmake_list_prepend``: Prepends ``VALUE`` to the current value of + - ``path_list_prepend``: Prepends singular ``VALUE`` to the current value of + ``MYVAR`` using the host platform's path list separator (``;`` on Windows + and ``:`` elsewhere). + - ``cmake_list_append``: Appends singular ``VALUE`` to the current value of + ``MYVAR`` using ``;`` as the separator. + - ``cmake_list_prepend``: Prepends singular ``VALUE`` to the current value of ``MYVAR`` using ``;`` as the separator. Unrecognized ``OP`` values will result in the test failing before it is diff --git a/Help/prop_tgt/COMPILE_WARNING_AS_ERROR.rst b/Help/prop_tgt/COMPILE_WARNING_AS_ERROR.rst new file mode 100644 index 0000000..86a0f7f --- /dev/null +++ b/Help/prop_tgt/COMPILE_WARNING_AS_ERROR.rst @@ -0,0 +1,10 @@ +COMPILE_WARNING_AS_ERROR +------------------------ + +.. versionadded:: 3.24 + +Specify whether to treat warnings on compile as errors. +If enabled, adds a flag to treat warnings on compile as errors. + +This property is initialized by the value of the variable +:variable:`CMAKE_COMPILE_WARNING_AS_ERROR` if it is set when a target is created. diff --git a/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst b/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst index d7fb9b1..8b777e4 100644 --- a/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst +++ b/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst @@ -8,9 +8,10 @@ This command will be added as a prefix to :command:`add_test`, :command:`add_custom_command`, and :command:`add_custom_target` commands for built target system executables. -If this property contains a :ref:`semicolon-separated list <CMake Language -Lists>`, then the first value is the command and remaining values are its -arguments. +.. versionadded:: 3.15 + If this property contains a :ref:`semicolon-separated list <CMake Language + Lists>`, then the first value is the command and remaining values are its + arguments. This property is initialized by the value of the :variable:`CMAKE_CROSSCOMPILING_EMULATOR` variable if it is set when a target diff --git a/Help/prop_tgt/CUDA_ARCHITECTURES.rst b/Help/prop_tgt/CUDA_ARCHITECTURES.rst index a3191e8..05c2599 100644 --- a/Help/prop_tgt/CUDA_ARCHITECTURES.rst +++ b/Help/prop_tgt/CUDA_ARCHITECTURES.rst @@ -20,6 +20,25 @@ variable if it is set when a target is created. The ``CUDA_ARCHITECTURES`` target property must be set to a non-empty value on targets that compile CUDA sources, or it is an error. See policy :policy:`CMP0104`. +The ``CUDA_ARCHITECTURES`` may be set to one of the following special values: + +``all`` + .. versionadded:: 3.23 + + Compile for all supported major and minor real architectures, + and the highest major virtual architecture. + +``all-major`` + .. versionadded:: 3.23 + + Compile for all supported major real architectures, and the highest + major virtual architecture. + +``native`` + .. versionadded:: 3.24 + + Compile for the architecture(s) of the host's GPU(s). + Examples ^^^^^^^^ diff --git a/Help/prop_tgt/DEPRECATION.rst b/Help/prop_tgt/DEPRECATION.rst index 45ca848..2945c98 100644 --- a/Help/prop_tgt/DEPRECATION.rst +++ b/Help/prop_tgt/DEPRECATION.rst @@ -7,3 +7,8 @@ Deprecation message from imported target's developer. ``DEPRECATION`` is the message regarding a deprecation status to be displayed to downstream users of a target. + +The message is formatted as follows: + +* Lines that do not start in whitespace are wrapped as paragraph text. +* Lines that start in whitespace are preserved as preformatted text. diff --git a/Help/prop_tgt/DOTNET_SDK.rst b/Help/prop_tgt/DOTNET_SDK.rst new file mode 100644 index 0000000..ca1dcac --- /dev/null +++ b/Help/prop_tgt/DOTNET_SDK.rst @@ -0,0 +1,25 @@ +DOTNET_SDK +---------- + +.. versionadded:: 3.23 + +Specify the .NET SDK for C# projects. For example: ``Microsoft.NET.Sdk``. + +This property tells :ref:`Visual Studio Generators` for VS 2019 and +above to generate a .NET SDK-style project using the specified SDK. +The property is meaningful only to these generators, and only in C# +targets. It is ignored for C++ projects, even if they are managed +(e.g. using :prop_tgt:`COMMON_LANGUAGE_RUNTIME`). + +This property must be a non-empty string to generate .NET SDK-style projects. +CMake does not perform any validations for the value of the property. + +This property may be initialized for all targets using the +:variable:`CMAKE_DOTNET_SDK` variable. + +.. note:: + + The :ref:`Visual Studio Generators` in this version of CMake have not + yet learned to support :command:`add_custom_command` in .NET SDK-style + projects. It is currently an error to attach a custom command to a + target with the ``DOTNET_SDK`` property set. diff --git a/Help/prop_tgt/HEADER_DIRS.rst b/Help/prop_tgt/HEADER_DIRS.rst new file mode 100644 index 0000000..d095345 --- /dev/null +++ b/Help/prop_tgt/HEADER_DIRS.rst @@ -0,0 +1,14 @@ +HEADER_DIRS +----------- + +.. versionadded:: 3.23 + +Semicolon-separated list of base directories of the target's default +header set (i.e. the file set with name and type ``HEADERS``). The property +supports :manual:`generator expressions <cmake-generator-expressions(7)>`. + +This property is normally only set by :command:`target_sources(FILE_SET)` +rather than being manipulated directly. + +See :prop_tgt:`HEADER_DIRS_<NAME>` for the list of base directories in +other header sets. diff --git a/Help/prop_tgt/HEADER_DIRS_NAME.rst b/Help/prop_tgt/HEADER_DIRS_NAME.rst new file mode 100644 index 0000000..dc73df7 --- /dev/null +++ b/Help/prop_tgt/HEADER_DIRS_NAME.rst @@ -0,0 +1,15 @@ +HEADER_DIRS_<NAME> +------------------ + +.. versionadded:: 3.23 + +Semicolon-separated list of base directories of the target's ``<NAME>`` +header set, which has the set type ``HEADERS``. The property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +This property is normally only set by :command:`target_sources(FILE_SET)` +rather than being manipulated directly. + +See :prop_tgt:`HEADER_DIRS` for the list of base directories in the +default header set. See :prop_tgt:`HEADER_SETS` for the file set names of all +header sets. diff --git a/Help/prop_tgt/HEADER_SET.rst b/Help/prop_tgt/HEADER_SET.rst new file mode 100644 index 0000000..a703fc1 --- /dev/null +++ b/Help/prop_tgt/HEADER_SET.rst @@ -0,0 +1,15 @@ +HEADER_SET +---------- + +.. versionadded:: 3.23 + +Semicolon-separated list of files in the target's default header set, +(i.e. the file set with name and type ``HEADERS``). If any of the paths +are relative, they are computed relative to the target's source directory. +The property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +This property is normally only set by :command:`target_sources(FILE_SET)` +rather than being manipulated directly. + +See :prop_tgt:`HEADER_SET_<NAME>` for the list of files in other header sets. diff --git a/Help/prop_tgt/HEADER_SETS.rst b/Help/prop_tgt/HEADER_SETS.rst new file mode 100644 index 0000000..ceb1df5 --- /dev/null +++ b/Help/prop_tgt/HEADER_SETS.rst @@ -0,0 +1,15 @@ +HEADER_SETS +----------- + +.. versionadded:: 3.23 + +Read-only list of the target's ``PRIVATE`` and ``PUBLIC`` header sets (i.e. +all file sets with the type ``HEADERS``). Files listed in these file sets are +treated as source files for the purpose of IDE integration. The files also +have their :prop_sf:`HEADER_FILE_ONLY` property set to ``TRUE``. + +Header sets may be defined using the :command:`target_sources` command +``FILE_SET`` option with type ``HEADERS``. + +See also :prop_tgt:`HEADER_SET_<NAME>`, :prop_tgt:`HEADER_SET` and +:prop_tgt:`INTERFACE_HEADER_SETS`. diff --git a/Help/prop_tgt/HEADER_SET_NAME.rst b/Help/prop_tgt/HEADER_SET_NAME.rst new file mode 100644 index 0000000..e537f5a --- /dev/null +++ b/Help/prop_tgt/HEADER_SET_NAME.rst @@ -0,0 +1,15 @@ +HEADER_SET_<NAME> +----------------- + +.. versionadded:: 3.23 + +Semicolon-separated list of files in the target's ``<NAME>`` header set, +which has the set type ``HEADERS``. If any of the paths are relative, +they are computed relative to the target's source directory. The property +supports :manual:`generator expressions <cmake-generator-expressions(7)>`. + +This property is normally only set by :command:`target_sources(FILE_SET)` +rather than being manipulated directly. + +See :prop_tgt:`HEADER_SET` for the list of files in the default header set. +See :prop_tgt:`HEADER_SETS` for the file set names of all header sets. diff --git a/Help/prop_tgt/IMPORTED_NO_SYSTEM.rst b/Help/prop_tgt/IMPORTED_NO_SYSTEM.rst new file mode 100644 index 0000000..ee22d6f --- /dev/null +++ b/Help/prop_tgt/IMPORTED_NO_SYSTEM.rst @@ -0,0 +1,21 @@ +IMPORTED_NO_SYSTEM +------------------ + +.. versionadded:: 3.23 + +Specifies that an :ref:`Imported Target <Imported Targets>` is not +a ``SYSTEM`` library. This has the following effects: + +* Entries of :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` are not treated + as ``SYSTEM`` include directories when compiling consumers, as they + would be by default. Entries of + :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` are not affected, + and will always be treated as ``SYSTEM`` include directories. + +This property can also be enabled on a non-imported target. Doing so does +not affect the build system, but does tell the :command:`install(EXPORT)` and +:command:`export` commands to enable it on the imported targets they generate. + +See the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target property to set this +behavior on the target consuming the include directories rather than +providing them. diff --git a/Help/prop_tgt/INTERFACE_HEADER_SETS.rst b/Help/prop_tgt/INTERFACE_HEADER_SETS.rst new file mode 100644 index 0000000..2d3bdac --- /dev/null +++ b/Help/prop_tgt/INTERFACE_HEADER_SETS.rst @@ -0,0 +1,14 @@ +INTERFACE_HEADER_SETS +--------------------- + +.. versionadded:: 3.23 + +Read-only list of the target's ``INTERFACE`` and ``PUBLIC`` header sets (i.e. +all file sets with the type ``HEADERS``). Files listed in these header sets +can be installed with :command:`install(TARGETS)` and exported with +:command:`install(EXPORT)` and :command:`export`. + +Header sets may be defined using the :command:`target_sources` command +``FILE_SET`` option with type ``HEADERS``. + +See also :prop_tgt:`HEADER_SETS`. diff --git a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst index bf7f72f..53f5838 100644 --- a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst +++ b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst @@ -12,6 +12,13 @@ other target also. This property is overridden by the :prop_tgt:`LINK_INTERFACE_LIBRARIES_<CONFIG>` property if policy :policy:`CMP0022` is ``OLD`` or unset. +The value of this property is used by the generators when constructing +the link rule for a dependent target. A dependent target's direct +link dependencies, specified by its :prop_tgt:`LINK_LIBRARIES` target +property, are linked first, followed by indirect dependencies from the +transitive closure of the direct dependencies' +``INTERFACE_LINK_LIBRARIES`` properties. See policy :policy:`CMP0022`. + Contents of ``INTERFACE_LINK_LIBRARIES`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. See the :manual:`cmake-buildsystem(7)` @@ -19,6 +26,12 @@ manual for more on defining buildsystem properties. .. include:: LINK_LIBRARIES_INDIRECTION.txt +``INTERFACE_LINK_LIBRARIES`` adds transitive link dependencies for a +target's dependents. In advanced use cases, one may update the +direct link dependencies of a target's dependents by using the +:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` and +:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target properties. + Creating Relocatable Packages ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT.rst b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT.rst new file mode 100644 index 0000000..b8b73df --- /dev/null +++ b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT.rst @@ -0,0 +1,236 @@ +INTERFACE_LINK_LIBRARIES_DIRECT +------------------------------- + +.. versionadded:: 3.24 + +List of libraries that consumers of this library should treat +as direct link dependencies. + +This target property may be set to *include* items in a dependent +target's final set of direct link dependencies. See the +:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target property +to exclude items. + +The initial set of a dependent target's direct link dependencies is +specified by its :prop_tgt:`LINK_LIBRARIES` target property. Indirect +link dependencies are specified by the transitive closure of the direct +link dependencies' :prop_tgt:`INTERFACE_LINK_LIBRARIES` properties. +Any link dependency may specify additional direct link dependencies +using the ``INTERFACE_LINK_LIBRARIES_DIRECT`` target property. +The set of direct link dependencies is then filtered to exclude items named +by any dependency's :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` +target property. + +.. |INTERFACE_PROPERTY_LINK_DIRECT| replace:: ``INTERFACE_LINK_LIBRARIES_DIRECT`` +.. include:: INTERFACE_LINK_LIBRARIES_DIRECT.txt + +Direct Link Dependencies as Usage Requirements +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``INTERFACE_PROPERTY_LINK_DIRECT`` and +``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target properties +are :ref:`usage requirements <Target Usage Requirements>`. +Their effects propagate to dependent targets transitively, and can +therefore affect the direct link dependencies of every target in a +chain of dependent libraries. Whenever some library target ``X`` links +to another library target ``Y`` whose direct or transitive usage +requirements contain ``INTERFACE_PROPERTY_LINK_DIRECT`` or +``INTERFACE_PROPERTY_LINK_DIRECT_EXCLUDE``, the properties may affect +``X``'s list of direct link dependencies: + +* If ``X`` is a shared library or executable, its dependencies are linked. + They also affect the usage requirements with which ``X``'s sources are + compiled. + +* If ``X`` is a static library or object library, it does not actually + link, so its dependencies at most affect the usage requirements with + which ``X``'s sources are compiled. + +The properties may also affect the list of direct link dependencies +on ``X``'s dependents: + +* If ``X`` links ``Y`` publicly: + + .. code-block:: cmake + + target_link_libraries(X PUBLIC Y) + + then ``Y`` is placed in ``X``'s :prop_tgt:`INTERFACE_LINK_LIBRARIES`, + so ``Y``'s usage requirements, including ``INTERFACE_PROPERTY_LINK_DIRECT``, + ``INTERFACE_PROPERTY_LINK_DIRECT_EXCLUDE``, and the usage requirements + declared by the direct link dependencies they add, are propagated to + ``X``'s dependents. + +* If ``X`` is a static library or object library, and links ``Y`` privately: + + .. code-block:: cmake + + target_link_libraries(X PRIVATE Y) + + then ``$<LINK_ONLY:Y>`` is placed in ``X``'s + :prop_tgt:`INTERFACE_LINK_LIBRARIES`. ``Y``'s linking requirements, + including ``INTERFACE_PROPERTY_LINK_DIRECT``, + ``INTERFACE_PROPERTY_LINK_DIRECT_EXCLUDE``, and the transitive link + dependencies declared by the direct link dependencies they add, are + propagated to ``X``'s dependents. However, ``Y``'s non-linking + usage requirements are blocked by the :genex:`LINK_ONLY` generator + expression, and are not propagated to ``X``'s dependents. + +* If ``X`` is a shared library or executable, and links ``Y`` privately: + + .. code-block:: cmake + + target_link_libraries(X PRIVATE Y) + + then ``Y`` is not placed in ``X``'s :prop_tgt:`INTERFACE_LINK_LIBRARIES`, + so ``Y``'s usage requirements, even ``INTERFACE_PROPERTY_LINK_DIRECT`` + and ``INTERFACE_PROPERTY_LINK_DIRECT_EXCLUDE``, are not propagated to + ``X``'s dependents. + +* In all cases, the content of ``X``'s :prop_tgt:`INTERFACE_LINK_LIBRARIES` + is not affected by ``Y``'s ``INTERFACE_PROPERTY_LINK_DIRECT`` or + ``INTERFACE_PROPERTY_LINK_DIRECT_EXCLUDE``. + +One may limit the effects of ``INTERFACE_PROPERTY_LINK_DIRECT`` and +``INTERFACE_PROPERTY_LINK_DIRECT_EXCLUDE`` to a subset of dependent +targets by using the :genex:`TARGET_PROPERTY` generator expression. +For example, to limit the effects to executable targets, use an +entry of the form:: + + "$<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:...>" + +Similarly, to limit the effects to specific targets, use an entry +of the form:: + + "$<$<BOOL:$<TARGET_PROPERTY:USE_IT>>:...>" + +This entry will only affect targets that set their ``USE_IT`` +target property to a true value. + +Direct Link Dependency Ordering +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The list of direct link dependencies for a target is computed from an +initial ordered list in its :prop_tgt:`LINK_LIBRARIES` target property. +For each item, additional direct link dependencies are discovered from +its direct and transitive ``INTERFACE_LINK_LIBRARIES_DIRECT`` usage +requirements. Each discovered item is injected before the item that +specified it. However, a discovered item is added at most once, +and only if it did not appear anywhere in the initial list. +This gives :prop_tgt:`LINK_LIBRARIES` control over ordering of +those direct link dependencies that it explicitly specifies. + +Once all direct link dependencies have been collected, items named by +all of their :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` +usage requirements are removed from the final list. This does not +affect the order of the items that remain. + +Example: Static Plugins +^^^^^^^^^^^^^^^^^^^^^^^ + +Consider a static library ``Foo`` that provides a static plugin +``FooPlugin`` to consuming application executables, where the +implementation of the plugin depends on ``Foo`` and other things. +In this case, the application should link to ``FooPlugin`` directly, +before ``Foo``. However, the application author only knows about ``Foo``. +We can express this as follows: + +.. code-block:: cmake + + # Core library used by other components. + add_library(Core STATIC core.cpp) + + # Foo is a static library for use by applications. + # Implementation of Foo depends on Core. + add_library(Foo STATIC foo.cpp foo_plugin_helper.cpp) + target_link_libraries(Foo PRIVATE Core) + + # Extra parts of Foo for use by its static plugins. + # Implementation of Foo's extra parts depends on both Core and Foo. + add_library(FooExtras STATIC foo_extras.cpp) + target_link_libraries(FooExtras PRIVATE Core Foo) + + # The Foo library has an associated static plugin + # that should be linked into the final executable. + # Implementation of the plugin depends on Core, Foo, and FooExtras. + add_library(FooPlugin STATIC foo_plugin.cpp) + target_link_libraries(FooPlugin PRIVATE Core Foo FooExtras) + + # An app that links Foo should link Foo's plugin directly. + set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT FooPlugin) + + # An app does not need to link Foo directly because the plugin links it. + set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE Foo) + +An application ``app`` only needs to specify that it links to ``Foo``: + +.. code-block:: cmake + + add_executable(app main.cpp) + target_link_libraries(app PRIVATE Foo) + +The ``INTERFACE_LINK_LIBRARIES_DIRECT`` target property on ``Foo`` tells +CMake to pretend that ``app`` also links directly to ``FooPlugin``. +The ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target property on ``Foo`` +tells CMake to pretend that ``app`` did *not* link directly to ``Foo``. +Instead, ``Foo`` will be linked as a dependency of ``FooPlugin``. The +final link line for ``app`` will link the libraries in the following +order: + +* ``FooPlugin`` as a direct link dependency of ``app`` + (via ``Foo``'s usage requiremens). +* ``FooExtras`` as a dependency of ``FooPlugin``. +* ``Foo`` as a dependency of ``FooPlugin`` and ``FooExtras``. +* ``Core`` as a dependency of ``FooPlugin``, ``FooExtras``, and ``Foo``. + +Note that without the ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target +property, ``Foo`` would be linked twice: once as a direct dependency +of ``app``, and once as a dependency of ``FooPlugin``. + +Example: Opt-In Static Plugins +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In the above `Example: Static Plugins`_, the ``app`` executable specifies +that it links directly to ``Foo``. In a real application, there might +be an intermediate library: + +.. code-block:: cmake + + add_library(app_impl STATIC app_impl.cpp) + target_link_libraries(app_impl PRIVATE Foo) + + add_executable(app main.cpp) + target_link_libraries(app PRIVATE app_impl) + +In this case we do not want ``Foo``'s ``INTERFACE_LINK_LIBRARIES_DIRECT`` +and ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target properties to affect +the direct dependencies of ``app_impl``. To avoid this, we can revise +the property values to make their effects opt-in: + +.. code-block:: cmake + + # An app that links Foo should link Foo's plugin directly. + set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT + "$<$<BOOL:$<TARGET_PROPERTY:FOO_STATIC_PLUGINS>>:FooPlugin>" + ) + + # An app does not need to link Foo directly because the plugin links it. + set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE + "$<$<BOOL:$<TARGET_PROPERTY:FOO_STATIC_PLUGINS>>:Foo>" + ) + +Now, the ``app`` executable can opt-in to get ``Foo``'s plugin(s): + +.. code-block:: cmake + + set_property(TARGET app PROPERTY FOO_STATIC_PLUGINS 1) + +The final link line for ``app`` will now link the libraries in the following +order: + +* ``FooPlugin`` as a direct link dependency of ``app`` + (via ``Foo``'s usage requiremens). +* ``app_impl`` as a direct link dependency of ``app``. +* ``FooExtras`` as a dependency of ``FooPlugin``. +* ``Foo`` as a dependency of ``app_impl``, ``FooPlugin``, and ``FooExtras``. +* ``Core`` as a dependency of ``FooPlugin``, ``FooExtras``, and ``Foo``. diff --git a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT.txt b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT.txt new file mode 100644 index 0000000..077af42 --- /dev/null +++ b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT.txt @@ -0,0 +1,9 @@ +The value of |INTERFACE_PROPERTY_LINK_DIRECT| may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +.. note:: + + The |INTERFACE_PROPERTY_LINK_DIRECT| target property is intended for + advanced use cases such as injection of static plugins into a consuming + executable. It should not be used as a substitute for organizing + normal calls to :command:`target_link_libraries`. diff --git a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE.rst b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE.rst new file mode 100644 index 0000000..2f8f87f --- /dev/null +++ b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE.rst @@ -0,0 +1,34 @@ +INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE +--------------------------------------- + +.. versionadded:: 3.24 + +List of libraries that consumers of this library should *not* treat +as direct link dependencies. + +This target property may be set to *exclude* items from a dependent +target's final set of direct link dependencies. This property is +processed after the :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` +target property of all other dependencies of the dependent target, so +exclusion from direct link dependence takes priority over inclusion. + +The initial set of a dependent target's direct link dependencies is +specified by its :prop_tgt:`LINK_LIBRARIES` target property. Indirect +link dependencies are specified by the transitive closure of the direct +link dependencies' :prop_tgt:`INTERFACE_LINK_LIBRARIES` properties. +Any link dependency may specify additional direct link dependencies +using the :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` target property. +The set of direct link dependencies is then filtered to exclude items named +by any dependency's ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target +property. + +Excluding an item from a dependent target's direct link dependencies +does not mean the dependent target won't link the item. The item +may still be linked as an indirect link dependency via the +:prop_tgt:`INTERFACE_LINK_LIBRARIES` property on other dependencies. + +.. |INTERFACE_PROPERTY_LINK_DIRECT| replace:: ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` +.. include:: INTERFACE_LINK_LIBRARIES_DIRECT.txt + +See the :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` target property +documentation for more details and examples. diff --git a/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst b/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst index a0a97ad..b37bb0c 100644 --- a/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst +++ b/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst @@ -5,9 +5,12 @@ List of public system include directories for a library. Targets may populate this property to publish the include directories which contain system headers, and therefore should not result in -compiler warnings. The :command:`target_include_directories(SYSTEM)` -command signature populates this property with values given to the -``PUBLIC`` and ``INTERFACE`` keywords. +compiler warnings. Additionally, system include directories are searched +after normal include directories regardless of the order specified. + +The :command:`target_include_directories(SYSTEM)` command signature +populates this property with values given to the ``PUBLIC`` and +``INTERFACE`` keywords. Projects may also get and set the property directly, but must be aware that adding directories to this property does not make those directories used diff --git a/Help/prop_tgt/LANG_STANDARD.rst b/Help/prop_tgt/LANG_STANDARD.rst index bd377ec..c83da01 100644 --- a/Help/prop_tgt/LANG_STANDARD.rst +++ b/Help/prop_tgt/LANG_STANDARD.rst @@ -15,6 +15,13 @@ newer standard is specified than is supported by the compiler, then it will fallback to the latest supported standard. This "decay" behavior may be controlled with the :prop_tgt:`<LANG>_STANDARD_REQUIRED` target property. +Note that the actual language standard used may be higher than that specified +by ``<LANG>_STANDARD``, regardless of the value of +:prop_tgt:`<LANG>_STANDARD_REQUIRED`. In particular, +:ref:`transitive usage requirements <Target Usage Requirements>` or the use of +:manual:`compile features <cmake-compile-features(7)>` can raise the required +language standard above what ``<LANG>_STANDARD`` specifies. + These properties are initialized by the value of the :variable:`CMAKE_<LANG>_STANDARD` variable if it is set when a target is created. diff --git a/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst b/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst index 56ecef8..e61125b 100644 --- a/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst +++ b/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst @@ -11,16 +11,22 @@ The variations are: * :prop_tgt:`OBJCXX_STANDARD_REQUIRED` These properties specify whether the value of :prop_tgt:`<LANG>_STANDARD` is a -requirement. When ``OFF`` or unset, the :prop_tgt:`<LANG>_STANDARD` target +requirement. When false or unset, the :prop_tgt:`<LANG>_STANDARD` target property is treated as optional and may "decay" to a previous standard if the -requested is not available. +requested standard is not available. When ``<LANG>_STANDARD_REQUIRED`` is set +to true, :prop_tgt:`<LANG>_STANDARD` becomes a hard requirement and a fatal +error will be issued if that requirement cannot be met. + +Note that the actual language standard used may be higher than that specified +by :prop_tgt:`<LANG>_STANDARD`, regardless of the value of +``<LANG>_STANDARD_REQUIRED``. In particular, +:ref:`transitive usage requirements <Target Usage Requirements>` or the use of +:manual:`compile features <cmake-compile-features(7)>` can raise the required +language standard above what :prop_tgt:`<LANG>_STANDARD` specifies. These properties are initialized by the value of the :variable:`CMAKE_<LANG>_STANDARD_REQUIRED` variable if it is set when a target is created. -For supported CMake versions see the respective pages. -To control language standard versions see :prop_tgt:`<LANG>_STANDARD`. - See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/prop_tgt/LINKER_LANGUAGE.rst b/Help/prop_tgt/LINKER_LANGUAGE.rst index b0a572b..f47b488 100644 --- a/Help/prop_tgt/LINKER_LANGUAGE.rst +++ b/Help/prop_tgt/LINKER_LANGUAGE.rst @@ -7,8 +7,10 @@ For executables, shared libraries, and modules, this sets the language whose compiler is used to link the target (such as "C" or "CXX"). A typical value for an executable is the language of the source file providing the program entry point (main). If not set, the language -with the highest linker preference value is the default. See -documentation of :variable:`CMAKE_<LANG>_LINKER_PREFERENCE` variables. +with the highest linker preference value is the default. Details of +the linker preferences are considered internal, but some limited +discussion can be found under the internal +:variable:`CMAKE_<LANG>_LINKER_PREFERENCE` variables. If this property is not set by the user, it will be calculated at generate-time by CMake. diff --git a/Help/prop_tgt/LINK_LIBRARIES.rst b/Help/prop_tgt/LINK_LIBRARIES.rst index d88e798..ae5334a 100644 --- a/Help/prop_tgt/LINK_LIBRARIES.rst +++ b/Help/prop_tgt/LINK_LIBRARIES.rst @@ -8,8 +8,11 @@ used for linking. In addition to accepting values from the :command:`target_link_libraries` command, values may be set directly on any target using the :command:`set_property` command. -The value of this property is used by the generators to set the link -libraries for the compiler. +The value of this property is used by the generators to construct the +link rule for the target. The direct link dependencies are linked first, +followed by indirect dependencies from the transitive closure of the +direct dependencies' :prop_tgt:`INTERFACE_LINK_LIBRARIES` properties. +See policy :policy:`CMP0022`. Contents of ``LINK_LIBRARIES`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual @@ -17,3 +20,8 @@ for available expressions. See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem properties. .. include:: LINK_LIBRARIES_INDIRECTION.txt + +In advanced use cases, the list of direct link dependencies specified +by this property may be updated by usage requirements from dependencies. +See the :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` and +:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target properties. diff --git a/Help/prop_tgt/LINK_LIBRARIES_ONLY_TARGETS.rst b/Help/prop_tgt/LINK_LIBRARIES_ONLY_TARGETS.rst new file mode 100644 index 0000000..a9af74d --- /dev/null +++ b/Help/prop_tgt/LINK_LIBRARIES_ONLY_TARGETS.rst @@ -0,0 +1,54 @@ +LINK_LIBRARIES_ONLY_TARGETS +--------------------------- + +.. versionadded:: 3.23 + +Enforce that link items that can be target names are actually existing targets. + +Set this property to a true value to enable additional checks on the contents +of the :prop_tgt:`LINK_LIBRARIES` and :prop_tgt:`INTERFACE_LINK_LIBRARIES` +target properties, typically populated by :command:`target_link_libraries`. +CMake will verify that link items that might be target names actually name +existing targets. An item is considered a possible target name if: + +* it does not contain a ``/`` or ``\``, and +* it does not start in ``-``, and +* (for historical reasons) it does not start in ``$`` or `````. + +This property is initialized by the value of the +:variable:`CMAKE_LINK_LIBRARIES_ONLY_TARGETS` variable when a non-imported +target is created. The property may be explicitly enabled on an imported +target to check its link interface. + +In the following example, CMake will halt with an error at configure time +because ``miLib`` is not a target: + +.. code-block:: cmake + + set(CMAKE_LINK_LIBRARIES_ONLY_TARGETS ON) + add_library(myLib STATIC myLib.c) + add_executable(myExe myExe.c) + target_link_libraries(myExe PRIVATE miLib) # typo for myLib + +In order to link toolchain-provided libraries by name while still +enforcing ``LINK_LIBRARIES_ONLY_TARGETS``, use an +:ref:`imported <Imported Targets>` +:ref:`Interface Library <Interface Libraries>` with the +:prop_tgt:`IMPORTED_LIBNAME` target property: + +.. code-block:: cmake + + add_library(toolchain::m INTERFACE IMPORTED) + set_property(TARGET toolchain::m PROPERTY IMPORTED_LIBNAME "m") + target_link_libraries(myExe PRIVATE toolchain::m) + +See also policy :policy:`CMP0028`. + +.. note:: + + If :prop_tgt:`INTERFACE_LINK_LIBRARIES` contains generator expressions, + its actual list of link items may depend on the type and properties of + the consuming target. In such cases CMake may not always detect names + of missing targets that only appear for specific consumers. + A future version of CMake with improved heuristics may start triggering + errors on projects accepted by previous versions of CMake. diff --git a/Help/prop_tgt/LINK_LIBRARY_OVERRIDE.rst b/Help/prop_tgt/LINK_LIBRARY_OVERRIDE.rst new file mode 100644 index 0000000..81a2a4a --- /dev/null +++ b/Help/prop_tgt/LINK_LIBRARY_OVERRIDE.rst @@ -0,0 +1,54 @@ +LINK_LIBRARY_OVERRIDE +--------------------- + +.. versionadded:: 3.24 + +To resolve incompatible features introduced by :genex:`LINK_LIBRARY` generator +expression, this property offers the possibility to override, per ``link-item`` +(``CMake`` target or external library) involved in the link step, any defined +features with a new one. + +This property takes a :ref:`;-list <CMake Language Lists>` of override +declarations which have the following format: + +:: + + feature[,link-item]* + +For the list of ``link-item`` (``CMake`` target or external library) specified, +the feature ``feature`` will be used in place of any declared feature. For +example: + +.. code-block:: cmake + + add_library(lib1 ...) + target_link_libraries(lib1 PUBLIC "$<LINK_LIBRARY:feature1,external>") + + add_library(lib2 ...) + target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature2,lib1>") + + add_library(lib3 ...) + target_link_libraries(lib3 PRIVATE lib1 lib2) + # Here, lib1 has two different features which prevents to link lib3 + # So, define LINK_LIBRARY_OVERRIDE property to ensure correct link + set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE "feature2,lib1,external") + # The lib1 and external will be used with FEATURE2 to link lib3 + +It is also possible to override any feature with the pre-defined feature +``DEFAULT`` to get the standard behavior (i.e. no feature): + +.. code-block:: cmake + + set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE "DEFAULT,lib1" + "feature2,external") + # The lib1 will be used without any feature and external will use feature2 to link lib3 + +Contents of ``LINK_LIBRARY_OVERRIDE`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +See also :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target property for +a per linked target oriented approach to override features. + +For more information about features, see +:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` +and :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables. diff --git a/Help/prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY.rst b/Help/prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY.rst new file mode 100644 index 0000000..112f614 --- /dev/null +++ b/Help/prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY.rst @@ -0,0 +1,45 @@ +LINK_LIBRARY_OVERRIDE_<LIBRARY> +------------------------------- + +.. versionadded:: 3.24 + +To resolve incompatible features introduced by :genex:`LINK_LIBRARY` generator +expression, this property offers the possibility to override, for a +``link-item`` (``CMake`` target or external library) involved in the link step, +any defined features with a new one. + +This property takes a ``feature`` name which will be applied to the +``link-item`` specified by ``<LIBRARY>`` suffix property. For example: + +.. code-block:: cmake + + add_library(lib1 ...) + target_link_libraries(lib1 PUBLIC "$<LINK_LIBRARY:feature1,external>") + + add_library(lib2 ...) + target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature2,lib1>") + + add_library(lib3 ...) + target_link_libraries(lib3 PRIVATE lib1 lib2) + # Here, lib1 has two different features which prevents to link lib3 + # So, define LINK_LIBRARY_OVERRIDE_lib1 property to ensure correct link + set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE_lib1 feature2) + # The lib1 will be used with feature2 to link lib3 + +It is also possible to override any feature with the pre-defined feature +``DEFAULT`` to get the standard behavior (i.e. no feature): + +.. code-block:: cmake + + set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE_lib1 DEFAULT) + # The lib1 will be used without any feature to link lib3 + +Contents of ``LINK_LIBRARY_OVERRIDE_<LIBRARY>`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +This property takes precedence over :prop_tgt:`LINK_LIBRARY_OVERRIDE` +target property. + +For more information about features, see +:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` +and :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables. diff --git a/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst b/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst index 880343d..39a13ee 100644 --- a/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst +++ b/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst @@ -8,8 +8,13 @@ The contents of the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property of imported targets are treated as ``SYSTEM`` includes by default. If this property is enabled on a target, compilation of sources in that target will not treat the contents of the ``INTERFACE_INCLUDE_DIRECTORIES`` of consumed -imported targets as system includes. +imported targets as system includes. Either way, entries of +:prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` are not affected, +and will always be treated as ``SYSTEM`` include directories. This property is initialized by the value of the :variable:`CMAKE_NO_SYSTEM_FROM_IMPORTED` variable if it is set when a target is created. + +See the :prop_tgt:`IMPORTED_NO_SYSTEM` target property to set this behavior +on the target providing the include directories rather than consuming them. diff --git a/Help/prop_tgt/SOURCES.rst b/Help/prop_tgt/SOURCES.rst index 493643e..1ebfa14 100644 --- a/Help/prop_tgt/SOURCES.rst +++ b/Help/prop_tgt/SOURCES.rst @@ -1,6 +1,38 @@ SOURCES ------- -Source names specified for a target. +This specifies the list of paths to source files for the target. +The following commands all set or add to the ``SOURCES`` target property +and are the usual way to manipulate it: -List of sources specified for a target. +* :command:`add_executable` +* :command:`add_library` +* :command:`add_custom_target` +* :command:`target_sources` + +Contents of ``SOURCES`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. +If a path starts with a generator expression, it is expected to +evaluate to an absolute path. Not doing so is considered undefined behavior. + +Paths that are for files generated by the build will be treated +as relative to the build directory of the target, if the path is not +already specified as an absolute path. Note that whether a file is seen as +generated may be affected by policy :policy:`CMP0118`. + +If a path does not start with a generator expression, is not an +absolute path and is not a generated file, it will be treated as relative to +the location selected by the first of the following that matches: + +* If a file by the specified path exists relative to the target's source + directory, use that file. +* If policy :policy:`CMP0115` is not set to ``NEW``, try appending each + known source file extension to the path and check if that exists + relative to the target's source directory. +* Repeat the above two steps, this time relative to the target's binary + directory instead. + +Note that the above decisions are made at generation time, not build time. + +See the :manual:`cmake-buildsystem(7)` manual for more on defining +buildsystem properties. diff --git a/Help/prop_tgt/VERIFY_INTERFACE_HEADER_SETS.rst b/Help/prop_tgt/VERIFY_INTERFACE_HEADER_SETS.rst new file mode 100644 index 0000000..d8045c6 --- /dev/null +++ b/Help/prop_tgt/VERIFY_INTERFACE_HEADER_SETS.rst @@ -0,0 +1,25 @@ +VERIFY_INTERFACE_HEADER_SETS +---------------------------- + +.. versionadded:: 3.24 + +Used to verify that all headers in a target's ``PUBLIC`` and ``INTERFACE`` +header sets can be included on their own. + +When this property is set to true, and the target is an object library, static +library, shared library, or executable with exports enabled, and the target +has one or more ``PUBLIC`` or ``INTERFACE`` header sets, an object library +target named ``<target_name>_verify_interface_header_sets`` is created. This +verification target has one source file per header in the ``PUBLIC`` and +``INTERFACE`` header sets. Each source file only includes its associated +header file. The verification target links against the original target to get +all of its usage requirements. The verification target has its +:prop_tgt:`EXCLUDE_FROM_ALL` and :prop_tgt:`DISABLE_PRECOMPILE_HEADERS` +properties set to true, and its :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTORCC`, +:prop_tgt:`AUTOUIC`, and :prop_tgt:`UNITY_BUILD` properties set to false. + +If the header's :prop_sf:`LANGUAGE` property is set, the value of that property +is used to determine the language with which to compile the header file. +Otherwise, if the target has any C++ sources, the header is compiled as C++. +Otherwise, if the target has any C sources, the header is compiled as C. +Otherwise, the header file is not compiled. diff --git a/Help/prop_tgt/VS_DOTNET_STARTUP_OBJECT.rst b/Help/prop_tgt/VS_DOTNET_STARTUP_OBJECT.rst new file mode 100644 index 0000000..5212293 --- /dev/null +++ b/Help/prop_tgt/VS_DOTNET_STARTUP_OBJECT.rst @@ -0,0 +1,21 @@ +VS_DOTNET_STARTUP_OBJECT +------------------------ + +.. versionadded:: 3.24 + +Sets the startup object property in Visual Studio .NET targets. +The property value defines a full qualified class name (including package +name), for example: ``MyCompany.Package.MyStarterClass``. + +If the property is unset, Visual Studio uses the first matching +``static void Main(string[])`` function signature by default. When more +than one ``Main()`` method is available in the current project, the property +becomes mandatory for building the project. + +This property only works for Visual Studio 2010 and above; +it is ignored on other generators. + +.. code-block:: cmake + + set_property(TARGET ${TARGET_NAME} PROPERTY + VS_DOTNET_STARTUP_OBJECT "MyCompany.Package.MyStarterClass") diff --git a/Help/prop_tgt/VS_NO_COMPILE_BATCHING.rst b/Help/prop_tgt/VS_NO_COMPILE_BATCHING.rst new file mode 100644 index 0000000..f8a9fa6 --- /dev/null +++ b/Help/prop_tgt/VS_NO_COMPILE_BATCHING.rst @@ -0,0 +1,21 @@ +VS_NO_COMPILE_BATCHING +---------------------- + +.. versionadded:: 3.24 + +Turn off compile batching for the target. Usually MSBuild calls the compiler +with multiple c/cpp files and compiler starts subprocesses for each file to +make the build parallel. If you want compiler to be invoked with one file at +a time set VS_NO_COMPILE_BATCHING to ON. If this flag is set MSBuild will call +compiler with one c/cpp file at a time. Useful when you want to use tool that +replaces the compiler, for example some build caching tool. + +Example +^^^^^^^ + +This shows setting the variable for the target foo. + +.. code-block:: cmake + + add_library(foo SHARED foo.cpp) + set_property(TARGET foo PROPERTY VS_NO_COMPILE_BATCHING ON) diff --git a/Help/prop_tgt/WATCOM_RUNTIME_LIBRARY-VALUES.txt b/Help/prop_tgt/WATCOM_RUNTIME_LIBRARY-VALUES.txt new file mode 100644 index 0000000..cdf99d0 --- /dev/null +++ b/Help/prop_tgt/WATCOM_RUNTIME_LIBRARY-VALUES.txt @@ -0,0 +1,20 @@ +``SingleThreaded`` + Compile without additional flags to use a single-threaded + statically-linked runtime library. +``SingleThreadedDLL`` + Compile with ``-br`` or equivalent flag(s) to use a single-threaded + dynamically-linked runtime library. This is not available for Linux + targets. +``MultiThreaded`` + Compile with ``-bm`` or equivalent flag(s) to use a multi-threaded + statically-linked runtime library. +``MultiThreadedDLL`` + Compile with ``-bm -br`` or equivalent flag(s) to use a multi-threaded + dynamically-linked runtime library. This is not available for Linux + targets. + +The value is ignored on non-Watcom compilers but an unsupported value will +be rejected as an error when using a compiler targeting the Watcom ABI. + +The value may also be the empty string (``""``) in which case no runtime +library selection flag will be added explicitly by CMake. diff --git a/Help/prop_tgt/WATCOM_RUNTIME_LIBRARY.rst b/Help/prop_tgt/WATCOM_RUNTIME_LIBRARY.rst new file mode 100644 index 0000000..3752862 --- /dev/null +++ b/Help/prop_tgt/WATCOM_RUNTIME_LIBRARY.rst @@ -0,0 +1,34 @@ +WATCOM_RUNTIME_LIBRARY +---------------------- + +.. versionadded:: 3.24 + +Select the Watcom runtime library for use by compilers targeting the Watcom ABI. + +The allowed values are: + +.. include:: WATCOM_RUNTIME_LIBRARY-VALUES.txt + +Use :manual:`generator expressions <cmake-generator-expressions(7)>` to +support per-configuration specification. + +For example, the code: + +.. code-block:: cmake + + add_executable(foo foo.c) + set_property(TARGET foo PROPERTY + WATCOM_RUNTIME_LIBRARY "MultiThreaded") + +selects for the target ``foo`` a multi-threaded statically-linked runtime +library. + +If this property is not set then CMake uses the default value +``MultiThreadedDLL`` on Windows and ``SingleThreaded`` on other +platforms to select a Watcom runtime library. + +.. note:: + + This property has effect only when policy :policy:`CMP0136` is set to ``NEW`` + prior to the first :command:`project` or :command:`enable_language` command + that enables a language using a compiler targeting the Watcom ABI. diff --git a/Help/prop_tgt/XCODE_EMBED_type.rst b/Help/prop_tgt/XCODE_EMBED_type.rst index a1af56f..e8383c2 100644 --- a/Help/prop_tgt/XCODE_EMBED_type.rst +++ b/Help/prop_tgt/XCODE_EMBED_type.rst @@ -19,6 +19,12 @@ The supported values for ``<type>`` are: The specified items will be added to the ``Embed App Extensions`` build phase. They must be CMake target names. +``PLUGINS`` + .. versionadded:: 3.23 + + The specified items will be added to the ``Embed PlugIns`` build phase. + They must be CMake target names. + See also :prop_tgt:`XCODE_EMBED_<type>_PATH`, :prop_tgt:`XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY` and :prop_tgt:`XCODE_EMBED_<type>_CODE_SIGN_ON_COPY`. diff --git a/Help/prop_tgt/XCODE_EMBED_type_CODE_SIGN_ON_COPY.rst b/Help/prop_tgt/XCODE_EMBED_type_CODE_SIGN_ON_COPY.rst index 7ec0385..cb449ac 100644 --- a/Help/prop_tgt/XCODE_EMBED_type_CODE_SIGN_ON_COPY.rst +++ b/Help/prop_tgt/XCODE_EMBED_type_CODE_SIGN_ON_COPY.rst @@ -14,5 +14,8 @@ The supported values for ``<type>`` are: ``APP_EXTENSIONS`` .. versionadded:: 3.21 +``PLUGINS`` + .. versionadded:: 3.23 + If a ``XCODE_EMBED_<type>_CODE_SIGN_ON_COPY`` property is not defined on the target, no code signing on copy will be performed for that ``<type>``. diff --git a/Help/prop_tgt/XCODE_EMBED_type_PATH.rst b/Help/prop_tgt/XCODE_EMBED_type_PATH.rst index a6f980d..160f765 100644 --- a/Help/prop_tgt/XCODE_EMBED_type_PATH.rst +++ b/Help/prop_tgt/XCODE_EMBED_type_PATH.rst @@ -16,3 +16,6 @@ The supported values for ``<type>`` are: ``APP_EXTENSIONS`` .. versionadded:: 3.21 + +``PLUGINS`` + .. versionadded:: 3.23 diff --git a/Help/prop_tgt/XCODE_EMBED_type_REMOVE_HEADERS_ON_COPY.rst b/Help/prop_tgt/XCODE_EMBED_type_REMOVE_HEADERS_ON_COPY.rst index 75c8eae..e3a7ced 100644 --- a/Help/prop_tgt/XCODE_EMBED_type_REMOVE_HEADERS_ON_COPY.rst +++ b/Help/prop_tgt/XCODE_EMBED_type_REMOVE_HEADERS_ON_COPY.rst @@ -18,3 +18,6 @@ The supported values for ``<type>`` are: If the ``XCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPY`` property is not defined, headers WILL be removed on copy by default. + +``PLUGINS`` + .. versionadded:: 3.23 diff --git a/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst b/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst index 06a3cf9..8f46d2f 100644 --- a/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst +++ b/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst @@ -38,6 +38,7 @@ The following target properties will be applied on the - :prop_tgt:`XCODE_SCHEME_ARGUMENTS` - :prop_tgt:`XCODE_SCHEME_DEBUG_AS_ROOT` - :prop_tgt:`XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING` +- :prop_tgt:`XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE` - :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` - :prop_tgt:`XCODE_SCHEME_EXECUTABLE` - :prop_tgt:`XCODE_SCHEME_WORKING_DIRECTORY` diff --git a/Help/prop_tgt/XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE.rst b/Help/prop_tgt/XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE.rst new file mode 100644 index 0000000..6ffd694 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE.rst @@ -0,0 +1,15 @@ +XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE +------------------------------------------ + +.. versionadded:: 3.23 + +Property value for ``GPU Frame Capture`` in the Options section of +the generated Xcode scheme. Example values are `Metal` and +`Disabled`. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE` +if it is set when a target is created. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_XCCONFIG.rst b/Help/prop_tgt/XCODE_XCCONFIG.rst new file mode 100644 index 0000000..f44e422 --- /dev/null +++ b/Help/prop_tgt/XCODE_XCCONFIG.rst @@ -0,0 +1,14 @@ +XCODE_XCCONFIG +-------------- + +.. versionadded:: 3.24 + +If set, the :generator:`Xcode` generator will register the specified +file as a target-level XCConfig file. For global XCConfig files see +the :variable:`CMAKE_XCODE_XCCONFIG` variable. + +This feature is intended to ease migration from native Xcode projects +to CMake projects. + +Contents of ``XCODE_XCCONFIG`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/release/3.17.rst b/Help/release/3.17.rst index abd7463..1aa475f 100644 --- a/Help/release/3.17.rst +++ b/Help/release/3.17.rst @@ -272,7 +272,7 @@ Deprecated and Removed Features of all policies are deprecated and that projects should port to the NEW behaviors. -* The :cpack_gen:`CPack PackageMaker Generator` generator has been +* The CPack ``PackageMaker`` generator has been deprecated because Xcode no longer distributes the PackageMaker tools. The undocumented ``OSXX11`` generator has also been deprecated. diff --git a/Help/release/3.23.rst b/Help/release/3.23.rst new file mode 100644 index 0000000..70a6175 --- /dev/null +++ b/Help/release/3.23.rst @@ -0,0 +1,311 @@ +CMake 3.23 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.22 include the following. + +New Features +============ + +Presets +------- + +* :manual:`cmake-presets(7)` files now support schema version ``4``. + +* :manual:`cmake-presets(7)` files now have an optional ``include`` field, + which allows the files to include other files. + +* :manual:`cmake-presets(7)` files now support a ``${fileDir}`` macro, which + contains the directory containing the preset file. + +* :manual:`cmake-presets(7)` gained support for specifying the + ``resolvePackageReferences`` command line option in a build preset to control + restoration behavior of package references from external package managers. + Currently this is only supported by the Visual Studio generator to support + restoring packages from NuGet. Other generators ignore this option. + +Generators +---------- + +* The :ref:`Visual Studio Generators` for VS 2019 and above learned to + support .NET SDK-style project files (``.csproj``) for C# projects. + See the :prop_tgt:`DOTNET_SDK` target property and corresponding + :variable:`CMAKE_DOTNET_SDK` variable. :command:`add_custom_command` + is not yet supported in .NET SDK-style projects. + +* The :ref:`Visual Studio Generators` for VS 2017 and above learned to + use portable instances of Visual Studio not known to the VS installer. + See the :variable:`CMAKE_GENERATOR_INSTANCE` variable. + +Command-Line +------------ + +* The :manual:`cmake(1)` ``--build`` command, when used with + :ref:`Visual Studio Generators` on projects that set the + :prop_tgt:`VS_PACKAGE_REFERENCES` target property, now automatically + restores package references from NuGet. The cache variable + :variable:`CMAKE_VS_NUGET_PACKAGE_RESTORE` may be set to toggle this behavior + in a build tree. Use the ``--resolve-package-references=<on|off|only>`` + command-line option to control the behavior on one invocation. + +* The :manual:`cmake(1)` command line tool gained a ``--debug-find-pkg=`` + option to enable debug messages under specific :command:`find_package` + calls. + +* The :manual:`cmake(1)` command line tool gained a ``--debug-find-var=`` + option to enable debug messages for ``find_*`` calls that use specific + result variables. + +Compilers +--------- + +* The IBM Open XL C/C++ compiler, based on LLVM, is now supported with + compiler id ``IBMClang``. + +* The MCST LCC compiler is now supported with compiler id ``LCC``. + See policy :policy:`CMP0129`. + +File-Based API +-------------- + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field + has been updated to ``2.4``. + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``directory`` + object ``installers`` field gained a new ``fileSet`` installer type. + +Commands +-------- + +* The :command:`define_property` command gained a new + ``INITIALIZE_FROM_VARIABLE`` option to cause a target property to be + initialized from a variable when a target is created. + +* The :command:`install(TARGETS)` command gained a new ``FILE_SET`` argument, + which can be used to install header file sets associated with a target. + +* The :command:`string(TIMESTAMP)` and :command:`file(TIMESTAMP)` commands now + support the ``%f`` specifier for microseconds. + +* The :command:`target_sources` command gained a new ``FILE_SET`` mode, which + can be used to add headers as header-only source files of a target. + +Variables +--------- + +* The :variable:`CMAKE_CUDA_ARCHITECTURES` variable and associated + :prop_tgt:`CUDA_ARCHITECTURES` target property now support the + ``all``, and ``all-major`` values for CUDA toolkit 7.0+. + +* The :variable:`CMAKE_IGNORE_PREFIX_PATH` and + :variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` variables were added + to tell the :command:`find_package`, :command:`find_program`, + :command:`find_library`, :command:`find_path`, and :command:`find_file` + commands to ignore specified prefixes. + +* The :variable:`CMAKE_LINK_LIBRARIES_ONLY_TARGETS` variable and + corresponding :prop_tgt:`LINK_LIBRARIES_ONLY_TARGETS` target + property were added to optionally require that all link items + that can be target names are actually names of existing targets. + +Properties +---------- + +* The :prop_tgt:`HEADER_SETS` and :prop_tgt:`INTERFACE_HEADER_SETS` read-only + target properties were added to list header sets associated with a target. + +* The :prop_tgt:`HEADER_SET` and :prop_tgt:`HEADER_SET_<NAME>` target + properties were added to list files in the default header set + and named header sets, respectively. + +* The :prop_tgt:`HEADER_DIRS` and :prop_tgt:`HEADER_DIRS_<NAME>` target + properties were added to specify the base directories of the default + header set and named header sets, respectively. + +* The :prop_tgt:`IMPORTED_NO_SYSTEM` target property was added to + specify that an :ref:`Imported Target <Imported Targets>` should + not be treated as a system library (i.e. its include directories + are not automatically ``SYSTEM``). + +* The :prop_tgt:`XCODE_EMBED_PLUGINS <XCODE_EMBED_<type>>` target property + was added to tell the :generator:`Xcode` generator what targets to put in + the ``Embed PlugIns`` build phase. + +* The :prop_tgt:`XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE` target property + and supporting :variable:`CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE` + variable were added to tell the :generator:`Xcode` generator to enable + specifying the Xcode scheme option property ``GPU Frame Capture``. + +Modules +------- + +* The :module:`CheckPIESupported` module now supports the ``OBJC``, + ``OBJCXX``, ``CUDA``, and ``HIP`` languages. It also now honors + :variable:`CMAKE_SYSROOT` and :variable:`CMAKE_OSX_SYSROOT`. + +* The :module:`ExternalProject` module's :command:`ExternalProject_Add` + command gained support for a ``USES_TERMINAL_PATCH`` option to give + the patch step exclusive terminal access. + +* The :module:`FindCUDAToolkit` module now provides a target for + ``libcufft_static_nocallback``, if found. + +* The :module:`FindGLUT` module now provides the ``GLUT_INCLUDE_DIRS`` + result variable to conform with naming conventions documented in the + :manual:`cmake-developer(7)` manual. This supersedes the legacy + ``GLUT_INCLUDE_DIR`` variable. + +* The :module:`FindGTest` module now provides a target for GMock, if found. + +* The :module:`FindVulkan` module now provides a ``Vulkan_VERSION`` result + variable reporting the version number. + +CTest +----- + +* :manual:`ctest(1)` gained a new :variable:`CTEST_SUBMIT_INACTIVITY_TIMEOUT` + variable, which can be used to specify a timeout for submission inactivity. + +CPack +----- + +* The :cpack_gen:`CPack productbuild Generator` gained the new + :variable:`CPACK_PRODUCTBUILD_DOMAINS`, + :variable:`CPACK_PRODUCTBUILD_DOMAINS_ANYWHERE`, + :variable:`CPACK_PRODUCTBUILD_DOMAINS_USER`, and + :variable:`CPACK_PRODUCTBUILD_DOMAINS_ROOT` variables for + adding the domains element to the Distribution XML. With these variables, + it is now possible to install products to the user's home directory + without requiring administrative privileges. + +* The :cpack_gen:`CPack productbuild Generator` gained a new variable, + :variable:`CPACK_PRODUCTBUILD_IDENTIFIER`, used to customize the unique + product identifier associated with the product. + +* The ``CPack.distribution.dist.in`` template used by the + :cpack_gen:`CPack productbuild Generator` and + CPack ``PackageMaker`` generator was updated to use a new + ``CPACK_APPLE_PKG_INSTALLER_CONTENT`` variable for its main content. + This replaced the previously undocumented and now deprecated + ``CPACK_PACKAGEMAKER_CHOICES`` variable. + +* The :cpack_gen:`CPack IFW Generator` gained the new + :variable:`CPACK_IFW_ARCHIVE_FORMAT` and + :variable:`CPACK_IFW_ARCHIVE_COMPRESSION` variables for setting the + format used when packaging new component data archives, and choosing + the compression level used. + These features are available for QtIFW 4.2 and newer. + +* The :cpack_gen:`CPack IFW Generator` gained new + :variable:`CPACK_IFW_PACKAGE_DISABLE_COMMAND_LINE_INTERFACE` variable to + prevent the user from passing any consumer command to the installer, like + ``install``, ``update``, and ``remove``. + This feature is available for QtIFW 4.0 and newer. + +* The :cpack_gen:`CPack IFW Generator` gained the new + :variable:`CPACK_IFW_PACKAGE_PRODUCT_IMAGES` variable for adding a + list of images to be shown on the ``PerformInstallationPage``. + This feature is available for QtIFW 4.0 and newer. + +* The :cpack_gen:`CPack IFW Generator` gained the new + :variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM`, + :variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM_ARGUMENTS`, and + :variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM_DESCRIPTION` variables for + executing a command after the installer is done if the user accepts + the action. This feature is available for QtIFW 4.0 and newer. + +* The :cpack_gen:`CPack IFW Generator` gained the new + :variable:`CPACK_IFW_PACKAGE_SIGNING_IDENTITY` variable for specifying a + code signing identity to be used for signing the generated app bundle. + This feature is available on macOS only, and for QtIFW 3.0 and newer. + +* The :cpack_gen:`CPack WIX Generator` gained a new variable, + :variable:`CPACK_WIX_SKIP_WIX_UI_EXTENSION`, to skip the inclusion + of WixUIExtensions. + +Deprecated and Removed Features +=============================== + +* :manual:`cmake(1)` now warns when multiple source paths are specified, + as in ``cmake -S src1 src2``. This has never been officially documented + or supported, but older versions accidentally accepted multiple source + paths and used the last path specified. Update scripts to avoid + passing multiple source path arguments. + +* The :manual:`cpack(1)` undocumented ``OSXX11`` generator has been removed. + +* The previously undocumented ``CPACK_PACKAGEMAKER_CHOICES`` variable used in + the ``CPack.distribution.dist.in`` template has been replaced by a new + ``CPACK_APPLE_PKG_INSTALLER_CONTENT`` variable. This only affects projects + that were providing their own custom ``CPack.distribution.dist.in`` template + file, but still relied on ``CPACK_PACKAGEMAKER_CHOICES`` being set. Those + custom template files should be updated to use + ``CPACK_APPLE_PKG_INSTALLER_CONTENT`` instead, or to fully define all the + template file's contents without relying on substitution of either variable. + +Other Changes +============= + +* The :cpack_gen:`CPack DragNDrop Generator` no longer attaches + :variable:`CPACK_RESOURCE_FILE_LICENSE` as the license agreement in + the generated ``.dmg`` unless explicitly activated by a + :variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` option. + In CMake projects, the :module:`CPack` module enables the option + by default for compatibility. + +* ``CUDA`` targets may now enable both :prop_tgt:`CUDA_SEPARABLE_COMPILATION` + and :prop_tgt:`CUDA_PTX_COMPILATION`. + +* ``CUDA`` compiler detection now: + + * issues an error in all cases when it's unable to compute the default + architecture(s) if required (see :policy:`CMP0104`), + + * handles ``OFF`` for :variable:`CMAKE_CUDA_ARCHITECTURES` on Clang, + + * supports the theoretical case of multiple default architectures, and + + * tries to detect invalid architectures and issue an error. + +* ``CUDA`` with Clang now implements policy :policy:`CMP0105` and + the ``$<DEVICE_LINK:...>`` and ``$<HOST_LINK:...>`` + :manual:`generator expressions <cmake-generator-expressions(7)>`. + +* The :command:`define_property` command's ``BRIEF_DOCS`` and ``FULL_DOCS`` + arguments are now optional. + +* :manual:`ccmake(1)` may now be enabled on Windows when building + CMake from source. This is experimental, and so is not included + in official distributions. + +Updates +======= + +Changes made since CMake 3.23.0 include the following. + +3.23.1 +------ + +* The :command:`target_sources` ``FILE_SET`` feature added in CMake 3.23.0 + does not yet place header files properly in Apple :prop_tgt:`FRAMEWORK` + targets. Pending further work in a future version of CMake, it is now + an error to add a ``FILE_SET`` of type ``HEADERS`` to such targets on + Apple platforms. + +* The :prop_tgt:`HEADER_SETS` and :prop_tgt:`INTERFACE_HEADER_SETS` target + properties added in CMake 3.23.0 are now read-only records of the header + sets created by the :command:`target_sources` command. + +3.23.2 +------ + +* The ``CPACK_PACKAGEMAKER_CHOICES`` variable used in the + ``CPack.distribution.dist.in`` template file was replaced by a new + ``CPACK_APPLE_PKG_INSTALLER_CONTENT`` variable in CMake 3.23.0. + This broke projects that provided their own template file but still + expected the ``CPACK_PACKAGEMAKER_CHOICES`` variable to be defined. + The old ``CPACK_PACKAGEMAKER_CHOICES`` variable is now also set to the + same content as it was before, but it is formally deprecated. diff --git a/Help/release/dev/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst new file mode 100644 index 0000000..e4cc01e --- /dev/null +++ b/Help/release/dev/0-sample-topic.rst @@ -0,0 +1,7 @@ +0-sample-topic +-------------- + +* This is a sample release note for the change in a topic. + Developers should add similar notes for each topic branch + making a noteworthy change. Each document should be named + and titled to match the topic name to avoid merge conflicts. diff --git a/Help/release/dev/Apple-link-framework.rst b/Help/release/dev/Apple-link-framework.rst new file mode 100644 index 0000000..e194c15 --- /dev/null +++ b/Help/release/dev/Apple-link-framework.rst @@ -0,0 +1,11 @@ +Apple-link-framework +-------------------- + +* The :genex:`LINK_LIBRARY` generator expression gained the ability to link + frameworks in various ways when targeting ``Apple`` platforms. The following + new features were added: + + * ``FRAMEWORK`` + * ``NEEDED_FRAMEWORK`` + * ``REEXPORT_FRAMEWORK`` + * ``WEAK_FRAMEWORK`` diff --git a/Help/release/dev/Apple-link-library.rst b/Help/release/dev/Apple-link-library.rst new file mode 100644 index 0000000..ec4e3b6 --- /dev/null +++ b/Help/release/dev/Apple-link-library.rst @@ -0,0 +1,10 @@ +Apple-link-library +------------------ + +* The :genex:`LINK_LIBRARY` generator expression gained the ability to link + libraries in various ways when targeting ``Apple`` platforms. The following + new features were added: + + * ``NEEDED_LIBRARY`` + * ``REEXPORT_LIBRARY`` + * ``WEAK_LIBRARY`` diff --git a/Help/release/dev/CMAKE_PROJECT_TOP_LEVEL_INCLUDES.rst b/Help/release/dev/CMAKE_PROJECT_TOP_LEVEL_INCLUDES.rst new file mode 100644 index 0000000..ca2d223 --- /dev/null +++ b/Help/release/dev/CMAKE_PROJECT_TOP_LEVEL_INCLUDES.rst @@ -0,0 +1,6 @@ +CMAKE_PROJECT_TOP_LEVEL_INCLUDES +-------------------------------- + +* The :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable was added to allow + injecting custom code at the site of the first :command:`project` call, + after the host and target platform details have been determined. diff --git a/Help/release/dev/ExternalProject-no-extract-timestamp.rst b/Help/release/dev/ExternalProject-no-extract-timestamp.rst new file mode 100644 index 0000000..0e8c01e --- /dev/null +++ b/Help/release/dev/ExternalProject-no-extract-timestamp.rst @@ -0,0 +1,8 @@ +ExternalProject-no-extract-timestamp +------------------------------------ + +* The :command:`ExternalProject_Add` command gained a new + ``DOWNLOAD_EXTRACT_TIMESTAMP`` option for controlling whether the timestamps + of extracted contents are set to match those in the archive when the ``URL`` + download method is used. A new policy :policy:`CMP0135` was added to control + the default behavior when the new option is not used. diff --git a/Help/release/dev/FetchContent_find_package_integration.rst b/Help/release/dev/FetchContent_find_package_integration.rst new file mode 100644 index 0000000..4ca7afc --- /dev/null +++ b/Help/release/dev/FetchContent_find_package_integration.rst @@ -0,0 +1,17 @@ +FetchContent_find_package_integration +------------------------------------- + +* Integration has been added between the :module:`FetchContent` module and the + :command:`find_package` command, enabling the following new capabilities: + + * :command:`FetchContent_MakeAvailable` can now try to satisfy a dependency + by calling :command:`find_package` first. A new + :variable:`FETCHCONTENT_TRY_FIND_PACKAGE_MODE` variable controls whether + this is done by default for all dependencies, is opt-in per dependency, + or is disabled entirely. + + * :command:`find_package` can be re-routed to call + :command:`FetchContent_MakeAvailable` instead. A new read-only + :variable:`CMAKE_FIND_PACKAGE_REDIRECTS_DIR` variable points to a + directory where config package files can be located to facilitate these + re-routed calls. diff --git a/Help/release/dev/FindGLUT-remove-undocumented-vars.rst b/Help/release/dev/FindGLUT-remove-undocumented-vars.rst new file mode 100644 index 0000000..6a0c904 --- /dev/null +++ b/Help/release/dev/FindGLUT-remove-undocumented-vars.rst @@ -0,0 +1,5 @@ +FindGLUT-remove-undocumented-vars +--------------------------------- + +* The :module:`FindGLUT` module no longer provides the undocumented + result variables ``GLUT_LIBRARY`` and ``GLUT_INCLUDE_PATH``. diff --git a/Help/release/dev/FindJNI-targets.rst b/Help/release/dev/FindJNI-targets.rst new file mode 100644 index 0000000..76e390f --- /dev/null +++ b/Help/release/dev/FindJNI-targets.rst @@ -0,0 +1,4 @@ +FindJNI-targets +--------------- + +* The :module:`FindJNI` module now provides imported targets. diff --git a/Help/release/dev/FindMatlab-no-implicit-link.txt b/Help/release/dev/FindMatlab-no-implicit-link.txt new file mode 100644 index 0000000..7ecc17f --- /dev/null +++ b/Help/release/dev/FindMatlab-no-implicit-link.txt @@ -0,0 +1,6 @@ +FindMatlab-no-implicit-link +--------------------------- + +* The :module:`FindMatlab` module :command:`matlab_add_mex` function + gained a ``NO_IMPLICIT_LINK_TO_MATLAB_LIBRARIES`` option to disable + automatic linking of MATLAB libraries. diff --git a/Help/release/dev/Genex-LINK_GROUP.rst b/Help/release/dev/Genex-LINK_GROUP.rst new file mode 100644 index 0000000..aa9e318 --- /dev/null +++ b/Help/release/dev/Genex-LINK_GROUP.rst @@ -0,0 +1,8 @@ +Genex-LINK_GROUP +---------------- + +* The :genex:`LINK_GROUP` generator expression was added to manage the grouping + of libraries during the link step. The variables + :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` and + :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` are used to define features + usable by the :genex:`LINK_GROUP` generator expression. diff --git a/Help/release/dev/Genex-LINK_LIBRARY.rst b/Help/release/dev/Genex-LINK_LIBRARY.rst new file mode 100644 index 0000000..fe44dbc --- /dev/null +++ b/Help/release/dev/Genex-LINK_LIBRARY.rst @@ -0,0 +1,11 @@ +Genex-LINK_LIBRARY +------------------ + +* The :genex:`LINK_LIBRARY` generator expression was added to manage how + libraries are specified during the link step. The variables + :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` and + :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` are used to define features + usable by the :genex:`LINK_LIBRARY` generator expression. Moreover, the + :prop_tgt:`LINK_LIBRARY_OVERRIDE` and + :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties are available + to resolve incompatible features. diff --git a/Help/release/dev/LINK_LIBRARY-WHOLE_ARCHIVE.rst b/Help/release/dev/LINK_LIBRARY-WHOLE_ARCHIVE.rst new file mode 100644 index 0000000..abaf3a9 --- /dev/null +++ b/Help/release/dev/LINK_LIBRARY-WHOLE_ARCHIVE.rst @@ -0,0 +1,14 @@ +LINK_LIBRARY-WHOLE_ARCHIVE +-------------------------- + +* The :genex:`LINK_LIBRARY` generator expression gained the feature + ``WHOLE_ARCHIVE`` to force load of all members in a static library. This + feature is supported on the following target platforms: + + * all ``Apple`` variants + * ``Linux`` + * all ``BSD`` variants + * ``SunOS`` + * ``Windows`` + * ``CYGWIN`` + * ``MSYS`` diff --git a/Help/release/dev/adsp-platform-and-compilers.rst b/Help/release/dev/adsp-platform-and-compilers.rst new file mode 100644 index 0000000..396b29d --- /dev/null +++ b/Help/release/dev/adsp-platform-and-compilers.rst @@ -0,0 +1,13 @@ +adsp-platform-and-compilers +--------------------------- + +* The ADSP compiler (SHARC and Blackfin) now supports + both CCES and VDSP++ installations, + with required configuration now done in the compiler module itself + rather than the Generic-ADSP platform module. + +* A dedicated ``ADSP`` platform has been added + to replace the existing ``Generic-ADSP`` implementation. + This features automatic detection of the latest CCES/VDSP++ install + and compiler selection (``cc21k`` vs. ``ccblkfn``) + based off of the :variable:`CMAKE_SYSTEM_PROCESSOR` variable. diff --git a/Help/release/dev/chsi-query-windows-registry.rst b/Help/release/dev/chsi-query-windows-registry.rst new file mode 100644 index 0000000..e75bbd8 --- /dev/null +++ b/Help/release/dev/chsi-query-windows-registry.rst @@ -0,0 +1,5 @@ +chsi-query-windows-registry +--------------------------- + +* :command:`cmake_host_system_information` command gains the capability, on + ``Windows`` platform, to query the registry. diff --git a/Help/release/dev/cmake-E-tar-touch.rst b/Help/release/dev/cmake-E-tar-touch.rst new file mode 100644 index 0000000..6d1338d --- /dev/null +++ b/Help/release/dev/cmake-E-tar-touch.rst @@ -0,0 +1,6 @@ +cmake-E-tar-touch +----------------- + +* The :manual:`cmake(1)` ``-E tar`` command gained the ``--touch`` option + to keep the current local timestamp instead of extracting file timestamps + from the archive. diff --git a/Help/release/dev/cmake-fresh.rst b/Help/release/dev/cmake-fresh.rst new file mode 100644 index 0000000..6de5b4e --- /dev/null +++ b/Help/release/dev/cmake-fresh.rst @@ -0,0 +1,5 @@ +cmake-fresh +----------- + +* :manual:`cmake(1)` gained the ``--fresh`` command-line option to remove + any existing ``CMakeCache.txt`` when configuring a build tree. diff --git a/Help/release/dev/cmcmd-end-of-options-delimiter.rst b/Help/release/dev/cmcmd-end-of-options-delimiter.rst new file mode 100644 index 0000000..bc9cc21 --- /dev/null +++ b/Help/release/dev/cmcmd-end-of-options-delimiter.rst @@ -0,0 +1,7 @@ +cmcmd-end-of-options-delimiter +------------------------------ + +* The :manual:`cmake(1)` ``-E`` commands ``cat`` and ``env`` learned to respect + a double dash (``--``) argument that acts as a delimiter indicating the end of + options. Any following arguments are treated as operands/positional arguments, + even if they begin with a dash ``-`` character. diff --git a/Help/release/dev/color-diagnostics.rst b/Help/release/dev/color-diagnostics.rst new file mode 100644 index 0000000..8e0e225 --- /dev/null +++ b/Help/release/dev/color-diagnostics.rst @@ -0,0 +1,10 @@ +color-diagnostics +----------------- + +* The :variable:`CMAKE_COLOR_DIAGNOSTICS` variable was added to control + color diagnostics generated by compilers. This variable also controls + color buildsystem messages with :ref:`Makefile Generators`, replacing + :variable:`CMAKE_COLOR_MAKEFILE`. + + The :envvar:`CMAKE_COLOR_DIAGNOSTICS` environment was added to set + a default value for :variable:`CMAKE_COLOR_DIAGNOSTICS`. diff --git a/Help/release/dev/cpack-dmg-sla.rst b/Help/release/dev/cpack-dmg-sla.rst new file mode 100644 index 0000000..34c3cff --- /dev/null +++ b/Help/release/dev/cpack-dmg-sla.rst @@ -0,0 +1,6 @@ +cpack-dmg-sla +------------- + +* The :module:`CPack` module no longer enables the SLA by default in the + :cpack_gen:`CPack DragNDrop Generator`. See policy :policy:`CMP0133` + and the :variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` variable. diff --git a/Help/release/dev/cpack-wix-arch.rst b/Help/release/dev/cpack-wix-arch.rst new file mode 100644 index 0000000..e7fd1ad --- /dev/null +++ b/Help/release/dev/cpack-wix-arch.rst @@ -0,0 +1,6 @@ +cpack-wix-arch +-------------- + +* The :cpack_gen:`CPack WIX Generator` gained a new variable, + :variable:`CPACK_WIX_ARCHITECTURE`, to specify the installer architecture + in order to support computers running Windows for ARM. diff --git a/Help/release/dev/cpack-zstd-parallel.rst b/Help/release/dev/cpack-zstd-parallel.rst new file mode 100644 index 0000000..da22625 --- /dev/null +++ b/Help/release/dev/cpack-zstd-parallel.rst @@ -0,0 +1,6 @@ +cpack-zstd-parallel +------------------- + +* CPack now supports the :variable:`CPACK_THREADS` option for ``zstd`` + compression when compiled with libarchive 3.6 or higher. It is + supported by official CMake binaries available on ``cmake.org``. diff --git a/Help/release/dev/ctest-output-truncation.rst b/Help/release/dev/ctest-output-truncation.rst new file mode 100644 index 0000000..85fb37c --- /dev/null +++ b/Help/release/dev/ctest-output-truncation.rst @@ -0,0 +1,11 @@ +ctest-output-truncation +----------------------- + +* :manual:`ctest(1)` gained a ``--test-output-truncation`` option (and + corresponding :variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` variable) to + specify the truncation mode once the maximum test output size has been + reached. Possible values are ``tail`` (default), ``middle`` or ``head``. +* :manual:`cmake-presets(7)` files now support schema version ``5``. +* :manual:`cmake-presets(7)` files gained support for specifying a + ``testOutputTruncation`` field in test presets, which specifies the truncation + mode once the maximum test output size has been reached. diff --git a/Help/release/dev/cuda-arch-native.rst b/Help/release/dev/cuda-arch-native.rst new file mode 100644 index 0000000..f44a668 --- /dev/null +++ b/Help/release/dev/cuda-arch-native.rst @@ -0,0 +1,7 @@ +cuda-arch-native +---------------- + +* The :variable:`CMAKE_CUDA_ARCHITECTURES` variable and associated + :prop_tgt:`CUDA_ARCHITECTURES` target property now support the + special ``native`` value to compile for the architectures(s) + of the host's GPU(s). diff --git a/Help/release/dev/file-download-range.rst b/Help/release/dev/file-download-range.rst new file mode 100644 index 0000000..194100d --- /dev/null +++ b/Help/release/dev/file-download-range.rst @@ -0,0 +1,6 @@ +file-download-range +------------------- + +* Add the fields ``RANGE_START`` and ``RANGE_END`` to ``file(DOWNLOAD)``. + Those fields provide a convenient way to specify the range, passed to the + libcurl, which can be useful for downloading parts of big binary files. diff --git a/Help/release/dev/find-calls-search-install-prefix.rst b/Help/release/dev/find-calls-search-install-prefix.rst new file mode 100644 index 0000000..a111a91 --- /dev/null +++ b/Help/release/dev/find-calls-search-install-prefix.rst @@ -0,0 +1,12 @@ +find-calls-search-install-prefix +-------------------------------- + +* The :command:`find_file`, :command:`find_library`, :command:`find_path`, + :command:`find_package`, and :command:`find_program` commands have gained + the `NO_CMAKE_INSTALL_PREFIX` option to control searching + `CMAKE_INSTALL_PREFIX`. + +* Adds support for :variable:`CMAKE_FIND_USE_INSTALL_PREFIX` to toggle + behavior of the :command:`find_file`, :command:`find_library`, :command:`find_path`, + :command:`find_package`, and :command:`find_program` commands new + `NO_CMAKE_INSTALL_PREFIX` option. diff --git a/Help/release/dev/find_item-query-windows-registry.rst b/Help/release/dev/find_item-query-windows-registry.rst new file mode 100644 index 0000000..ff0bd40 --- /dev/null +++ b/Help/release/dev/find_item-query-windows-registry.rst @@ -0,0 +1,6 @@ +find_item-query-windows-registry.rst +------------------------------------ + +* :command:`find_file`, :command:`find_path`, :command:`find_library`, + :command:`find_program`, and :command:`find_package` commands gain the + capability to specify which registry views must be queried. diff --git a/Help/release/dev/find_package-global-imported.rst b/Help/release/dev/find_package-global-imported.rst new file mode 100644 index 0000000..b32d18d --- /dev/null +++ b/Help/release/dev/find_package-global-imported.rst @@ -0,0 +1,9 @@ +find_package-global-imported +---------------------------- + +* The :command:`find_package` command gained a `GLOBAL` option that + allows for the promotion of imported targets to global scope fur the + duration of the :command:`find_package` call. + +* Adds support for :variable:`CMAKE_FIND_PACKAGE_TARGETS_GLOBAL` to + toggle behavior of the :command:`find_package` command's new GLOBAL option diff --git a/Help/release/dev/findzlib-static.rst b/Help/release/dev/findzlib-static.rst new file mode 100644 index 0000000..35855f6 --- /dev/null +++ b/Help/release/dev/findzlib-static.rst @@ -0,0 +1,5 @@ +findzlib-static +--------------- + +* The :module:`FindZLIB` learned a new ``ZLIB_USE_STATIC_LIBS`` variable to + search only for static libraries. diff --git a/Help/release/dev/ghs_predefined_targets.rst b/Help/release/dev/ghs_predefined_targets.rst new file mode 100644 index 0000000..eeca5a9 --- /dev/null +++ b/Help/release/dev/ghs_predefined_targets.rst @@ -0,0 +1,6 @@ +ghs_predefined_targets +---------------------- + +* A new predefined target `RERUN_CMAKE` is added for + :generator:`Green Hills MULTI` generator to easily rerun + CMake if any CMake files were updated. diff --git a/Help/release/dev/link-interface-direct.rst b/Help/release/dev/link-interface-direct.rst new file mode 100644 index 0000000..8b858e2 --- /dev/null +++ b/Help/release/dev/link-interface-direct.rst @@ -0,0 +1,11 @@ +link-interface-direct +--------------------- + +* The :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` and + :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target properties + were added to express usage requirements affecting a consumer's + direct link dependencies. + +* The :prop_tgt:`LINK_LIBRARIES` target property now supports + the :genex:`$<LINK_ONLY:...>` generator expression. + See policy :policy:`CMP0131`. diff --git a/Help/release/dev/presets-pathListSep.rst b/Help/release/dev/presets-pathListSep.rst new file mode 100644 index 0000000..84b129f --- /dev/null +++ b/Help/release/dev/presets-pathListSep.rst @@ -0,0 +1,5 @@ +presets-pathListSep +------------------- + +* :manual:`cmake-presets(7)` files now support a ``${pathListSep}`` macro, + which expands to ``:`` or ``;`` based on the platform. diff --git a/Help/release/dev/rel-macos-dmg-no-sla.rst b/Help/release/dev/rel-macos-dmg-no-sla.rst new file mode 100644 index 0000000..2f20aab --- /dev/null +++ b/Help/release/dev/rel-macos-dmg-no-sla.rst @@ -0,0 +1,7 @@ +rel-macos-dmg-no-sla +-------------------- + +* The precompiled macOS binaries provided on + `cmake.org <https://cmake.org/download/>`_ no longer attach a SLA + to the ``.dmg`` packages. This was removed because macOS 12 deprecated + the tools used to attach ``.dmg`` resources. diff --git a/Help/release/dev/remove-PackageMaker-generator.rst b/Help/release/dev/remove-PackageMaker-generator.rst new file mode 100644 index 0000000..f20a08c --- /dev/null +++ b/Help/release/dev/remove-PackageMaker-generator.rst @@ -0,0 +1,5 @@ +remove-PackageMaker-generator +----------------------------- + +* The deprecated ``PackageMaker`` :manual:`cpack(1)` generator has + been removed. diff --git a/Help/release/dev/rescan-static-libraries.rst b/Help/release/dev/rescan-static-libraries.rst new file mode 100644 index 0000000..8892d70 --- /dev/null +++ b/Help/release/dev/rescan-static-libraries.rst @@ -0,0 +1,6 @@ +rescan-static-libraries +----------------------- + +* The :genex:`LINK_GROUP` generator expression gained the ability to manage, on + ``Linux`` and ``BSD`` systems, circular references between static libraries + by using ``RESCAN`` feature. diff --git a/Help/release/dev/set-env-var-first-run.rst b/Help/release/dev/set-env-var-first-run.rst new file mode 100644 index 0000000..c3f7d9f --- /dev/null +++ b/Help/release/dev/set-env-var-first-run.rst @@ -0,0 +1,6 @@ +set-env-var-first-run +--------------------- + +* CMake no longer sets environment variables like :envvar:`CC`, :envvar:`CXX`, + etc. when enabling the corresponding language during the first CMake run in + a build directory. See policy :policy:`CMP0132`. diff --git a/Help/release/dev/target-bundle-dir-name-genex.rst b/Help/release/dev/target-bundle-dir-name-genex.rst new file mode 100644 index 0000000..0ae835a --- /dev/null +++ b/Help/release/dev/target-bundle-dir-name-genex.rst @@ -0,0 +1,6 @@ +target-bundle-dir-name-genex +---------------------------- + +* Added the new :genex:`TARGET_BUNDLE_DIR_NAME` generator expression + which evaluates to the name of the bundle directory for a given bundle + target. diff --git a/Help/release/dev/trace-global-frame.rst b/Help/release/dev/trace-global-frame.rst new file mode 100644 index 0000000..fdc4b5c --- /dev/null +++ b/Help/release/dev/trace-global-frame.rst @@ -0,0 +1,8 @@ +trace-global-frame +------------------ + +* Add the field ``global_frame`` to the json-v1 trace format. This + frame tracks the depth of the call stack globally across all + ``CMakeLists.txt`` files involved in the trace, and will let tools + reconstruct stack traces that span from the top-level ``CMakeLists.txt`` + file of the project. diff --git a/Help/release/dev/trace-line-end.rst b/Help/release/dev/trace-line-end.rst new file mode 100644 index 0000000..beade4b --- /dev/null +++ b/Help/release/dev/trace-line-end.rst @@ -0,0 +1,7 @@ +trace-line-end +-------------- + +* Add the field ``line_end`` to the json-v1 trace format. This + field tells you the line in file ``file`` at which the function + call ends. Tools can use this new field, together with ``line`` + and ``file``, to map traces to lines of CMake source code. diff --git a/Help/release/dev/try_compile-project-platform-vars.rst b/Help/release/dev/try_compile-project-platform-vars.rst new file mode 100644 index 0000000..06596d4 --- /dev/null +++ b/Help/release/dev/try_compile-project-platform-vars.rst @@ -0,0 +1,10 @@ +try_compile-project-platform-vars +--------------------------------- + +* The :command:`try_compile` command + :ref:`whole-project <Try Compiling Whole Projects>` signature + now propagates platform variables. See policy :policy:`CMP0137`. + +* The :variable:`CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES` variable + was added to tell the :command:`try_compile` command not to + pass any platform variables to the test project. diff --git a/Help/release/dev/verify-interface-header-sets.rst b/Help/release/dev/verify-interface-header-sets.rst new file mode 100644 index 0000000..fcccb62 --- /dev/null +++ b/Help/release/dev/verify-interface-header-sets.rst @@ -0,0 +1,9 @@ +verify-interface-header-sets +---------------------------- + +* A new :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` target property was added, + which can be used to verify that all headers in header sets can be used on + their own. +* A new :variable:`CMAKE_VERIFY_INTERFACE_HEADER_SETS` variable was added, + which is used to initialize the :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` + target property. diff --git a/Help/release/dev/vs_buildcache_support.rst b/Help/release/dev/vs_buildcache_support.rst new file mode 100644 index 0000000..bdda675 --- /dev/null +++ b/Help/release/dev/vs_buildcache_support.rst @@ -0,0 +1,6 @@ +vs_buildcache_support +--------------------- + +* The :prop_tgt:`VS_NO_COMPILE_BATCHING` target property was added to + tell :ref:`Visual Studio Generators` whether to disable compiler parallelism + and call the compiler with one c/cpp file at a time. diff --git a/Help/release/dev/vs_dotnet_startup_object_support.rst b/Help/release/dev/vs_dotnet_startup_object_support.rst new file mode 100644 index 0000000..1f0672f --- /dev/null +++ b/Help/release/dev/vs_dotnet_startup_object_support.rst @@ -0,0 +1,8 @@ +vs_dotnet_startup_object_support +-------------------------------- + +* The :prop_tgt:`VS_DOTNET_STARTUP_OBJECT` target property was added to + tell :ref:`Visual Studio Generators` which startup class shall be used + when the program or project is executed. This is necessary when more + than one ``static void Main(string[])`` function signature is available + in a managed .NET project. diff --git a/Help/release/dev/watcom-runtime-library.rst b/Help/release/dev/watcom-runtime-library.rst new file mode 100644 index 0000000..3a07b32 --- /dev/null +++ b/Help/release/dev/watcom-runtime-library.rst @@ -0,0 +1,7 @@ +watcom-runtime-library +---------------------- + +* The :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY` variable and + :prop_tgt:`WATCOM_RUNTIME_LIBRARY` target property were introduced to + select the runtime library used by compilers targeting the Watcom ABI. + See policy :policy:`CMP0136`. diff --git a/Help/release/dev/werror-property.rst b/Help/release/dev/werror-property.rst new file mode 100644 index 0000000..84c825f --- /dev/null +++ b/Help/release/dev/werror-property.rst @@ -0,0 +1,13 @@ +werror-property +--------------- + +* Added the Target Property :prop_tgt:`COMPILE_WARNING_AS_ERROR` and the + Variable :variable:`CMAKE_COMPILE_WARNING_AS_ERROR` which initializes the + Target Property. If :prop_tgt:`COMPILE_WARNING_AS_ERROR` is true, it expands + to a different flag depending on the compiler such that any warnings at + compile will be treated as errors. + +* :manual:`cmake(1)` gained the command-line option + ``--compile-no-warning-as-error`` which causes the values of + the :prop_tgt:`COMPILE_WARNING_AS_ERROR` target property and + :variable:`CMAKE_COMPILE_WARNING_AS_ERROR` variable to be ignored. diff --git a/Help/release/dev/while-errors.rst b/Help/release/dev/while-errors.rst new file mode 100644 index 0000000..c39e6e8 --- /dev/null +++ b/Help/release/dev/while-errors.rst @@ -0,0 +1,5 @@ +while-errors +------------ + +* The :command:`while` command now diagnoses errors during condition + evaluation. See policy :policy:`CMP0130`. diff --git a/Help/release/dev/xcode-xcconfig.rst b/Help/release/dev/xcode-xcconfig.rst new file mode 100644 index 0000000..4ad4cbe --- /dev/null +++ b/Help/release/dev/xcode-xcconfig.rst @@ -0,0 +1,6 @@ +xcode-xcconfig +-------------- + +* The Xcode generator learned to handle global and target specific + ``xcconfig`` files with the :variable:`CMAKE_XCODE_XCCONFIG` + variable and :prop_tgt:`XCODE_XCCONFIG` target property. diff --git a/Help/release/index.rst b/Help/release/index.rst index 3d2ed43..ad33705 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -7,12 +7,15 @@ CMake Release Notes This file should include the adjacent "dev.txt" file in development versions but not in release versions. +.. include:: dev.txt + Releases ======== .. toctree:: :maxdepth: 1 + 3.23 <3.23> 3.22 <3.22> 3.21 <3.21> 3.20 <3.20> diff --git a/Help/variable/CMAKE_ADSP_ROOT.rst b/Help/variable/CMAKE_ADSP_ROOT.rst new file mode 100644 index 0000000..e6d903d --- /dev/null +++ b/Help/variable/CMAKE_ADSP_ROOT.rst @@ -0,0 +1,9 @@ +CMAKE_ADSP_ROOT +--------------- + +When :ref:`Cross Compiling for ADSP SHARC/Blackfin`, +this variable holds the absolute path to the latest CCES or VDSP++ install. +The directory is expected to contain the ``cc21k.exe`` and ``ccblkfn.exe`` compilers. +This will be set automatically if a default install of CCES or VDSP++ can be found. + +See also the :envvar:`ADSP_ROOT` environment variable. diff --git a/Help/variable/CMAKE_CACHEFILE_DIR.rst b/Help/variable/CMAKE_CACHEFILE_DIR.rst index 8604d0e..3fee09f 100644 --- a/Help/variable/CMAKE_CACHEFILE_DIR.rst +++ b/Help/variable/CMAKE_CACHEFILE_DIR.rst @@ -1,7 +1,6 @@ CMAKE_CACHEFILE_DIR ------------------- -The directory with the ``CMakeCache.txt`` file. - -This is the full path to the directory that has the ``CMakeCache.txt`` -file in it. This is the same as :variable:`CMAKE_BINARY_DIR`. +This variable is used internally by CMake, and may not be set during +the first configuration of a build tree. When it is set, it has the +same value as :variable:`CMAKE_BINARY_DIR`. Use that variable instead. diff --git a/Help/variable/CMAKE_COLOR_DIAGNOSTICS.rst b/Help/variable/CMAKE_COLOR_DIAGNOSTICS.rst new file mode 100644 index 0000000..a72c9e1 --- /dev/null +++ b/Help/variable/CMAKE_COLOR_DIAGNOSTICS.rst @@ -0,0 +1,37 @@ +CMAKE_COLOR_DIAGNOSTICS +----------------------- + +.. versionadded:: 3.24 + +Enable color diagnostics throughout. + +This variable uses three states: ``ON``, ``OFF`` and not defined. + +When not defined: + +* :ref:`Makefile Generators` initialize the :variable:`CMAKE_COLOR_MAKEFILE` + variable to ``ON``. It controls color buildsystem messages. + +* GNU/Clang compilers are not invoked with any color diagnostics flag. + +When ``ON``: + +* :ref:`Makefile Generators` produce color buildsystem messages by default. + :variable:`CMAKE_COLOR_MAKEFILE` is not initialized, but may be + explicitly set to ``OFF`` to disable color buildsystem messages. + +* GNU/Clang compilers are invoked with a flag enabling color diagnostics + (``-fcolor-diagnostics``). + +When ``OFF``: + +* :ref:`Makefile Generators` do not produce color buildsystem messages by + default. :variable:`CMAKE_COLOR_MAKEFILE` is not initialized, but may be + explicitly set to ``ON`` to enable color buildsystem messages. + +* GNU/Clang compilers are invoked with a flag disabling color diagnostics + (``-fno-color-diagnostics``). + +If the :envvar:`CMAKE_COLOR_DIAGNOSTICS` environment variable is set, its +value is used. Otherwise, ``CMAKE_COLOR_DIAGNOSTICS`` is not defined by +default. diff --git a/Help/variable/CMAKE_COMPILE_WARNING_AS_ERROR.rst b/Help/variable/CMAKE_COMPILE_WARNING_AS_ERROR.rst new file mode 100644 index 0000000..56dc6a6 --- /dev/null +++ b/Help/variable/CMAKE_COMPILE_WARNING_AS_ERROR.rst @@ -0,0 +1,9 @@ +CMAKE_COMPILE_WARNING_AS_ERROR +------------------------------ + +.. versionadded:: 3.24 + +Specify whether to treat warnings on compile as errors. + +This variable is used to initialize the +:prop_tgt:`COMPILE_WARNING_AS_ERROR` property on all the targets. diff --git a/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst b/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst index 815da00..e21b35d 100644 --- a/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst +++ b/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst @@ -7,9 +7,10 @@ This variable is only used when :variable:`CMAKE_CROSSCOMPILING` is on. It should point to a command on the host system that can run executable built for the target system. -If this variable contains a :ref:`semicolon-separated list <CMake Language -Lists>`, then the first value is the command and remaining values are its -arguments. +.. versionadded:: 3.15 + If this variable contains a :ref:`semicolon-separated list <CMake Language + Lists>`, then the first value is the command and remaining values are its + arguments. The command will be used to run :command:`try_run` generated executables, which avoids manual population of the ``TryRunResults.cmake`` file. diff --git a/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst b/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst index 40496b5..8fc85ee 100644 --- a/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst +++ b/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst @@ -3,7 +3,7 @@ CMAKE_CURRENT_BINARY_DIR The path to the binary directory currently being processed. -This the full path to the build directory that is currently being +This is the full path to the build directory that is currently being processed by cmake. Each directory added by :command:`add_subdirectory` will 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 diff --git a/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst b/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst index c1b755a..1a25efc 100644 --- a/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst +++ b/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst @@ -3,7 +3,7 @@ CMAKE_CURRENT_SOURCE_DIR The path to the source directory currently being processed. -This the full path to the source directory that is currently being +This is the full path to the source directory that is currently being processed by cmake. When run in -P script mode, CMake sets the variables diff --git a/Help/variable/CMAKE_DOTNET_SDK.rst b/Help/variable/CMAKE_DOTNET_SDK.rst new file mode 100644 index 0000000..dc8806a --- /dev/null +++ b/Help/variable/CMAKE_DOTNET_SDK.rst @@ -0,0 +1,9 @@ +CMAKE_DOTNET_SDK +---------------- + +.. versionadded:: 3.23 + +Default value for :prop_tgt:`DOTNET_SDK` property of targets. + +This variable is used to initialize the :prop_tgt:`DOTNET_SDK` +property on all targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst b/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst new file mode 100644 index 0000000..fa414e4 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst @@ -0,0 +1,27 @@ +CMAKE_FIND_PACKAGE_REDIRECTS_DIR +-------------------------------- + +.. versionadded:: 3.24 + +This read-only variable specifies a directory that the :command:`find_package` +command will check first before searching anywhere else for a module or config +package file. A config package file in this directory will always be found in +preference to any other Find module file or config package file. + +The primary purpose of this variable is to facilitate integration between +:command:`find_package` and :command:`FetchContent_MakeAvailable`. The latter +command may create files in the ``CMAKE_FIND_PACKAGE_REDIRECTS_DIR`` directory +when it populates a dependency. This allows subsequent calls to +:command:`find_package` for the same dependency to re-use the populated +contents instead of trying to satisfy the dependency from somewhere external +to the build. Projects may also want to write files into this directory in +some situations (see :ref:`FetchContent-find_package-integration` for examples). + +The directory that ``CMAKE_FIND_PACKAGE_REDIRECTS_DIR`` points to will always +be erased and recreated empty at the start of every CMake run. Any files +written into this directory during the CMake run will be lost the next time +CMake configures the project. + +``CMAKE_FIND_PACKAGE_REDIRECTS_DIR`` is only set in CMake project mode. +It is not set when CMake is run in script mode +(i.e. :manual:`cmake -P ... <cmake(1)>`). diff --git a/Help/variable/CMAKE_FIND_PACKAGE_TARGETS_GLOBAL.rst b/Help/variable/CMAKE_FIND_PACKAGE_TARGETS_GLOBAL.rst new file mode 100644 index 0000000..58efccf --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_TARGETS_GLOBAL.rst @@ -0,0 +1,10 @@ +CMAKE_FIND_PACKAGE_TARGETS_GLOBAL +--------------------------------- + +Setting to ``TRUE`` promotes all :prop_tgt:`IMPORTED` targets discoverd +by :command:`find_package` to a ``GLOBAL`` scope. + + +Setting this to ``TRUE`` is akin to specifying ``GLOBAL`` +as an argument to :command:`find_package`. +Default value is ``OFF``. diff --git a/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst b/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst index de1bad7..f72fd65 100644 --- a/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst +++ b/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst @@ -20,6 +20,7 @@ take precedence over this variable. See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, +:variable:`CMAKE_FIND_USE_INSTALL_PREFIX`, :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, diff --git a/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst b/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst index 2fd00df..2c1d237 100644 --- a/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst +++ b/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst @@ -20,6 +20,7 @@ take precedence over this variable. See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_INSTALL_PREFIX`, :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, diff --git a/Help/variable/CMAKE_FIND_USE_INSTALL_PREFIX.rst b/Help/variable/CMAKE_FIND_USE_INSTALL_PREFIX.rst new file mode 100644 index 0000000..8494e95 --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_INSTALL_PREFIX.rst @@ -0,0 +1,39 @@ +CMAKE_FIND_USE_INSTALL_PREFIX +----------------------------------- + +.. versionadded:: 3.24 + +Controls the default behavior of the following commands for whether or not to +search the install location: + +* :command:`find_program` +* :command:`find_library` +* :command:`find_file` +* :command:`find_path` +* :command:`find_package` + +This is useful in cross-compiling environments. + +Due to backwards compatibility with :variable:`CMAKE_FIND_NO_INSTALL_PREFIX`, +the behavior of the find command change based on if this variable exists. + +============================== ============================ =========== + CMAKE_FIND_USE_INSTALL_PREFIX CMAKE_FIND_NO_INSTALL_PREFIX Search +============================== ============================ =========== + Not Defined On NO + Not Defined Off || Not Defined YES + Off On NO + Off Off || Not Defined NO + On On YES + On Off || Not Defined YES +============================== ============================ =========== + +By default this variable is not defined. Explicit options given to the above +commands take precedence over this variable. + +See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, +and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst index 3127206..a5eec7a 100644 --- a/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst +++ b/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst @@ -26,6 +26,7 @@ the :ref:`User Package Registry` as if they were called with the See also :ref:`Disabling the Package Registry` and the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_INSTALL_PREFIX`, :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, diff --git a/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst b/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst index 64e5c6d..1f876a9 100644 --- a/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst +++ b/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst @@ -18,6 +18,7 @@ take precedence over this variable. See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_INSTALL_PREFIX`, :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, diff --git a/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst b/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst index a0a86e4..65edd10 100644 --- a/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst +++ b/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst @@ -20,6 +20,7 @@ take precedence over this variable. See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_INSTALL_PREFIX`, :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH`, diff --git a/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst index 504b7e8..2527904 100644 --- a/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst +++ b/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst @@ -27,6 +27,7 @@ See also :ref:`Disabling the Package Registry`. See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_INSTALL_PREFIX`, :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, diff --git a/Help/variable/CMAKE_GENERATOR_INSTANCE.rst b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst index 5858d7a..6bfabe0 100644 --- a/Help/variable/CMAKE_GENERATOR_INSTANCE.rst +++ b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst @@ -18,10 +18,60 @@ variable may initialize ``CMAKE_GENERATOR_INSTANCE`` as a cache entry. Once a given build tree has been initialized with a particular value for this variable, changing the value has undefined behavior. -Instance specification is supported only on specific generators: +Instance specification is supported only on specific generators. -* For the :generator:`Visual Studio 15 2017` generator (and above) - this specifies the absolute path to the VS installation directory - of the selected VS instance. +Visual Studio Instance Selection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -See native build system documentation for allowed instance values. +:ref:`Visual Studio Generators` support instance specification for +Visual Studio 2017 and above. The ``CMAKE_GENERATOR_INSTANCE`` variable +may be set as a cache entry selecting an instance of Visual Studio +via one of the following forms: + +* ``location`` +* ``location[,key=value]*`` +* ``key=value[,key=value]*`` + +The ``location`` specifies the absolute path to the top-level directory +of the VS installation. + +The ``key=value`` pairs form a comma-separated list of options to +specify details of the instance selection. +Supported pairs are: + +``version=<major>.<minor>.<date>.<build>`` + .. versionadded:: 3.23 + + Specify the 4-component VS Build Version, a.k.a. Build Number. + The components are: + + ``<major>.<minor>`` + + The VS major and minor version numbers. + These are the same as the release version numbers. + + ``<date>`` + + A build date in the format ``MMMDD``, where ``MMM`` is a month index + since an epoch used by Microsoft, and ``DD`` is a day in that month. + + ``<build>`` + + A build index on the day represented by ``<date>``. + + The build number is reported by ``vswhere`` as ``installationVersion``. + For example, VS 16.11.10 has build number ``16.11.32126.315``. + +.. versionadded:: 3.23 + + A portable VS instance, which is not known to the Visual Studio Installer, + may be specified by providing both ``location`` and ``version=``. + +If the value of ``CMAKE_GENERATOR_INSTANCE`` is not specified explicitly +by the user or a toolchain file, CMake queries the Visual Studio Installer +to locate VS instances, chooses one, and sets the variable as a cache entry +to hold the value persistently. If an environment variable of the form +``VS##0COMNTOOLS``, where ``##`` the Visual Studio major version number, +is set and points to the ``Common7/Tools`` directory within one of the +VS instances, that instance will be used. Otherwise, if more than one +VS instance is installed we do not define which one is chosen by default. diff --git a/Help/variable/CMAKE_IGNORE_PATH.rst b/Help/variable/CMAKE_IGNORE_PATH.rst index 4bca34b..4b2bd8a 100644 --- a/Help/variable/CMAKE_IGNORE_PATH.rst +++ b/Help/variable/CMAKE_IGNORE_PATH.rst @@ -1,18 +1,18 @@ CMAKE_IGNORE_PATH ----------------- -:ref:`Semicolon-separated list <CMake Language Lists>` of directories to be *ignored* by -the :command:`find_program`, :command:`find_library`, :command:`find_file`, -and :command:`find_path` commands. This is useful in cross-compiling -environments where some system directories contain incompatible but -possibly linkable libraries. For example, on cross-compiled cluster -environments, this allows a user to ignore directories containing -libraries meant for the front-end machine. +.. |CMAKE_IGNORE_VAR| replace:: ``CMAKE_IGNORE_PATH`` +.. |CMAKE_IGNORE_PREFIX_VAR| replace:: :variable:`CMAKE_IGNORE_PREFIX_PATH` -By default this is empty; it is intended to be set by the project. -Note that ``CMAKE_IGNORE_PATH`` takes a list of directory names, *not* -a list of prefixes. To ignore paths under prefixes (``bin``, ``include``, -``lib``, etc.), specify them explicitly. +.. include:: IGNORE_SEARCH_PATH.txt +.. include:: IGNORE_SEARCH_LOCATIONS.txt +.. include:: IGNORE_SEARCH_NONSYSTEM.txt -See also the :variable:`CMAKE_PREFIX_PATH`, :variable:`CMAKE_LIBRARY_PATH`, -:variable:`CMAKE_INCLUDE_PATH`, and :variable:`CMAKE_PROGRAM_PATH` variables. +See also the following variables: + +- :variable:`CMAKE_IGNORE_PREFIX_PATH` +- :variable:`CMAKE_SYSTEM_IGNORE_PATH` +- :variable:`CMAKE_PREFIX_PATH` +- :variable:`CMAKE_LIBRARY_PATH` +- :variable:`CMAKE_INCLUDE_PATH` +- :variable:`CMAKE_PROGRAM_PATH` diff --git a/Help/variable/CMAKE_IGNORE_PREFIX_PATH.rst b/Help/variable/CMAKE_IGNORE_PREFIX_PATH.rst new file mode 100644 index 0000000..b81cc57 --- /dev/null +++ b/Help/variable/CMAKE_IGNORE_PREFIX_PATH.rst @@ -0,0 +1,20 @@ +CMAKE_IGNORE_PREFIX_PATH +------------------------ + +.. versionadded:: 3.23 + +.. |CMAKE_IGNORE_VAR| replace:: ``CMAKE_IGNORE_PREFIX_PATH`` +.. |CMAKE_IGNORE_NONPREFIX_VAR| replace:: :variable:`CMAKE_IGNORE_PATH` + +.. include:: IGNORE_SEARCH_PREFIX.txt +.. include:: IGNORE_SEARCH_LOCATIONS.txt +.. include:: IGNORE_SEARCH_NONSYSTEM.txt + +See also the following variables: + +- :variable:`CMAKE_IGNORE_PATH` +- :variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` +- :variable:`CMAKE_PREFIX_PATH` +- :variable:`CMAKE_LIBRARY_PATH` +- :variable:`CMAKE_INCLUDE_PATH` +- :variable:`CMAKE_PROGRAM_PATH` diff --git a/Help/variable/CMAKE_INSTALL_PREFIX.rst b/Help/variable/CMAKE_INSTALL_PREFIX.rst index 02ba645..6d42ea8 100644 --- a/Help/variable/CMAKE_INSTALL_PREFIX.rst +++ b/Help/variable/CMAKE_INSTALL_PREFIX.rst @@ -10,14 +10,26 @@ See :variable:`CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT` for how a project might choose its own default. On UNIX one can use the ``DESTDIR`` mechanism in order to relocate the -whole installation. See :envvar:`DESTDIR` for more information. +whole installation to a staging area. See the :envvar:`DESTDIR` environment +variable for more information. The installation prefix is also added to :variable:`CMAKE_SYSTEM_PREFIX_PATH` so that :command:`find_package`, :command:`find_program`, :command:`find_library`, :command:`find_path`, and :command:`find_file` -will search the prefix for other software. +will search the prefix for other software. This behavior can be disabled by +setting the :variable:`CMAKE_FIND_NO_INSTALL_PREFIX` to ``TRUE`` before the +first :command:`project` invocation. .. note:: Use the :module:`GNUInstallDirs` module to provide GNU-style options for the layout of directories within the installation. + +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 ``--install`` mode, one may specify a different prefix +using the ``--prefix`` option: + +.. code-block:: shell + + cmake --install . --prefix /my/install/prefix diff --git a/Help/variable/CMAKE_LANG_COMPILER_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_ID.rst index 0abedde..cd7d5cd 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_ID.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_ID.rst @@ -28,6 +28,7 @@ include: IAR = IAR Systems (iar.com) Intel = Intel Compiler (intel.com) IntelLLVM = Intel LLVM-Based Compiler (intel.com) + LCC = MCST Elbrus C/C++/Fortran Compiler (mcst.ru) MSVC = Microsoft Visual Studio (microsoft.com) NVHPC = NVIDIA HPC SDK Compiler (nvidia.com) NVIDIA = NVIDIA CUDA Compiler (nvidia.com) @@ -40,6 +41,7 @@ include: TinyCC = Tiny C Compiler (tinycc.org) XL, VisualAge, zOS = IBM XL (ibm.com) XLClang = IBM Clang-based XL (ibm.com) + IBMClang = IBM LLVM-based Compiler (ibm.com) This variable is not guaranteed to be defined for all compilers or languages. diff --git a/Help/variable/CMAKE_LANG_LINKER_PREFERENCE.rst b/Help/variable/CMAKE_LANG_LINKER_PREFERENCE.rst index ff82f8b..a4035bd 100644 --- a/Help/variable/CMAKE_LANG_LINKER_PREFERENCE.rst +++ b/Help/variable/CMAKE_LANG_LINKER_PREFERENCE.rst @@ -1,6 +1,8 @@ CMAKE_<LANG>_LINKER_PREFERENCE ------------------------------ +An internal variable subject to change. + Preference value for linker language selection. The "linker language" for executable, shared library, and module diff --git a/Help/variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES.rst b/Help/variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES.rst index dbbeb0a..df33edb 100644 --- a/Help/variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES.rst +++ b/Help/variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES.rst @@ -1,6 +1,8 @@ CMAKE_<LANG>_LINKER_PREFERENCE_PROPAGATES ----------------------------------------- +An internal variable subject to change. + True if :variable:`CMAKE_<LANG>_LINKER_PREFERENCE` propagates across targets. This is used when CMake selects a linker language for a target. diff --git a/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE.rst b/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE.rst new file mode 100644 index 0000000..f2ef843 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE.rst @@ -0,0 +1,27 @@ +CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE> +--------------------------------------- + +.. versionadded:: 3.24 + +This variable defines, for the specified ``<FEATURE>`` and the linker language +``<LANG>``, the expression expected by the linker when libraries are specified +using :genex:`LINK_GROUP` generator expression. + +.. note:: + + * Feature names can contain Latin letters, digits and undercores. + * Feature names defined in all uppercase are reserved to CMake. + +See also the associated variable +:variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` and +:variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` variable for the definition of +features independent from the link language. + +.. include:: CMAKE_LINK_GROUP_USING_FEATURE.txt + +Predefined Features +^^^^^^^^^^^^^^^^^^^ + +CMake pre-defines some features of general interest: + +.. include:: LINK_GROUP_PREDEFINED_FEATURES.txt diff --git a/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE_SUPPORTED.rst b/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE_SUPPORTED.rst new file mode 100644 index 0000000..533eee7 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE_SUPPORTED.rst @@ -0,0 +1,13 @@ +CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED +------------------------------------------------- + +.. versionadded:: 3.24 + +Set to ``TRUE`` if the ``<FEATURE>``, as defined by variable +:variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>`, is supported for the +linker language ``<LANG>``. + +.. note:: + + This variable is evaluated before the more generic variable + :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED`. diff --git a/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE.rst b/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE.rst new file mode 100644 index 0000000..220ae99 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE.rst @@ -0,0 +1,27 @@ +CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE> +----------------------------------------- + +.. versionadded:: 3.24 + +This variable defines, for the specified ``<FEATURE>`` and the linker language +``<LANG>``, the expression expected by the linker when libraries are specified +using :genex:`LINK_LIBRARY` generator expression. + +.. note:: + + * Feature names can contain Latin letters, digits and undercores. + * Feature names defined in all uppercase are reserved to CMake. + +See also the associated variable +:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` and +:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variable for the definition of +features independent from the link language. + +.. include:: CMAKE_LINK_LIBRARY_USING_FEATURE.txt + +Predefined Features +^^^^^^^^^^^^^^^^^^^ + +CMake pre-defines some features of general interest: + +.. include:: LINK_LIBRARY_PREDEFINED_FEATURES.txt diff --git a/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE_SUPPORTED.rst b/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE_SUPPORTED.rst new file mode 100644 index 0000000..e595bc7 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE_SUPPORTED.rst @@ -0,0 +1,13 @@ +CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED +--------------------------------------------------- + +.. versionadded:: 3.24 + +Set to ``TRUE`` if the ``<FEATURE>``, as defined by variable +:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>`, is supported for the +linker language ``<LANG>``. + +.. note:: + + This variable is evaluated before the more generic variable + :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED`. diff --git a/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.rst b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.rst new file mode 100644 index 0000000..692c099 --- /dev/null +++ b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.rst @@ -0,0 +1,33 @@ +CMAKE_LINK_GROUP_USING_<FEATURE> +-------------------------------- + +.. versionadded:: 3.24 + +This variable defines, for the specified ``<FEATURE>``, the expression expected +by the linker when libraries are specified using :genex:`LINK_GROUP` generator +expression. + +.. note:: + + * Feature names can contain Latin letters, digits and undercores. + * Feature names defined in all uppercase are reserved to CMake. + +See also the associated variable +:variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED` and +:variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` variable for the definition +of features dependent from the link language. + +This variable will be used by :genex:`LINK_GROUP` generator expression if, +for the linker language, the variable +:variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` is not defined +and the variable :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED` is +``TRUE``.. + +.. include:: CMAKE_LINK_GROUP_USING_FEATURE.txt + +Predefined Features +^^^^^^^^^^^^^^^^^^^ + +CMake pre-defines some features of general interest: + +.. include:: LINK_GROUP_PREDEFINED_FEATURES.txt diff --git a/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.txt b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.txt new file mode 100644 index 0000000..ecd9cb5 --- /dev/null +++ b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.txt @@ -0,0 +1,54 @@ + +It must contain two elements. + +:: + + <PREFIX> <SUFFIX> + +``<PREFIX>`` and ``<SUFFIX>`` will be used to encapsulate the list of +libraries. + +For the elements of this variable, the ``LINKER:`` prefix can be used: + + .. include:: ../command/LINK_OPTIONS_LINKER.txt + :start-line: 3 + +Examples +^^^^^^^^ + +Solving cross-references between two static libraries +""""""""""""""""""""""""""""""""""""""""""""""""""""" + +A common need is the capability to search repeatedly in a group of static +libraries until no new undefined references are created. This capability is +offered by different environments but with a specific syntax: + +.. code-block:: cmake + + set(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED TRUE) + if(CMAKE_C_COMPILER_ID STREQUAL "GNU" + AND CMAKE_SYSTEM_NAME STREQUAL "Linux") + set(CMAKE_C_LINK_GROUP_USING_cross_refs "LINKER:--start-group" + "LINKER:--end-group") + elseif(CMAKE_C_COMPILER_ID STREQUAL "SunPro" + AND CMAKE_SYSTEM_NAME STREQUAL "SunOS") + set(CMAKE_C_LINK_GROUP_USING_cross_refs "LINKER:-z,rescan-start" + "LINKER:-z,rescan-end") + else() + # feature not yet supported for the other environments + set(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED FALSE) + endif() + + add_library(lib1 STATIC ...) + + add_library(lib3 SHARED ...) + if(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED) + target_link_libraries(lib3 PRIVATE "$<LINK_GROUP:cross_refs,lib1,external>") + else() + target_link_libraries(lib3 PRIVATE lib1 external) + endif() + +CMake will generate the following link expressions: + +* ``GNU``: ``-Wl,--start-group /path/to/lib1.a -lexternal -Wl,--end-group`` +* ``SunPro``: ``-Wl,-z,rescan-start /path/to/lib1.a -lexternal -Wl,-z,rescan-end`` diff --git a/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED.rst b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED.rst new file mode 100644 index 0000000..318892f --- /dev/null +++ b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED.rst @@ -0,0 +1,13 @@ +CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED +------------------------------------------ + +.. versionadded:: 3.24 + +Set to ``TRUE`` if the ``<FEATURE>``, as defined by variable +:variable:`CMAKE_LINK_GROUP_USING_<FEATURE>`, is supported regardless the +linker language. + +.. note:: + + This variable is evaluated if, and only if, the variable + :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` is not defined. diff --git a/Help/variable/CMAKE_LINK_LIBRARIES_ONLY_TARGETS.rst b/Help/variable/CMAKE_LINK_LIBRARIES_ONLY_TARGETS.rst new file mode 100644 index 0000000..513c3d0 --- /dev/null +++ b/Help/variable/CMAKE_LINK_LIBRARIES_ONLY_TARGETS.rst @@ -0,0 +1,10 @@ +CMAKE_LINK_LIBRARIES_ONLY_TARGETS +--------------------------------- + +.. versionadded:: 3.23 + +Set this variable to initialize the :prop_tgt:`LINK_LIBRARIES_ONLY_TARGETS` +property of non-imported targets when they are created. Setting it to true +enables an additional check that all items named by +:command:`target_link_libraries` that can be target names are actually names +of existing targets. See the target property documentation for details. diff --git a/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.rst b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.rst new file mode 100644 index 0000000..9f1cede --- /dev/null +++ b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.rst @@ -0,0 +1,33 @@ +CMAKE_LINK_LIBRARY_USING_<FEATURE> +---------------------------------- + +.. versionadded:: 3.24 + +This variable defines, for the specified ``FEATURE``, the expression expected +by the linker, regardless the linker language, when libraries are specified +using :genex:`LINK_LIBRARY` generator expression. + +.. note:: + + * Feature names can contain Latin letters, digits and undercores. + * Feature names defined in all uppercase are reserved to CMake. + +See also the associated variable +:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` and +:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` variable for the +definition of features dependent from the link language. + +This variable will be used by :genex:`LINK_LIBRARY` generator expression if, +for the linker language, the variable +:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` is not defined +and the variable :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` is +``TRUE``. + +.. include:: CMAKE_LINK_LIBRARY_USING_FEATURE.txt + +Predefined Features +^^^^^^^^^^^^^^^^^^^ + +CMake pre-defines some features of general interest: + +.. include:: LINK_LIBRARY_PREDEFINED_FEATURES.txt diff --git a/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.txt b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.txt new file mode 100644 index 0000000..ec293d3 --- /dev/null +++ b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.txt @@ -0,0 +1,112 @@ + +It can contain one or three elements. + +:: + + [<PREFIX>] <LIBRARY_EXPRESSION> [<SUFFIX>] + +When ``<PREFIX>`` and/or ``<SUFFIX>`` are specified, they encapsulate the list +of libraries. + +.. note:: + + Even if ``<PREFIX>`` and ``<SUFFIX>`` are specified, there is not guarantee + that the list of specified libraries, as part of :genex:`LINK_LIBRARY` + generator expression, will be kept grouped. So, constructs like + ``start-group`` and ``end-group``, as supported by ``GNU ld``, cannot be + used. + +``<LIBRARY_EXPRESSION>`` is used to specify the decoration for each +library. For that purpose, the patterns ``<LIBRARY>``, ``<LINK_ITEM>``, and +``<LIB_ITEM>`` are available: + +* ``<LIBRARY>`` is expanded to the library as computed by CMake. +* ``<LINK_ITEM>`` is expanded to the same expression as if the library was + specified in the standard way. +* ``<LIB_ITEM>`` is equivalent to ``<LIBRARY>`` for CMake targets and is + expanded to the item specified by the user for external libraries. + +Moreover, it is possible to have different decorations for paths (CMake targets +and external libraries specified with absolute paths) and other items specified +by name. For that purpose, ``PATH{}`` and ``NAME{}`` wrappers can be used. + +For all three elements of this variable, the ``LINKER:`` prefix can be used: + + .. include:: ../command/LINK_OPTIONS_LINKER.txt + :start-line: 3 + +Examples +^^^^^^^^ + +Loading a whole static library +"""""""""""""""""""""""""""""" + +A common need is the capability to load a whole static library. This capability +is offered by various environments but with a specific syntax: + +.. code-block:: cmake + + set(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED TRUE) + if(CMAKE_C_COMPILER_ID STREQUAL "AppleClang") + set(CMAKE_C_LINK_LIBRARY_USING_load_archive "-force_load <LIB_ITEM>") + elseif(CMAKE_C_COMPILER_ID STREQUAL "GNU" + AND CMAKE_SYSTEM_NAME STREQUAL "Linux") + set(CMAKE_C_LINK_LIBRARY_USING_load_archive "LINKER:--push-state,--whole-archive" + "<LINK_ITEM>" + "LINKER:--pop-state") + elseif(CMAKE_C_COMPILER_ID STREQUAL "MSVC") + set(CMAKE_C_LINK_LIBRARY_USING_load_archive "/WHOLEARCHIVE:<LIBRARY>") + else() + # feature not yet supported for the other environments + set(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED FALSE) + endif() + + add_library(lib1 STATIC ...) + + add_library(lib2 SHARED ...) + if(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED) + target_link_libraries(lib2 PRIVATE + "$<LINK_LIBRARY:load_archive,lib1,$<IF:$<LINK_LANG_AND_ID:C,Clang>,libexternal.a,external>>") + else() + target_link_libraries(lib2 PRIVATE lib1 external) + endif() + +CMake will generate the following link expressions: + +* ``Clang``: ``-force_load /path/to/lib1.a -force_load libexternal.a`` +* ``GNU``: ``-Wl,--whole-archive /path/to/lib1.a -lexternal -Wl,--no-whole-archive`` +* ``MSVC``: ``/WHOLEARCHIVE:/path/to/lib1.lib /WHOLEARCHIVE:external.lib`` + +CMake will ensure, when possible, that ``<PREFIX>`` and ``<SUFFIX>`` are +not repeated for each library. + +In case of ``Clang``, the pattern ``<LIB_ITEM>`` is used because we need to +specify the library as defined by the user, not the name computed by CMake +(in that case ``external``). + +Linking a library as weak +""""""""""""""""""""""""" + +On MacOS, it is possible to link a library in weak mode (the library and all +references are marked as weak imports), but different flags must be used for a +library specified by path and by name. This constraint by be solved by using +``PATH{}`` and ``NAME{}`` wrappers: + +.. code-block:: cmake + + if (CMAKE_C_COMPILER_ID STREQUAL "AppleClang") + set(CMAKE_LINK_LIBRARY_USING_weak_library + "PATH{-weak_library <LIBRARY>}NAME{LINKER:-weak-l<LIB_ITEM>}") + set(CMAKE_LINK_LIBRARY_USING_weak_library_SUPPORTED TRUE) + endif() + + add_library(lib SHARED ...) + add_executable(main ...) + if(CMAKE_LINK_LIBRARY_USING_weak_library_SUPPORTED) + target_link_libraries(main PRIVATE "$<LINK_LIBRARY:weak_library,lib,external>") + else() + target_link_libraries(main PRIVATE lib external) + endif() + +CMake will generate the following link expression: +``-weak_library /path/to/lib -Xlinker -weak-lexternal`` diff --git a/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE_SUPPORTED.rst b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE_SUPPORTED.rst new file mode 100644 index 0000000..417724b --- /dev/null +++ b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE_SUPPORTED.rst @@ -0,0 +1,14 @@ +CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED +-------------------------------------------- + +.. versionadded:: 3.24 + +Set to ``TRUE`` if the ``<FEATURE>``, as defined by variable +:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>`, is supported regardless the +linker language. + +.. note:: + + This variable is evaluated if, and only if, the variable + :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` is not + defined. diff --git a/Help/variable/CMAKE_PLATFORM_NO_VERSIONED_SONAME.rst b/Help/variable/CMAKE_PLATFORM_NO_VERSIONED_SONAME.rst new file mode 100644 index 0000000..bf15fc8 --- /dev/null +++ b/Help/variable/CMAKE_PLATFORM_NO_VERSIONED_SONAME.rst @@ -0,0 +1,14 @@ +CMAKE_PLATFORM_NO_VERSIONED_SONAME +---------------------------------- + +.. versionadded:: 3.1 + +This variable is used to globally control whether the +:prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` target +properties should be used for shared libraries. +When set to true, adding version information to each +shared library target is disabled. + +By default this variable is set only on platforms where +CMake knows it is needed. On other platforms, the +specified properties will be used for shared libraries. diff --git a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst index 0231668..9dce760 100644 --- a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst @@ -34,6 +34,10 @@ only for the policies that do not warn by default: policy :policy:`CMP0126`. * ``CMAKE_POLICY_WARNING_CMP0128`` controls the warning for policy :policy:`CMP0128`. +* ``CMAKE_POLICY_WARNING_CMP0129`` controls the warning for + policy :policy:`CMP0129`. +* ``CMAKE_POLICY_WARNING_CMP0133`` controls the warning for + policy :policy:`CMP0133`. This variable should not be set by a project in CMake code. Project developers running CMake may set this variable in their cache to diff --git a/Help/variable/CMAKE_PROJECT_INCLUDE.rst b/Help/variable/CMAKE_PROJECT_INCLUDE.rst index 41d9e5d..76b9d92 100644 --- a/Help/variable/CMAKE_PROJECT_INCLUDE.rst +++ b/Help/variable/CMAKE_PROJECT_INCLUDE.rst @@ -5,8 +5,11 @@ CMAKE_PROJECT_INCLUDE A CMake language file or module to be included as the last step of all :command:`project` command calls. This is intended for injecting custom code -into project builds without modifying their source. +into project builds without modifying their source. See :ref:`Code Injection` +for a more detailed discussion of files potentially included during a +:command:`project` call. See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, -:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` and -:variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables. +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`, +:variable:`CMAKE_PROJECT_INCLUDE_BEFORE`, and +:variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variables. diff --git a/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst b/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst index c2fd0f8..9a8c4b5 100644 --- a/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst +++ b/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst @@ -5,8 +5,11 @@ CMAKE_PROJECT_INCLUDE_BEFORE A CMake language file or module to be included as the first step of all :command:`project` command calls. This is intended for injecting custom code -into project builds without modifying their source. +into project builds without modifying their source. See :ref:`Code Injection` +for a more detailed discussion of files potentially included during a +:command:`project` call. See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, -:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` and -:variable:`CMAKE_PROJECT_INCLUDE` variables. +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`, +:variable:`CMAKE_PROJECT_INCLUDE`, and +:variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variables. diff --git a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst index 74247f1..3bb5cd8 100644 --- a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst +++ b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst @@ -4,8 +4,9 @@ CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE A CMake language file or module to be included as the last step of any :command:`project` command calls that specify ``<PROJECT-NAME>`` as the project name. This is intended for injecting custom code into project builds without -modifying their source. +modifying their source. See :ref:`Code Injection` for a more detailed +discussion of files potentially included during a :command:`project` call. See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`, -:variable:`CMAKE_PROJECT_INCLUDE` and -:variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables. +:variable:`CMAKE_PROJECT_INCLUDE`, :variable:`CMAKE_PROJECT_INCLUDE_BEFORE`, +and :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variables. diff --git a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst index 39abb12..ca584c1 100644 --- a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst +++ b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst @@ -6,8 +6,9 @@ CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE A CMake language file or module to be included as the first step of any :command:`project` command calls that specify ``<PROJECT-NAME>`` as the project name. This is intended for injecting custom code into project builds without -modifying their source. +modifying their source. See :ref:`Code Injection` for a more detailed +discussion of files potentially included during a :command:`project` call. See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, -:variable:`CMAKE_PROJECT_INCLUDE` and -:variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables. +:variable:`CMAKE_PROJECT_INCLUDE`, :variable:`CMAKE_PROJECT_INCLUDE_BEFORE`, +and :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variables. diff --git a/Help/variable/CMAKE_PROJECT_TOP_LEVEL_INCLUDES.rst b/Help/variable/CMAKE_PROJECT_TOP_LEVEL_INCLUDES.rst new file mode 100644 index 0000000..2010b08 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_TOP_LEVEL_INCLUDES.rst @@ -0,0 +1,27 @@ +CMAKE_PROJECT_TOP_LEVEL_INCLUDES +-------------------------------- + +.. versionadded:: 3.24 + +:ref:`Semicolon-separated list <CMake Language Lists>` of CMake language +files to include as part of the very first :command:`project` call. +The files will be included immediately after the toolchain file has been read +(if one is specified) and platform variables have been set, but before any +languages have been enabled. Therefore, language-specific variables, +including things like :variable:`CMAKE_<LANG>_COMPILER`, might not be set. +See :ref:`Code Injection` for a more detailed discussion of files potentially +included during a :command:`project` call. + +This variable is intended for specifying files that perform one-time setup +for the build. It provides an injection point for things like configuring +package managers, adding logic the user shares between projects (e.g. defining +their own custom build types), and so on. It is primarily for users to add +things specific to their environment, but not for specifying the toolchain +details (use :variable:`CMAKE_TOOLCHAIN_FILE` for that). + +By default, this variable is empty. It is intended to be set by the user. + +See also the :variable:`CMAKE_PROJECT_INCLUDE`, +:variable:`CMAKE_PROJECT_INCLUDE_BEFORE`, +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, and +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` variables. diff --git a/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst b/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst index 6afbd33..a6d8016 100644 --- a/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst +++ b/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst @@ -1,18 +1,18 @@ CMAKE_SYSTEM_IGNORE_PATH ------------------------ -:ref:`Semicolon-separated list <CMake Language Lists>` of directories to be *ignored* by -the :command:`find_program`, :command:`find_library`, :command:`find_file`, -and :command:`find_path` commands. This is useful in cross-compiling -environments where some system directories contain incompatible but -possibly linkable libraries. For example, on cross-compiled cluster -environments, this allows a user to ignore directories containing -libraries meant for the front-end machine. +.. |CMAKE_IGNORE_VAR| replace:: ``CMAKE_SYSTEM_IGNORE_PATH`` +.. |CMAKE_IGNORE_PREFIX_VAR| replace:: :variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` +.. |CMAKE_IGNORE_NONSYSTEM_VAR| replace:: :variable:`CMAKE_IGNORE_PATH` -By default this contains a list of directories containing incompatible -binaries for the host system. See the :variable:`CMAKE_IGNORE_PATH` variable -that is intended to be set by the project. +.. include:: IGNORE_SEARCH_PATH.txt +.. include:: IGNORE_SEARCH_LOCATIONS.txt +.. include:: IGNORE_SEARCH_SYSTEM.txt -See also the :variable:`CMAKE_SYSTEM_PREFIX_PATH`, -:variable:`CMAKE_SYSTEM_LIBRARY_PATH`, :variable:`CMAKE_SYSTEM_INCLUDE_PATH`, -and :variable:`CMAKE_SYSTEM_PROGRAM_PATH` variables. +See also the following variables: + +- :variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` +- :variable:`CMAKE_SYSTEM_PREFIX_PATH` +- :variable:`CMAKE_SYSTEM_LIBRARY_PATH` +- :variable:`CMAKE_SYSTEM_INCLUDE_PATH` +- :variable:`CMAKE_SYSTEM_PROGRAM_PATH` diff --git a/Help/variable/CMAKE_SYSTEM_IGNORE_PREFIX_PATH.rst b/Help/variable/CMAKE_SYSTEM_IGNORE_PREFIX_PATH.rst new file mode 100644 index 0000000..48a2994 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_IGNORE_PREFIX_PATH.rst @@ -0,0 +1,20 @@ +CMAKE_SYSTEM_IGNORE_PREFIX_PATH +------------------------------- + +.. versionadded:: 3.23 + +.. |CMAKE_IGNORE_VAR| replace:: ``CMAKE_SYSTEM_IGNORE_PREFIX_PATH`` +.. |CMAKE_IGNORE_NONPREFIX_VAR| replace:: :variable:`CMAKE_SYSTEM_IGNORE_PATH` +.. |CMAKE_IGNORE_NONSYSTEM_VAR| replace:: :variable:`CMAKE_IGNORE_PREFIX_PATH` + +.. include:: IGNORE_SEARCH_PREFIX.txt +.. include:: IGNORE_SEARCH_LOCATIONS.txt +.. include:: IGNORE_SEARCH_SYSTEM.txt + +See also the following variables: + +- :variable:`CMAKE_SYSTEM_IGNORE_PATH` +- :variable:`CMAKE_SYSTEM_PREFIX_PATH` +- :variable:`CMAKE_SYSTEM_LIBRARY_PATH` +- :variable:`CMAKE_SYSTEM_INCLUDE_PATH` +- :variable:`CMAKE_SYSTEM_PROGRAM_PATH` diff --git a/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst index 81a7a0b..c8b5815 100644 --- a/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst +++ b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst @@ -11,7 +11,8 @@ documentation. By default this contains the system directories for the current system, the :variable:`CMAKE_INSTALL_PREFIX`, and the :variable:`CMAKE_STAGING_PREFIX`. The installation and staging prefixes may be excluded by setting -the :variable:`CMAKE_FIND_NO_INSTALL_PREFIX` variable. +the :variable:`CMAKE_FIND_NO_INSTALL_PREFIX` variable before the +first :command:`project` invocation. The system directories that are contained in ``CMAKE_SYSTEM_PREFIX_PATH`` are locations that typically include installed software. An example being diff --git a/Help/variable/CMAKE_TOOLCHAIN_FILE.rst b/Help/variable/CMAKE_TOOLCHAIN_FILE.rst index ff8d59a..1117c1f 100644 --- a/Help/variable/CMAKE_TOOLCHAIN_FILE.rst +++ b/Help/variable/CMAKE_TOOLCHAIN_FILE.rst @@ -13,3 +13,6 @@ build directory, and if not found, relative to the source directory. This is initialized by the :envvar:`CMAKE_TOOLCHAIN_FILE` environment variable if it is set when a new build tree is first created. + +See the :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable for setting +other things not directly related to the toolchain. diff --git a/Help/variable/CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES.rst b/Help/variable/CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES.rst new file mode 100644 index 0000000..944caa5 --- /dev/null +++ b/Help/variable/CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES.rst @@ -0,0 +1,10 @@ +CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES +--------------------------------------- + +Set to a true value to tell the :command:`try_compile` command not +to propagate any platform variables into the test project. + +The :command:`try_compile` command normally passes some CMake variables +that configure the platform and toolchain behavior into test projects. +See policy :policy:`CMP0137`. This variable may be set to disable +that behavior. diff --git a/Help/variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES.rst b/Help/variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES.rst index d178513..6b26d14 100644 --- a/Help/variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES.rst +++ b/Help/variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES.rst @@ -26,3 +26,12 @@ If a user passes ``-DMY_CUSTOM_VARIABLE=SomeValue`` to CMake then this setting will be made visible to the toolchain file both for the main project and for test projects generated by the :command:`try_compile` command source file signature. + +.. versionchanged:: 3.24 + Listed variables are propagated to the :command:`try_compile` + :ref:`whole-project <Try Compiling Whole Projects>` signature too. + See :policy:`CMP0137`. + +.. versionadded:: 3.24 + The :variable:`CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES` variable may be + set to disable passing platform variables into the test project. diff --git a/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE.rst b/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE.rst index 622278e..71c06cf 100644 --- a/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE.rst +++ b/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE.rst @@ -8,6 +8,8 @@ language from either the :command:`project` or :command:`enable_language` commands. It is loaded after CMake's builtin compiler and platform information modules have been loaded but before the information is used. The file may set platform information variables to override CMake's defaults. +See :variable:`CMAKE_USER_MAKE_RULES_OVERRIDE_<LANG>` for the language-specific +version of this variable. This feature is intended for use only in overriding information variables that must be set before CMake builds its first test project diff --git a/Help/variable/CMAKE_VERIFY_INTERFACE_HEADER_SETS.rst b/Help/variable/CMAKE_VERIFY_INTERFACE_HEADER_SETS.rst new file mode 100644 index 0000000..6f14e6f --- /dev/null +++ b/Help/variable/CMAKE_VERIFY_INTERFACE_HEADER_SETS.rst @@ -0,0 +1,17 @@ +CMAKE_VERIFY_INTERFACE_HEADER_SETS +---------------------------------- + +.. versionadded:: 3.24 + +This variable is used to initialize the +:prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` property of targets when they are +created. Setting it to true enables header set verification. + +Projects should not set this variable, it is intended as a developer +control to be set on the :manual:`cmake(1)` command line or other +equivalent methods. The developer must have the ability to enable or +disable header set verification according to the capabilities of their own +machine and compiler. + +By default, this variable is not set, which will result in header set +verification being disabled. diff --git a/Help/variable/CMAKE_VS_NUGET_PACKAGE_RESTORE.rst b/Help/variable/CMAKE_VS_NUGET_PACKAGE_RESTORE.rst new file mode 100644 index 0000000..7160726 --- /dev/null +++ b/Help/variable/CMAKE_VS_NUGET_PACKAGE_RESTORE.rst @@ -0,0 +1,22 @@ +CMAKE_VS_NUGET_PACKAGE_RESTORE +------------------------------ + +.. versionadded:: 3.23 + +When using a Visual Studio generator, this cache variable controls +if msbuild should automatically attempt to restore NuGet packages +prior to a build. NuGet packages can be defined using the +:prop_tgt:`VS_PACKAGE_REFERENCES` property on a target. If no +package references are defined, this setting will do nothing. + +The command line option ``--resolve-package-references`` can be used +alternatively to control the resolve behavior globally. This option +will take precedence over the cache variable. + +Targets that use the :prop_tgt:`DOTNET_SDK` are required to run a +restore before building. Disabling this option may cause the build +to fail in such projects. + +This setting is stored as a cache entry. Default value is ``ON``. + +See also the :prop_tgt:`VS_PACKAGE_REFERENCES` property. diff --git a/Help/variable/CMAKE_WATCOM_RUNTIME_LIBRARY.rst b/Help/variable/CMAKE_WATCOM_RUNTIME_LIBRARY.rst new file mode 100644 index 0000000..feb2a60 --- /dev/null +++ b/Help/variable/CMAKE_WATCOM_RUNTIME_LIBRARY.rst @@ -0,0 +1,36 @@ +CMAKE_WATCOM_RUNTIME_LIBRARY +---------------------------- + +.. versionadded:: 3.24 + +Select the Watcom runtime library for use by compilers targeting the Watcom ABI. +This variable is used to initialize the :prop_tgt:`WATCOM_RUNTIME_LIBRARY` +property on all targets as they are created. It is also propagated by +calls to the :command:`try_compile` command into the test project. + +The allowed values are: + +.. include:: ../prop_tgt/WATCOM_RUNTIME_LIBRARY-VALUES.txt + +Use :manual:`generator expressions <cmake-generator-expressions(7)>` to +support per-configuration specification. + +For example, the code: + +.. code-block:: cmake + + set(CMAKE_WATCOM_RUNTIME_LIBRARY "MultiThreaded") + +selects for all following targets a multi-threaded statically-linked runtime +library. + +If this variable is not set then the :prop_tgt:`WATCOM_RUNTIME_LIBRARY` target +property will not be set automatically. If that property is not set then +CMake uses the default value ``MultiThreadedDLL`` on Windows and +``SingleThreaded`` on other platforms to select a Watcom runtime library. + +.. note:: + + This variable has effect only when policy :policy:`CMP0136` is set to ``NEW`` + prior to the first :command:`project` or :command:`enable_language` command + that enables a language using a compiler targeting the Watcom ABI. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE.rst b/Help/variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE.rst new file mode 100644 index 0000000..3a3c847 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE.rst @@ -0,0 +1,15 @@ +CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE +------------------------------------------------ + +.. versionadded:: 3.23 + +Property value for ``GPU Frame Capture`` in the Options section of +the generated Xcode scheme. Example values are `Metal` and +`Disabled`. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_XCCONFIG.rst b/Help/variable/CMAKE_XCODE_XCCONFIG.rst new file mode 100644 index 0000000..6b1ef30 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_XCCONFIG.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_XCCONFIG +-------------------- + +.. versionadded:: 3.24 + +If set, the :generator:`Xcode` generator will register the specified +file as a global XCConfig file. For target-level XCConfig files see +the :prop_tgt:`XCODE_XCCONFIG` target property. + +This feature is intended to ease migration from native Xcode projects +to CMake projects. + +Contents of ``CMAKE_XCODE_XCCONFIG`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst b/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst index 7e7d431..007cfe0 100644 --- a/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst +++ b/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst @@ -3,7 +3,8 @@ CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE When saving a failing test's output, this is the maximum size, in bytes, that will be collected by the :command:`ctest_test` command. Defaults to 307200 -(300 KiB). +(300 KiB). See :variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` for possible +truncation modes. If a test's output contains the literal string "CTEST_FULL_OUTPUT", the output will not be truncated and may exceed the maximum size. diff --git a/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst b/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst index 64367f9..8545fc4 100644 --- a/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst +++ b/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst @@ -3,7 +3,8 @@ CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE When saving a passing test's output, this is the maximum size, in bytes, that will be collected by the :command:`ctest_test` command. Defaults to 1024 -(1 KiB). +(1 KiB). See :variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` for possible +truncation modes. If a test's output contains the literal string "CTEST_FULL_OUTPUT", the output will not be truncated and may exceed the maximum size. diff --git a/Help/variable/CTEST_CUSTOM_TESTS_IGNORE.rst b/Help/variable/CTEST_CUSTOM_TESTS_IGNORE.rst index 57222ca..7b1a4b8 100644 --- a/Help/variable/CTEST_CUSTOM_TESTS_IGNORE.rst +++ b/Help/variable/CTEST_CUSTOM_TESTS_IGNORE.rst @@ -1,7 +1,7 @@ CTEST_CUSTOM_TESTS_IGNORE ------------------------- -A list of regular expressions to use to exclude tests during the +A list of test names to be excluded from the set of tests run by the :command:`ctest_test` command. .. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION.rst b/Help/variable/CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION.rst new file mode 100644 index 0000000..2d4219e --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION.rst @@ -0,0 +1,12 @@ +CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION +----------------------------------- + +.. versionadded:: 3.24 + +Set the test output truncation mode in case a maximum size is configured +via the :variable:`CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE` or +:variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE` variables. +By default the ``tail`` of the output will be truncated. Other possible +values are ``middle`` and ``head``. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_SUBMIT_INACTIVITY_TIMEOUT.rst b/Help/variable/CTEST_SUBMIT_INACTIVITY_TIMEOUT.rst new file mode 100644 index 0000000..175885a --- /dev/null +++ b/Help/variable/CTEST_SUBMIT_INACTIVITY_TIMEOUT.rst @@ -0,0 +1,7 @@ +CTEST_SUBMIT_INACTIVITY_TIMEOUT +------------------------------- + +.. versionadded:: 3.23 + +Specify the CTest ``SubmitInactivityTimeout`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/ENV.rst b/Help/variable/ENV.rst index 2b43934..6791853 100644 --- a/Help/variable/ENV.rst +++ b/Help/variable/ENV.rst @@ -8,5 +8,6 @@ Use the syntax ``$ENV{VAR}`` to read environment variable ``VAR``. To test whether an environment variable is defined, use the signature ``if(DEFINED ENV{<name>})`` of the :command:`if` command. -See the :command:`set` and :command:`unset` commands to see how to -write or remove environment variables. +For general information on environment variables, see the +:ref:`Environment Variables <CMake Language Environment Variables>` +section in the :manual:`cmake-language(7)` manual. diff --git a/Help/variable/GHS-MULTI.rst b/Help/variable/GHS-MULTI.rst deleted file mode 100644 index bb139af..0000000 --- a/Help/variable/GHS-MULTI.rst +++ /dev/null @@ -1,6 +0,0 @@ -GHS-MULTI ---------- - -.. versionadded:: 3.3 - -``True`` when using :generator:`Green Hills MULTI` generator. diff --git a/Help/variable/GHSMULTI.rst b/Help/variable/GHSMULTI.rst new file mode 100644 index 0000000..3daef5d --- /dev/null +++ b/Help/variable/GHSMULTI.rst @@ -0,0 +1,9 @@ +GHSMULTI +-------- + +.. versionadded:: 3.3 + +``1`` when using :generator:`Green Hills MULTI` generator. + +Also, Set to ``1`` when the target system is a Green Hills platform +(i.e. When CMAKE_SYSTEM_NAME is ``GHS-MULTI``). diff --git a/Help/variable/IGNORE_SEARCH_LOCATIONS.txt b/Help/variable/IGNORE_SEARCH_LOCATIONS.txt new file mode 100644 index 0000000..a98f359 --- /dev/null +++ b/Help/variable/IGNORE_SEARCH_LOCATIONS.txt @@ -0,0 +1,4 @@ +Ignoring search locations can be useful in cross-compiling environments where +some system directories contain incompatible but possibly linkable libraries. +For example, on cross-compiled cluster environments, this allows a user to +ignore directories containing libraries meant for the front-end machine. diff --git a/Help/variable/IGNORE_SEARCH_NONSYSTEM.txt b/Help/variable/IGNORE_SEARCH_NONSYSTEM.txt new file mode 100644 index 0000000..a32a189 --- /dev/null +++ b/Help/variable/IGNORE_SEARCH_NONSYSTEM.txt @@ -0,0 +1,2 @@ +By default, |CMAKE_IGNORE_VAR| is empty. It is intended to be set by the +project or the end user. diff --git a/Help/variable/IGNORE_SEARCH_PATH.txt b/Help/variable/IGNORE_SEARCH_PATH.txt new file mode 100644 index 0000000..0811e02 --- /dev/null +++ b/Help/variable/IGNORE_SEARCH_PATH.txt @@ -0,0 +1,19 @@ +:ref:`Semicolon-separated list <CMake Language Lists>` of directories +to be ignored by the various ``find...()`` commands. + +For :command:`find_program`, :command:`find_library`, :command:`find_file`, +and :command:`find_path`, any file found in one of the listed directories +will be ignored. The listed directories do not apply recursively, so any +subdirectories to be ignored must also be explicitly listed. +|CMAKE_IGNORE_VAR| does not affect the search *prefixes* used by these +four commands. To ignore individual paths under a search prefix +(e.g. ``bin``, ``include``, ``lib``, etc.), each path must be listed in +|CMAKE_IGNORE_VAR| as a full absolute path. |CMAKE_IGNORE_PREFIX_VAR| +provides a more appropriate way to ignore a whole search prefix. + +:command:`find_package` is also affected by |CMAKE_IGNORE_VAR|, but only +for *Config mode* searches. Any ``<Name>Config.cmake`` or +``<name>-config.cmake`` file found in one of the specified directories +will be ignored. In addition, any search *prefix* found in |CMAKE_IGNORE_VAR| +will be skipped for backward compatibility reasons, but new code should +prefer to use |CMAKE_IGNORE_PREFIX_VAR| to ignore prefixes instead. diff --git a/Help/variable/IGNORE_SEARCH_PREFIX.txt b/Help/variable/IGNORE_SEARCH_PREFIX.txt new file mode 100644 index 0000000..f5ec3dc --- /dev/null +++ b/Help/variable/IGNORE_SEARCH_PREFIX.txt @@ -0,0 +1,6 @@ +:ref:`Semicolon-separated list <CMake Language Lists>` of search *prefixes* +to be ignored by the :command:`find_program`, :command:`find_library`, +:command:`find_file`, and :command:`find_path` commands. +The prefixes are also ignored by the *Config mode* of the +:command:`find_package` command (*Module mode* is unaffected). +To ignore specific directories instead, see |CMAKE_IGNORE_NONPREFIX_VAR|. diff --git a/Help/variable/IGNORE_SEARCH_SYSTEM.txt b/Help/variable/IGNORE_SEARCH_SYSTEM.txt new file mode 100644 index 0000000..78b285d6 --- /dev/null +++ b/Help/variable/IGNORE_SEARCH_SYSTEM.txt @@ -0,0 +1,5 @@ +|CMAKE_IGNORE_VAR| is populated by CMake as part of its platform +and toolchain setup. Its purpose is to ignore locations containing +incompatible binaries meant for the host rather than the target platform. +The project or end user should not modify this variable, they should use +|CMAKE_IGNORE_NONSYSTEM_VAR| instead. diff --git a/Help/variable/LINK_GROUP_PREDEFINED_FEATURES.txt b/Help/variable/LINK_GROUP_PREDEFINED_FEATURES.txt new file mode 100644 index 0000000..5f1a11b --- /dev/null +++ b/Help/variable/LINK_GROUP_PREDEFINED_FEATURES.txt @@ -0,0 +1,22 @@ +**Circular references with static libraries** + +Some linkers are one-pass only so to handle circular references between +static libraries, the following feature can be used: + +``RESCAN`` + The specified static libraries are searched repeatedly until no + new undefined references are created. Normally, an static library is searched + only once in the order that it is specified on the command line. If a symbol + in that library is needed to resolve an undefined symbol referred to by an + object in an library that appears later on the command line, the linker would + not be able to resolve that reference. By grouping the static libraries, they + all be searched repeatedly until all possible references are resolved (use + linker options ``--start-group`` and ``--end-group`` or, on ``SunOS``, + ``-z rescan-start`` and ``-z rescan-end``). + + Using this feature has a significant performance cost. It is best to use it + only when there are unavoidable circular references between two or more + static libraries. + + This feature is available on ``Linux``, ``BSD``, and ``SunOS`` target + platforms as well as ``Windows`` when ``GNU`` toolchain is used. diff --git a/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt b/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt new file mode 100644 index 0000000..e4fa0ed8 --- /dev/null +++ b/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt @@ -0,0 +1,88 @@ +**Features available in all environments** + +``DEFAULT`` + This feature enables default link expression. This is mainly + useful with :prop_tgt:`LINK_LIBRARY_OVERRIDE` and + :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties. + +**Features available for a subset of environments** + +``WHOLE_ARCHIVE`` + Force load of all members in a static library. + + Target platforms supported: all ``Apple`` variants, ``Linux``, all ``BSD`` + variants, ``SunOS``, ``Windows``, ``CYGWIN``, and ``MSYS``. + + Platform-specific notes: + + * On Apple platforms, the library must be specified as a CMake target name, a + library file name (such as ``libfoo.a``), or a library file path (such as + ``/path/to/libfoo.a``). It cannot be specified as a plain library name + (such as ``foo``, where ``foo`` is not CMake target), due to a limitation + in the Apple linker. + * On Windows platforms, for ``MSVC`` or MSVC-like toolchains, the version + must be greater than ``1900``. + +**Features available in Apple environments** + +It is assumed that the linker used is the one provided by `XCode` or is +compatible with it. + +Framework support + +``FRAMEWORK`` + This option tells the linker to search for the specified + framework (use linker option ``-framework``). +``NEEDED_FRAMEWORK`` + This is the same as the ``FRAMEWORK`` feature but means + to really link with the framework even if no symbols are used from it (use + linker option ``-needed_framework``). +``REEXPORT_FRAMEWORK`` + This is the same as the ``FRAMEWORK`` feature but + also specifies that all symbols in that framework should be available to + clients linking to the library being created (use linker option + ``-reexport_framework``). +``WEAK_FRAMEWORK`` + This is the same as the ``FRAMEWORK`` feature but forces + the framework and all references to it to be marked as weak imports (use + linker option ``-weak_framework``). + +Features for framework linking have a special handling in CMake: the +framework can be specified as a CMake framework target or file path. In the +first case, the target must have the :prop_tgt:`FRAMEWORK` target property set +as ``TRUE`` to enable framework handling. In the later case, if the path +includes a directory part, this one will be specified as framework search path +at link step. + +.. code-block:: cmake + + add_library(lib SHARED ...) + target_link_libraries(lib PRIVATE "$<LINK_LIBRARY:NEEDED_FRAMEWORK,/path/to/my_framework>") + + # at link step we will have: + # -F/path/to -needed_framework my_framework + +.. note:: + + The expected formats for the file path, with optional parts specified as + ``()?``, are: + + * (/path/to/)?FwName(.framework)? + * (/path/to/)?FwName.framework/FwName + * (/path/to/)?FwName.framework/Versions/\*/FwName + +Library support + +``NEEDED_LIBRARY`` + This is the same as specifying a link item (target or + library) but means to really link with the item even if no symbols are used + from it (use linker option ``-needed_library`` or ``-needed-l``). +``REEXPORT_LIBRARY`` + This is the same as specifying a link item (target or + library) but also specifies that all symbols in that item should be available + to clients linking to the library being created (use linker option + ``-reexport_library`` or ``-reexport-l``). +``WEAK_LIBRARY`` + This is the same as specifying a link item (target or + library) but forces the item and all references to it to be marked as weak + imports (use linker option ``-weak_library`` or ``-weak-l``). |