diff options
Diffstat (limited to 'Help')
138 files changed, 4878 insertions, 955 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index ee6c1cc..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| 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 ec73f9f..9e60d2d 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -288,12 +288,12 @@ The options are: .. productionlist:: depfile depfile: `rule`* - rule: `targets` (`:` (`separator` `dependencies`?)?)? `eol` + rule: `targets` (':' (`separator` `dependencies`?)?)? `eol` targets: `target` (`separator` `target`)* `separator`* target: `pathname` dependencies: `dependency` (`separator` `dependency`)* `separator`* dependency: `pathname` - separator: (space | line_continue)+ + separator: (`space` | `line_continue`)+ line_continue: '\' `eol` space: ' ' | '\t' pathname: `character`+ @@ -425,6 +425,11 @@ of the following is specified: ``POST_BUILD`` Run after all other rules within the target have been executed. +Projects should always specify one of the above three keywords when using +the ``TARGET`` form. For backward compatibility reasons, ``POST_BUILD`` is +assumed if no such keyword is given, but projects should explicitly provide +one of the keywords to make clear the behavior they expect. + .. note:: Because generator expressions can be used in custom commands, it is possible to define ``COMMAND`` lines or whole custom commands 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/cmake_language.rst b/Help/command/cmake_language.rst index 2859f6b..cb8d60b 100644 --- a/Help/command/cmake_language.rst +++ b/Help/command/cmake_language.rst @@ -13,6 +13,7 @@ Synopsis cmake_language(`CALL`_ <command> [<arg>...]) cmake_language(`EVAL`_ CODE <code>...) cmake_language(`DEFER`_ <options>... CALL <command> [<arg>...]) + cmake_language(`SET_DEPENDENCY_PROVIDER`_ <command> SUPPORTED_METHODS <methods>...) Introduction ^^^^^^^^^^^^ @@ -225,3 +226,268 @@ also prints:: Immediate Message Deferred Message 1 Deferred Message 2 + + +.. _SET_DEPENDENCY_PROVIDER: +.. _dependency_providers: + +Dependency Providers +^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.24 + +.. note:: A high-level introduction to this feature can be found in the + :ref:`Using Dependencies Guide <dependency_providers_overview>`. + +.. code-block:: cmake + + cmake_language(SET_DEPENDENCY_PROVIDER <command> + SUPPORTED_METHODS <methods>...) + +When a call is made to :command:`find_package` or +:command:`FetchContent_MakeAvailable`, the call may be forwarded to a +dependency provider which then has the opportunity to fulfill the request. +If the request is for one of the ``<methods>`` specified when the provider +was set, CMake calls the provider's ``<command>`` with a set of +method-specific arguments. If the provider does not fulfill the request, +or if the provider doesn't support the request's method, or no provider +is set, the built-in :command:`find_package` or +:command:`FetchContent_MakeAvailable` implementation is used to fulfill +the request in the usual way. + +One or more of the following values can be specified for the ``<methods>`` +when setting the provider: + +``FIND_PACKAGE`` + The provider command accepts :command:`find_package` requests. + +``FETCHCONTENT_MAKEAVAILABLE_SERIAL`` + The provider command accepts :command:`FetchContent_MakeAvailable` + requests. It expects each dependency to be fed to the provider command + one at a time, not the whole list in one go. + +Only one provider can be set at any point in time. If a provider is already +set when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called, the new +provider replaces the previously set one. The specified ``<command>`` must +already exist when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called. +As a special case, providing an empty string for the ``<command>`` and no +``<methods>`` will discard any previously set provider. + +The dependency provider can only be set while processing one of the files +specified by the :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable. +Thus, dependency providers can only be set as part of the first call to +:command:`project`. Calling ``cmake_language(SET_DEPENDENCY_PROVIDER)`` +outside of that context will result in an error. + +.. note:: + The choice of dependency provider should always be under the user's control. + As a convenience, a project may choose to provide a file that users can + list in their :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable, but + the use of such a file should always be the user's choice. + +Provider commands +""""""""""""""""" + +Providers define a single ``<command>`` to accept requests. The name of +the command should be specific to that provider, not something overly +generic that another provider might also use. This enables users to compose +different providers in their own custom provider. The recommended form is +``xxx_provide_dependency()``, where ``xxx`` is the provider-specific part +(e.g. ``vcpkg_provide_dependency()``, ``conan_provide_dependency()``, +``ourcompany_provide_dependency()``, and so on). + +.. code-block:: cmake + + xxx_provide_dependency(<method> [<method-specific-args>...]) + +Because some methods expect certain variables to be set in the calling scope, +the provider command should typically be implemented as a macro rather than a +function. This ensures it does not introduce a new variable scope. + +The arguments CMake passes to the dependency provider depend on the type of +request. The first argument is always the method, and it will only ever +be one of the ``<methods>`` that was specified when setting the provider. + +``FIND_PACKAGE`` + The ``<method-specific-args>`` will be everything passed to the + :command:`find_package` call that requested the dependency. The first of + these ``<method-specific-args>`` will therefore always be the name of the + dependency. Dependency names are case-sensitive for this method because + :command:`find_package` treats them case-sensitively too. + + If the provider command fulfills the request, it must set the same variable + that :command:`find_package` expects to be set. For a dependency named + ``depName``, the provider must set ``depName_FOUND`` to true if it fulfilled + the request. If the provider returns without setting this variable, CMake + will assume the request was not fulfilled and will fall back to the + built-in implementation. + + If the provider needs to call the built-in :command:`find_package` + implementation as part of its processing, it can do so by including the + ``BYPASS_PROVIDER`` keyword as one of the arguments. + +``FETCHCONTENT_MAKEAVAILABE_SERIAL`` + The ``<method-specific-args>`` will be everything passed to the + :command:`FetchContent_Declare` call that corresponds to the requested + dependency, with the following exceptions: + + * If ``SOURCE_DIR`` or ``BINARY_DIR`` were not part of the original + declared arguments, they will be added with their default values. + * If :variable:`FETCHCONTENT_TRY_FIND_PACKAGE_MODE` is set to ``NEVER``, + any ``FIND_PACKAGE_ARGS`` will be omitted. + * The ``OVERRIDE_FIND_PACKAGE`` keyword is always omitted. + + The first of the ``<method-specific-args>`` will always be the name of the + dependency. Dependency names are case-insensitive for this method because + :module:`FetchContent` also treats them case-insensitively. + + If the provider fulfills the request, it should call + :command:`FetchContent_SetPopulated`, passing the name of the dependency as + the first argument. The ``SOURCE_DIR`` and ``BINARY_DIR`` arguments to that + command should only be given if the provider makes the dependency's source + and build directories available in exactly the same way as the built-in + :command:`FetchContent_MakeAvailable` command. + + If the provider returns without calling :command:`FetchContent_SetPopulated` + for the named dependency, CMake will assume the request was not fulfilled + and will fall back to the built-in implementation. + + Note that empty arguments may be significant for this method (e.g. an empty + string following a ``GIT_SUBMODULES`` keyword). Therefore, if forwarding + these arguments on to another command, extra care must be taken to avoid such + arguments being silently dropped. + + If ``FETCHCONTENT_SOURCE_DIR_<uppercaseDepName>`` is set, then the + dependency provider will never see requests for the ``<depName>`` dependency + for this method. When the user sets such a variable, they are explicitly + overriding where to get that dependency from and are taking on the + responsibility that their overriding version meets any requirements for that + dependency and is compatible with whatever else in the project uses it. + Depending on the value of :variable:`FETCHCONTENT_TRY_FIND_PACKAGE_MODE` + and whether the ``OVERRIDE_FIND_PACKAGE`` option was given to + :command:`FetchContent_Declare`, having + ``FETCHCONTENT_SOURCE_DIR_<uppercaseDepName>`` set may also prevent the + dependency provider from seeing requests for a ``find_package(depName)`` + call too. + +Provider Examples +""""""""""""""""" + +This first example only intercepts :command:`find_package` calls. The +provider command runs an external tool which copies the relevant artifacts +into a provider-specific directory, if that tool knows about the dependency. +It then relies on the built-in implementation to then find those artifacts. +:command:`FetchContent_MakeAvailable` calls would not go through the provider. + +.. code-block:: cmake + :caption: mycomp_provider.cmake + + # Always ensure we have the policy settings this provider expects + cmake_minimum_required(VERSION 3.24) + + set(MYCOMP_PROVIDER_INSTALL_DIR ${CMAKE_BINARY_DIR}/mycomp_packages + CACHE PATH "The directory this provider installs packages to" + ) + # Tell the built-in implementation to look in our area first, unless + # the find_package() call uses NO_..._PATH options to exclude it + list(APPEND CMAKE_MODULE_PATH ${MYCOMP_PROVIDER_INSTALL_DIR}/cmake) + list(APPEND CMAKE_PREFIX_PATH ${MYCOMP_PROVIDER_INSTALL_DIR}) + + macro(mycomp_provide_dependency method package_name) + execute_process( + COMMAND some_tool ${package_name} --installdir ${MYCOMP_PROVIDER_INSTALL_DIR} + COMMAND_ERROR_IS_FATAL ANY + ) + endmacro() + + cmake_language( + SET_DEPENDENCY_PROVIDER mycomp_provide_dependency + SUPPORTED_METHODS FIND_PACKAGE + ) + +The user would then typically use the above file like so:: + + cmake -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=/path/to/mycomp_provider.cmake ... + +The next example demonstrates a provider that accepts both methods, but +only handles one specific dependency. It enforces providing Google Test +using :module:`FetchContent`, but leaves all other dependencies to be +fulfilled by CMake's built-in implementation. It accepts a few different +names, which demonstrates one way of working around projects that hard-code +an unusual or undesirable way of adding this particular dependency to the +build. The example also demonstrates how to use the :command:`list` command +to preserve variables that may be overwritten by a call to +:command:`FetchContent_MakeAvailable`. + +.. code-block:: cmake + :caption: mycomp_provider.cmake + + cmake_minimum_required(VERSION 3.24) + + # Because we declare this very early, it will take precedence over any + # details the project might declare later for the same thing + include(FetchContent) + FetchContent_Declare( + googletest + GIT_REPOSITORY https://github.com/google/googletest.git + GIT_TAG e2239ee6043f73722e7aa812a459f54a28552929 # release-1.11.0 + ) + + # Both FIND_PACKAGE and FETCHCONTENT_MAKEAVAILABLE_SERIAL methods provide + # the package or dependency name as the first method-specific argument. + macro(mycomp_provide_dependency method dep_name) + if("${dep_name}" MATCHES "^(gtest|googletest)$") + # Save our current command arguments in case we are called recursively + list(APPEND mycomp_provider_args ${method} ${dep_name}) + + # This will forward to the built-in FetchContent implementation, + # which detects a recursive call for the same thing and avoids calling + # the provider again if dep_name is the same as the current call. + FetchContent_MakeAvailable(googletest) + + # Restore our command arguments + list(POP_BACK mycomp_provider_args dep_name method) + + # Tell the caller we fulfilled the request + if("${method}" STREQUAL "FIND_PACKAGE") + # We need to set this if we got here from a find_package() call + # since we used a different method to fulfill the request. + # This example assumes projects only use the gtest targets, + # not any of the variables the FindGTest module may define. + set(${dep_name}_FOUND TRUE) + elseif(NOT "${dep_name}" STREQUAL "googletest") + # We used the same method, but were given a different name to the + # one we populated with. Tell the caller about the name it used. + FetchContent_SetPopulated(${dep_name} + SOURCE_DIR "${googletest_SOURCE_DIR}" + BINARY_DIR "${googletest_BINARY_DIR}" + ) + endif() + endif() + endmacro() + + cmake_language( + SET_DEPENDENCY_PROVIDER mycomp_provide_dependency + SUPPORTED_METHODS + FIND_PACKAGE + FETCHCONTENT_MAKEAVAILABLE_SERIAL + ) + +The final example demonstrates how to modify arguments to a +:command:`find_package` call. It forces all such calls to have the +``QUIET`` keyword. It uses the ``BYPASS_PROVIDER`` keyword to prevent +calling the provider command recursively for the same dependency. + +.. code-block:: cmake + :caption: mycomp_provider.cmake + + cmake_minimum_required(VERSION 3.24) + + macro(mycomp_provide_dependency method) + find_package(${ARGN} BYPASS_PROVIDER QUIET) + endmacro() + + cmake_language( + SET_DEPENDENCY_PROVIDER mycomp_provide_dependency + SUPPORTED_METHODS FIND_PACKAGE + ) diff --git a/Help/command/cmake_path.rst b/Help/command/cmake_path.rst index 454c860..eb7da07 100644 --- a/Help/command/cmake_path.rst +++ b/Help/command/cmake_path.rst @@ -96,6 +96,8 @@ The following conventions are used in this command's documentation: The name of a variable into which the result of a command will be written. +.. _Path Structure And Terminology: + Path Structure And Terminology ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -216,6 +218,8 @@ normalize a path is as follows: is ``.``). +.. _Path Decomposition: + Decomposition ^^^^^^^^^^^^^ @@ -385,6 +389,8 @@ Path traversal examples Parent path is "c:/" +.. _Path Query: + Query ^^^^^ @@ -467,6 +473,7 @@ are :ref:`normalized <Normalization>` before the check. set(path "/a/b") cmake_path(IS_PREFIX path "/a/c/../b" NORMALIZE result) # result = true +.. _Path COMPARE: .. _COMPARE: :: @@ -475,8 +482,9 @@ are :ref:`normalized <Normalization>` before the check. cmake_path(COMPARE <input1> NOT_EQUAL <input2> <out-var>) Compares the lexical representations of two paths provided as string literals. -No normalization is performed on either path. Equality is determined -according to the following pseudo-code logic: +No normalization is performed on either path, except multiple consecutive +directory separators are effectively collapsed into a single separator. +Equality is determined according to the following pseudo-code logic: :: @@ -495,6 +503,8 @@ according to the following pseudo-code logic: takes literal strings as input, not the names of variables. +.. _Path Modification: + Modification ^^^^^^^^^^^^ @@ -509,7 +519,7 @@ path, it is converted into a cmake-style path with forward-slashes (``/``). On Windows, the long filename marker is taken into account. When the ``NORMALIZE`` option is specified, the path is :ref:`normalized -<Normalization>` before the conversion. +<Normalization>` after the conversion. For example: @@ -644,6 +654,8 @@ is equivalent to the following: cmake_path(APPEND_STRING path "input") +.. _Path Generation: + Generation ^^^^^^^^^^ 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/execute_process.rst b/Help/command/execute_process.rst index 82fcd46..d4ba465 100644 --- a/Help/command/execute_process.rst +++ b/Help/command/execute_process.rst @@ -37,8 +37,15 @@ Options: ``COMMAND`` A child process command line. - CMake executes the child process using operating system APIs directly. - All arguments are passed VERBATIM to the child process. + CMake executes the child process using operating system APIs directly: + + * On POSIX platforms, the command line is passed to the + child process in an ``argv[]`` style array. + + * On Windows platforms, the command line is encoded as a string such + that child processes using ``CommandLineToArgvW`` will decode the + original arguments. + No intermediate shell is used, so shell operators such as ``>`` are treated as normal arguments. (Use the ``INPUT_*``, ``OUTPUT_*``, and ``ERROR_*`` options to 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 5acefad..ee52c41 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -1,17 +1,30 @@ 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:: +.. note:: The :guide:`Using Dependencies Guide` provides a high-level + introduction to this general topic. It provides a broader overview of + where the ``find_package()`` command fits into the bigger picture, + including its relationship to the :module:`FetchContent` module. + The guide is recommended pre-reading before moving on to the details below. + Find a package (usually provided by something external to the project), -and load its package-specific details. +and load its package-specific details. Calls to this command can also +be intercepted by :ref:`dependency providers <dependency_providers>`. 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 +67,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 +87,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 +97,15 @@ 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)] + [GLOBAL] + [NO_POLICY_SCOPE] + [BYPASS_PROVIDER]) 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 +141,18 @@ 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. + +.. versionadded:: 3.24 + 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:`CMAKE_FIND_PACKAGE_TARGETS_GLOBAL` + variable. + .. _FIND_PACKAGE_VERSION_FORMAT: The ``[version]`` argument requests a version with which the package found @@ -144,22 +182,33 @@ only take the single version at the lower end of the range into account. See the :command:`cmake_policy` command documentation for discussion of the ``NO_POLICY_SCOPE`` option. +.. versionadded:: 3.24 + The ``BYPASS_PROVIDER`` keyword is only allowed when ``find_package()`` is + being called by a :ref:`dependency provider <dependency_providers>`. + It can be used by providers to call the built-in ``find_package()`` + implementation directly and prevent that call from being re-routed back to + itself. Future versions of CMake may detect attempts to use this keyword + from places other than a dependency provider and halt with a fatal error. + .. _`full signature`: Full Signature ^^^^^^^^^^^^^^ -.. code-block:: cmake +.. parsed-literal:: find_package(<PackageName> [version] [EXACT] [QUIET] [REQUIRED] [[COMPONENTS] [components...]] [OPTIONAL_COMPONENTS components...] [CONFIG|NO_MODULE] + [GLOBAL] [NO_POLICY_SCOPE] + [BYPASS_PROVIDER] [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 +218,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 +231,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 +273,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 +325,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 +412,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 :variable:`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` @@ -372,11 +447,6 @@ of the above locations to be ignored. 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 @@ -388,7 +458,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. @@ -411,8 +482,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 @@ -547,6 +618,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 4f955db..301cdce 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -47,7 +47,7 @@ Compound conditions are evaluated in the following order of precedence: `GREATER_EQUAL`_, `STREQUAL`_, `STRLESS`_, `STRLESS_EQUAL`_, `STRGREATER`_, `STRGREATER_EQUAL`_, `VERSION_EQUAL`_, `VERSION_LESS`_, `VERSION_LESS_EQUAL`_, `VERSION_GREATER`_, `VERSION_GREATER_EQUAL`_, - and `MATCHES`_. + `PATH_EQUAL`_, and `MATCHES`_. 4. Unary logical operator `NOT`_. @@ -71,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: @@ -313,6 +314,39 @@ Version Comparisons Any non-integer version component or non-integer trailing part of a version component effectively truncates the string at that point. +Path Comparisons +"""""""""""""""" + +.. _PATH_EQUAL: + +``if(<variable|string> PATH_EQUAL <variable|string>)`` + .. versionadded:: 3.24 + + Compares the two paths component-by-component. Only if every component of + both paths match will the two paths compare equal. Multiple path separators + are effectively collapsed into a single separator, but note that backslashes + are not converted to forward slashes. No other + :ref:`path normalization <Normalization>` is performed. + + Component-wise comparison is superior to string-based comparison due to the + handling of multiple path separators. In the following example, the + expression evaluates to true using ``PATH_EQUAL``, but false with + ``STREQUAL``: + + .. code-block:: cmake + + # comparison is TRUE + if ("/a//b/c" PATH_EQUAL "/a/b/c") + ... + endif() + + # comparison is FALSE + if ("/a//b/c" STREQUAL "/a/b/c") + ... + endif() + + See :ref:`cmake_path(COMPARE) <Path COMPARE>` for more details. + Variable Expansion ^^^^^^^^^^^^^^^^^^ diff --git a/Help/command/install.rst b/Help/command/install.rst index 1a9dfd7..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``. 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/option.rst b/Help/command/option.rst index 02b8dac..464ad44 100644 --- a/Help/command/option.rst +++ b/Help/command/option.rst @@ -1,16 +1,18 @@ option ------ -Provide an option that the user can optionally select. +Provide a boolean option that the user can optionally select. .. code-block:: cmake option(<variable> "<help_text>" [value]) -Provides an option for the user to select as ``ON`` or ``OFF``. -If no initial ``<value>`` is provided, ``OFF`` is used. +If no initial ``<value>`` is provided, boolean ``OFF`` is the default value. If ``<variable>`` is already set as a normal or cache variable, then the command does nothing (see policy :policy:`CMP0077`). -If you have options that depend on the values of other options, see +For options that depend on the values of other options, see the module help for :module:`CMakeDependentOption`. + +In CMake project mode, a boolean cache variable is created with the option +value. In CMake script mode, a boolean variable is set with the option value. 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/target_sources.rst b/Help/command/target_sources.rst index 1ad6c37..72119f6 100644 --- a/Help/command/target_sources.rst +++ b/Help/command/target_sources.rst @@ -52,10 +52,10 @@ 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>") + target_sources(MyTarget PRIVATE "$<$<CONFIG:Debug>:dbgsrc.cpp>") # CORRECT: absolute path used inside the generator expression - target_sources(MyTarget "$<$<CONFIG:Debug>:${CMAKE_CURRENT_SOURCE_DIR}/dbgsrc.cpp>") + target_sources(MyTarget PRIVATE "$<$<CONFIG:Debug>:${CMAKE_CURRENT_SOURCE_DIR}/dbgsrc.cpp>") See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem properties. 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/archive.rst b/Help/cpack_gen/archive.rst index 47e8e13..a77b615 100644 --- a/Help/cpack_gen/archive.rst +++ b/Help/cpack_gen/archive.rst @@ -49,6 +49,8 @@ Variables specific to CPack Archive generator Package file name without extension. The extension is determined from the archive format (see list above) and automatically appended to the file name. + Note that ``<component>`` is all uppercase in the variable name. + The default is ``<CPACK_PACKAGE_FILE_NAME>[-<component>]``, with spaces replaced by '-'. diff --git a/Help/cpack_gen/dmg.rst b/Help/cpack_gen/dmg.rst index b4ef5a2..cba7a00 100644 --- a/Help/cpack_gen/dmg.rst +++ b/Help/cpack_gen/dmg.rst @@ -65,8 +65,8 @@ on macOS: In a CMake project that uses the :module:`CPack` module to generate ``CPackConfig.cmake``, ``CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE`` - is automatically enabled by default if it is not set and - :variable:`CPACK_RESOURCE_FILE_LICENSE` is set to a non-default value. + must be explicitly enabled by the project to activate the SLA. + See policy :policy:`CMP0133`. .. note:: 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/wix.rst b/Help/cpack_gen/wix.rst index e9d5af6..a3d43fc 100644 --- a/Help/cpack_gen/wix.rst +++ b/Help/cpack_gen/wix.rst @@ -328,3 +328,12 @@ Windows using WiX. 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/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/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..ee2328b --- /dev/null +++ b/Help/envvar/ADSP_ROOT.rst @@ -0,0 +1,10 @@ +ADSP_ROOT +--------- + +.. versionadded:: 3.24 + +.. 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/guide/using-dependencies/index.rst b/Help/guide/using-dependencies/index.rst index f4d7845..bb519ad 100644 --- a/Help/guide/using-dependencies/index.rst +++ b/Help/guide/using-dependencies/index.rst @@ -8,193 +8,412 @@ Using Dependencies Guide Introduction ============ -For developers wishing to use CMake to consume a third -party binary package, there are multiple possibilities -regarding how to optimally do so, depending on how -CMake-aware the third-party library is. - -CMake files provided with a software package contain -instructions for finding each build dependency. Some -build dependencies are optional in that the build may -succeed with a different feature set if the dependency -is missing, and some dependencies are required. CMake -searches well-known locations for each dependency, and -the provided software may supply additional hints or -locations to CMake to find each dependency. - -If a required dependency is not found by -:manual:`cmake(1)`, the cache is populated with an entry -which contains a ``NOTFOUND`` value. This value can be -replaced by specifying it on the command line, or in -the :manual:`ccmake(1)` or :manual:`cmake-gui(1)` tool. -See the :guide:`User Interaction Guide` for -more about setting cache entries. - -Libraries providing Config-file packages -======================================== - -The most convenient way for a third-party to provide library -binaries for use with CMake is to provide -:ref:`Config File Packages`. These packages are text files -shipped with the library which instruct CMake how to use the -library binaries and associated headers, helper tools and -CMake macros provided by the library. - -The config files can usually be found in a directory whose -name matches the pattern ``lib/cmake/<PackageName>``, though -they may be in other locations instead. The -``<PackageName>`` corresponds to use in CMake code with the -:command:`find_package` command such as -``find_package(PackageName REQUIRED)``. - -The ``lib/cmake/<PackageName>`` directory will contain a -file which is either named ``<PackageName>Config.cmake`` -or ``<PackageName>-config.cmake``. This is the entry point +Projects will frequently depend on other projects, assets, and artifacts. +CMake provides a number of ways to incorporate such things into the build. +Projects and users have the flexibility to choose between methods that +best suit their needs. + +The primary methods of bringing dependencies into the build are the +:command:`find_package` command and the :module:`FetchContent` module. +The :module:`FindPkgConfig` module is also sometimes used, although it +lacks some of the integration of the other two and is not discussed any +further in this guide. + +Dependencies can also be made available by a custom +:ref:`dependency provider <dependency_providers>`. +This might be a third party package manager, or it might be custom code +implemented by the developer. Dependency providers co-operate with the +primary methods mentioned above to extend their flexibility. + +.. _prebuilt_find_package: + +Using Pre-built Packages With ``find_package()`` +================================================ + +A package needed by the project may already be built and available at some +location on the user's system. That package might have also been built by +CMake, or it could have used a different build system entirely. It might +even just be a collection of files that didn't need to be built at all. +CMake provides the :command:`find_package` command for these scenarios. +It searches well-known locations, along with additional hints and paths +provided by the project or user. It also supports package components and +packages being optional. Result variables are provided to allow the project +to customize its own behavior according to whether the package or specific +components were found. + +In most cases, projects should generally use the :ref:`basic signature`. +Most of the time, this will involve just the package name, maybe a version +constraint, and the ``REQUIRED`` keyword if the dependency is not optional. +A set of package components may also be specified. + +.. code-block:: cmake + :caption: Examples of ``find_package()`` basic signature + + find_package(Catch2) + find_package(GTest REQUIRED) + find_package(Boost 1.79 COMPONENTS date_time) + +The :command:`find_package` command supports two main methods for carrying +out the search: + +**Config mode** + With this method, the command looks for files that are typically provided + by the package itself. This is the more reliable method of the two, since + the package details should always be in sync with the package. + +**Module mode** + Not all packages are CMake-aware. Many don't provide the files needed to + support config mode. For such cases, a Find module file can be provided + separately, either by the project or by CMake. A Find module is typically + a heuristic implementation which knows what the package normally provides + and how to present that package to the project. Since Find modules are + usually distributed separately from the package, they are not as reliable. + They are typically maintained separately, and they are likely to follow + different release schedules, so they can easily become out-of-date. + +Depending on the arguments used, :command:`find_package` may use one or both +of the above methods. By restricting the options to just the basic signature, +both config mode and module mode can be used to satisfy the dependency. +The presence of other options may restrict the call to using only one of the +two methods, potentially reducing the command's ability to find the dependency. +See the :command:`find_package` documentation for full details about this +complex topic. + +For both search methods, the user can also set cache variables on the +:manual:`cmake(1)` command line or in the :manual:`ccmake(1)` or +:manual:`cmake-gui(1)` UI tools to influence and override where to find +packages. See the :ref:`User Interaction Guide <Setting Build Variables>` +for more on how to set cache variables. + +.. _Libraries providing Config-file packages: + +Config-file packages +-------------------- + +The preferred way for a third party to provide executables, libraries, +headers, and other files for use with CMake is to provide +:ref:`config files <Config File Packages>`. These are text files shipped +with the package, which define CMake targets, variables, commands, and so on. +The config file is an ordinary CMake script, which is read in by the +:command:`find_package` command. + +The config files can usually be found in a directory whose name matches the +pattern ``lib/cmake/<PackageName>``, although they may be in other locations +instead (see :ref:`search procedure`). The ``<PackageName>`` is usually the +first argument to the :command:`find_package` command, and it may even be the +only argument. Alternative names can also be specified with the ``NAMES`` +option: + +.. code-block:: cmake + :caption: Providing alternative names when finding a package + + find_package(SomeThing + NAMES + SameThingOtherName # Another name for the package + SomeThing # Also still look for its canonical name + ) + +The config file must be named either ``<PackageName>Config.cmake`` or +``<LowercasePackageName>-config.cmake`` (the former is used for the remainder +of this guide, but both are supported). This file is the entry point to the package for CMake. A separate optional file named -``<PackageName>ConfigVersion.cmake`` may also exist in the -directory. This file is used by CMake to determine whether -the version of the third party package satisfies uses of the -:command:`find_package` command which specify version -constraints. It is optional to specify a version when using -:command:`find_package`, even if a ``ConfigVersion`` file is -present. - -If the ``Config.cmake`` file is found and the -optionally-specified version is satisfied, then the CMake -:command:`find_package` command considers the package to be -found and the entire library package is assumed to be -complete as designed. - -There may be additional files providing CMake macros or -:ref:`imported targets` for you to use. CMake does not -enforce any naming convention for these -files. They are related to the primary ``Config`` file by -use of the CMake :command:`include` command. - -:guide:`Invoking CMake <User Interaction Guide>` with the -intent of using a package of third party binaries requires -that cmake :command:`find_package` commands succeed in finding -the package. If the location of the package is in a directory -known to CMake, the :command:`find_package` call should -succeed. The directories known to cmake are platform-specific. -For example, packages installed on Linux with a standard -system package manager will be found in the ``/usr`` prefix -automatically. Packages installed in ``Program Files`` on -Windows will similarly be found automatically. - -Packages which are not found automatically are in locations -not predictable to CMake such as ``/opt/mylib`` or -``$HOME/dev/prefix``. This is a normal situation and CMake -provides several ways for users to specify where to find -such libraries. +``<PackageName>ConfigVersion.cmake`` or +``<LowercasePackageName>-config-version.cmake`` may also exist in the same +directory. This file is used by CMake to determine whether the version of +the package satisfies any version constraint included in the call to +:command:`find_package`. It is optional to specify a version when calling +:command:`find_package`, even if a ``<PackageName>ConfigVersion.cmake`` +file is present. + +If the ``<PackageName>Config.cmake`` file is found and any version constraint +is satisfied, the :command:`find_package` command considers the package to be +found, and the entire package is assumed to be complete as designed. + +There may be additional files providing CMake commands or +:ref:`imported targets` for you to use. CMake does not enforce any naming +convention for these files. They are related to the primary +``<PackageName>Config.cmake`` file by use of the CMake :command:`include` +command. The ``<PackageName>Config.cmake`` file would typically include +these for you, so they won't usually require any additional step other than +the call to :command:`find_package`. + +If the location of the package is in a +:ref:`directory known to CMake <search procedure>`, the +:command:`find_package` call should succeed. The directories known to CMake +are platform-specific. For example, packages installed on Linux with a +standard system package manager will be found in the ``/usr`` prefix +automatically. Packages installed in ``Program Files`` on Windows will +similarly be found automatically. + +Packages will not be found automatically without help if they are in +locations not known to CMake, such as ``/opt/mylib`` or ``$HOME/dev/prefix``. +This is a normal situation, and CMake provides several ways for users to +specify where to find such libraries. The :variable:`CMAKE_PREFIX_PATH` variable may be :ref:`set when invoking CMake <Setting Build Variables>`. -It is treated as a list of paths to search for -:ref:`Config File Packages`. A package installed in -``/opt/somepackage`` will typically install config files -such as +It is treated as a list of base paths in which to search for +:ref:`config files <Config File Packages>`. A package installed in +``/opt/somepackage`` will typically install config files such as ``/opt/somepackage/lib/cmake/somePackage/SomePackageConfig.cmake``. In that case, ``/opt/somepackage`` should be added to :variable:`CMAKE_PREFIX_PATH`. -The environment variable ``CMAKE_PREFIX_PATH`` may also be -populated with prefixes to search for packages. Like the -``PATH`` environment variable, this is a list and needs to use -the platform-specific environment variable list item separator -(``:`` on Unix and ``;`` on Windows). - -The :variable:`CMAKE_PREFIX_PATH` variable provides convenience -in cases where multiple prefixes need to be specified, or when -multiple different package binaries are available in the same -prefix. Paths to packages may also be specified by setting -variables matching ``<PackageName>_DIR``, such as -``SomePackage_DIR``. Note that this is not a prefix but should -be a full path to a directory containing a config-style package -file, such as ``/opt/somepackage/lib/cmake/SomePackage/`` in -the above example. - -Imported Targets from Packages -============================== - -A third-party package which provides config-file packages may -also provide :ref:`Imported targets`. These will be -specified in files containing configuration-specific file -paths relevant to the package, such as debug and release -versions of libraries. - -Often the third-party package documentation will point out the -names of imported targets available after a successful -``find_package`` for a library. Those imported target names -can be used with the :command:`target_link_libraries` command. - -A complete example which makes a simple use of a third party -library might look like: +The environment variable ``CMAKE_PREFIX_PATH`` may also be populated with +prefixes to search for packages. Like the ``PATH`` environment variable, +this is a list, but it needs to use the platform-specific environment variable +list item separator (``:`` on Unix and ``;`` on Windows). + +The :variable:`CMAKE_PREFIX_PATH` variable provides convenience in cases +where multiple prefixes need to be specified, or when multiple packages +are available under the same prefix. Paths to packages may also be +specified by setting variables matching ``<PackageName>_DIR``, such as +``SomePackage_DIR``. Note that this is not a prefix, but should be a full +path to a directory containing a config-style package file, such as +``/opt/somepackage/lib/cmake/SomePackage`` in the above example. +See the :command:`find_package` documentation for other CMake variables and +environment variables that can affect the search. + +.. _Libraries not Providing Config-file Packages: + +Find Module Files +----------------- + +Packages which do not provide config files can still be found with the +:command:`find_package` command, if a ``FindSomePackage.cmake`` file is +available. These Find module files are different to config files in that: + +#. Find module files should not be provided by the package itself. +#. The availability of a ``Find<PackageName>.cmake`` file does not indicate + the availability of the package, or any particular part of the package. +#. CMake does not search the locations specified in the + :variable:`CMAKE_PREFIX_PATH` variable for ``Find<PackageName>.cmake`` + files. Instead, CMake searches for such files in the locations given + by the :variable:`CMAKE_MODULE_PATH` variable. It is common for users to + set the :variable:`CMAKE_MODULE_PATH` when running CMake, and it is common + for CMake projects to append to :variable:`CMAKE_MODULE_PATH` to allow use + of local Find module files. +#. CMake ships ``Find<PackageName>.cmake`` files for some + :manual:`third party packages <cmake-modules(7)>`. These files are a + maintenance burden for CMake, and it is not unusual for these to fall + behind the latest releases of the packages they are associated with. + In general, new Find modules are not added to CMake any more. Projects + should encourage the upstream packages to provide a config file where + possible. If that is unsuccessful, the project should provide its own + Find module for the package. + +See :ref:`Find Modules` for a detailed discussion of how to write a +Find module file. + +.. _Imported Targets from Packages: + +Imported Targets +---------------- + +Both config files and Find module files can define :ref:`Imported targets`. +These will typically have names of the form ``SomePrefix::ThingName``. +Where these are available, the project should prefer to use them instead of +any CMake variables that may also be provided. Such targets typically carry +usage requirements and apply things like header search paths, compiler +definitions, etc. automatically to other targets that link to them (e.g. using +:command:`target_link_libraries`). This is both more robust and more +convenient than trying to apply the same things manually using variables. +Check the documentation for the package or Find module to see what imported +targets it defines, if any. + +Imported targets should also encapsulate any configuration-specific paths. +This includes the location of binaries (libraries, executables), compiler +flags, and any other configuration-dependent quantities. Find modules may +be less reliable in providing these details than config files. + +A complete example which finds a third party package and uses a library +from it might look like the following: .. code-block:: cmake - cmake_minimum_required(VERSION 3.10) - project(MyExeProject VERSION 1.0.0) - - find_package(SomePackage REQUIRED) - add_executable(MyExe main.cpp) - target_link_libraries(MyExe PRIVATE SomePrefix::LibName) - -See :manual:`cmake-buildsystem(7)` for further information -about developing a CMake buildsystem. - -Libraries not Providing Config-file Packages --------------------------------------------- - -Third-party libraries which do not provide config-file packages -can still be found with the :command:`find_package` command, if -a ``FindSomePackage.cmake`` file is available. - -These module-file packages are different to config-file packages -in that: - -#. They should not be provided by the third party, except - perhaps in the form of documentation -#. The availability of a ``Find<PackageName>.cmake`` file does - not indicate the availability of the binaries themselves. -#. CMake does not search the :variable:`CMAKE_PREFIX_PATH` for - ``Find<PackageName>.cmake`` files. Instead CMake searches - for such files in the :variable:`CMAKE_MODULE_PATH` - variable. It is common for users to set the - :variable:`CMAKE_MODULE_PATH` when running CMake, and it is - common for CMake projects to append to - :variable:`CMAKE_MODULE_PATH` to allow use of local - module-file packages. -#. CMake ships ``Find<PackageName>.cmake`` files for some - :manual:`third party packages <cmake-modules(7)>` - for convenience in cases where the third party does - not provide config-file packages directly. These files are - a maintenance burden for CMake, so new Find modules are - generally not added to CMake anymore. Third-parties should - provide config file packages instead of relying on a Find - module to be provided by CMake. - -Module-file packages may also provide :ref:`Imported targets`. -A complete example which finds such a package might look -like: + cmake_minimum_required(VERSION 3.10) + project(MyExeProject VERSION 1.0.0) + + # Make project-provided Find modules available + list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake") + + find_package(SomePackage REQUIRED) + add_executable(MyExe main.cpp) + target_link_libraries(MyExe PRIVATE SomePrefix::LibName) + +Note that the above call to :command:`find_package` could be resolved by +a config file or a Find module. It uses only the basic arguments supported +by the :ref:`basic signature`. A ``FindSomePackage.cmake`` file in the +``${CMAKE_CURRENT_SOURCE_DIR}/cmake`` directory would allow the +:command:`find_package` command to succeed using module mode, for example. +If no such module file is present, the system would be searched for a config +file. + + +Downloading And Building From Source With ``FetchContent`` +========================================================== + +Dependencies do not necessarily have to be pre-built in order to use them +with CMake. They can be built from sources as part of the main project. +The :module:`FetchContent` module provides functionality to download +content (typically sources, but can be anything) and add it to the main +project if the dependency also uses CMake. The dependency's sources will +be built along with the rest of the project, just as though the sources were +part of the project's own sources. + +The general pattern is that the project should first declare all the +dependencies it wants to use, then ask for them to be made available. +The following demonstrates the principle (see :ref:`fetch-content-examples` +for more): .. code-block:: cmake - cmake_minimum_required(VERSION 3.10) - project(MyExeProject VERSION 1.0.0) + include(FetchContent) + FetchContent_Declare( + googletest + GIT_REPOSITORY https://github.com/google/googletest.git + GIT_TAG 703bd9caab50b139428cea1aaff9974ebee5742e # release-1.10.0 + ) + FetchContent_Declare( + Catch2 + GIT_REPOSITORY https://github.com/catchorg/Catch2.git + GIT_TAG de6fe184a9ac1a06895cdd1c9b437f0a0bdf14ad # v2.13.4 + ) + FetchContent_MakeAvailable(googletest Catch2) + +Various download methods are supported, including downloading and extracting +archives from a URL (a range of archive formats are supported), and a number +of repository formats including Git, Subversion, and Mercurial. +Custom download, update, and patch commands can also be used to support +arbitrary use cases. + +When a dependency is added to the project with :module:`FetchContent`, the +project links to the dependency's targets just like any other target from the +project. If the dependency provides namespaced targets of the form +``SomePrefix::ThingName``, the project should link to those rather than to +any non-namespaced targets. See the next section for why this is recommended. + +Not all dependencies can be brought into the project this way. Some +dependencies define targets whose names clash with other targets from the +project or other dependencies. Concrete executable and library targets +created by :command:`add_executable` and :command:`add_library` are global, +so each one must be unique across the whole build. If a dependency would +add a clashing target name, it cannot be brought directly into the build +with this method. + +``FetchContent`` And ``find_package()`` Integration +=================================================== + +.. versionadded:: 3.24 + +Some dependencies support being added by either :command:`find_package` or +:module:`FetchContent`. Such dependencies must ensure they define the same +namespaced targets in both installed and built-from-source scenarios. +A consuming project then links to those namespaced targets and can handle +both scenarios transparently, as long as the project does not use anything +else that isn't provided by both methods. + +The project can indicate it is happy to accept a dependency by either method +using the ``FIND_PACKAGE_ARGS`` option to :command:`FetchContent_Declare`. +This allows :command:`FetchContent_MakeAvailable` to try satisfying the +dependency with a call to :command:`find_package` first, using the arguments +after the ``FIND_PACKAGE_ARGS`` keyword, if any. If that doesn't find the +dependency, it is built from source as described previously instead. - find_package(PNG REQUIRED) +.. code-block:: cmake - # Add path to a FindSomePackage.cmake file - list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake") - find_package(SomePackage REQUIRED) + include(FetchContent) + FetchContent_Declare( + googletest + GIT_REPOSITORY https://github.com/google/googletest.git + GIT_TAG 703bd9caab50b139428cea1aaff9974ebee5742e # release-1.10.0 + FIND_PACKAGE_ARGS NAMES GTest + ) + FetchContent_MakeAvailable(googletest) + + add_executable(ThingUnitTest thing_ut.cpp) + target_link_libraries(ThingUnitTest GTest::gtest_main) + +The above example calls +:command:`find_package(googletest NAMES GTest) <find_package>` first. +CMake provides a :module:`FindGTest` module, so if that finds a GTest package +installed somewhere, it will make it available, and the dependency will not be +built from source. If no GTest package is found, it *will* be built from +source. In either case, the ``GTest::gtest_main`` target is expected to be +defined, so we link our unit test executable to that target. + +High-level control is also available through the +:variable:`FETCHCONTENT_TRY_FIND_PACKAGE_MODE` variable. This can be set to +``NEVER`` to disable all redirection to :command:`find_package`. It can be +set to ``ALWAYS`` to try :command:`find_package` even if ``FIND_PACKAGE_ARGS`` +was not specified (this should be used with caution). + +The project might also decide that a particular dependency must be built from +source. This might be needed if a patched or unreleased version of the +dependency is required, or to satisfy some policy that requires all +dependencies to be built from source. The project can enforce this by adding +the ``OVERRIDE_FIND_PACKAGE`` keyword to :command:`FetchContent_Declare`. +A call to :command:`find_package` for that dependency will then be redirected +to :command:`FetchContent_MakeAvailable` instead. - add_executable(MyExe main.cpp) - target_link_libraries(MyExe PRIVATE - PNG::PNG - SomePrefix::LibName - ) +.. code-block:: cmake -The :variable:`<PackageName>_ROOT` variable is also -searched as a prefix for :command:`find_package` calls using -module-file packages such as ``FindSomePackage``. + include(FetchContent) + FetchContent_Declare( + Catch2 + URL https://intranet.mycomp.com/vendored/Catch2_2.13.4_patched.tgz + URL_HASH MD5=abc123... + OVERRIDE_FIND_PACKAGE + ) + + # The following is automatically redirected to FetchContent_MakeAvailable(Catch2) + find_package(Catch2) + +For more advanced use cases, see the +:variable:`CMAKE_FIND_PACKAGE_REDIRECTS_DIR` variable. + +.. _dependency_providers_overview: + +Dependency Providers +==================== + +.. versionadded:: 3.24 + +The preceding section discussed techniques that projects can use to specify +their dependencies. Ideally, the project shouldn't really care where a +dependency comes from, as long as it provides the things it expects (often +just some imported targets). The project says what it needs and may also +specify where to get it from, in the absence of any other details, so that it +can still be built out-of-the-box. + +The developer, on the other hand, may be much more interested in controlling +*how* a dependency is provided to the project. You might want to use a +particular version of a package that you built yourself. You might want +to use a third party package manager. You might want to redirect some +requests to a different URL on a system you control for security or +performance reasons. CMake supports these sort of scenarios through +:ref:`dependency_providers`. + +A dependency provider can be set to intercept :command:`find_package` and +:command:`FetchContent_MakeAvailable` calls. The provider is given an +opportunity to satisfy such requests before falling back to the built-in +implementation if the provider doesn't fulfill it. + +Only one dependency provider can be set, and it can only be set at a very +specific point early in the CMake run. +The :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable lists CMake files +that will be read while processing the first :command:`project()` call (and +only that call). This is the only time a dependency provider may be set. +At most, one single provider is expected to be used throughout the whole +project. + +For some scenarios, the user wouldn't need to know the details of how the +dependency provider is set. A third party may provide a file that can be +added to :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES`, which will set up +the dependency provider on the user's behalf. This is the recommended +approach for package managers. The developer can use such a file like so:: + + cmake -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=/path/to/package_manager/setup.cmake ... + +For details on how to implement your own custom dependency provider, see the +:command:`cmake_language(SET_DEPENDENCY_PROVIDER)` command. diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index f48313a..bceff2d 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -1040,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: @@ -1081,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-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-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index a6d2a05..7a6188a 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -11,40 +11,189 @@ Introduction ============ Generator expressions are evaluated during build system generation to produce -information specific to each build configuration. +information specific to each build configuration. They have the form +``$<...>``. For example: + +.. code-block:: cmake + + target_include_directories(tgt PRIVATE /opt/include/$<CXX_COMPILER_ID>) + +This would expand to ``/opt/include/GNU``, ``/opt/include/Clang``, etc. +depending on the C++ compiler used. Generator expressions are allowed in the context of many target properties, such as :prop_tgt:`LINK_LIBRARIES`, :prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_DEFINITIONS` and others. They may also be used when using commands to populate those properties, such as :command:`target_link_libraries`, :command:`target_include_directories`, :command:`target_compile_definitions` -and others. +and others. They enable conditional linking, conditional definitions used when +compiling, conditional include directories, and more. The conditions may be +based on the build configuration, target properties, platform information, +or any other queryable information. -They enable conditional linking, conditional definitions used when compiling, -conditional include directories, and more. The conditions may be based on -the build configuration, target properties, platform information or any other -queryable information. +Generator expressions can be nested: -Generator expressions have the form ``$<...>``. To avoid confusion, this page -deviates from most of the CMake documentation in that it omits angular brackets -``<...>`` around placeholders like ``condition``, ``string``, ``target``, -among others. +.. code-block:: cmake -Generator expressions can be nested, as shown in most of the examples below. + target_compile_definitions(tgt PRIVATE + $<$<VERSION_LESS:$<CXX_COMPILER_VERSION>,4.2.0>:OLD_COMPILER> + ) -.. _`Boolean Generator Expressions`: +The above would expand to ``OLD_COMPILER`` if the +:variable:`CMAKE_CXX_COMPILER_VERSION <CMAKE_<LANG>_COMPILER_VERSION>` is less +than 4.2.0. -Boolean Generator Expressions -============================= +Whitespace And Quoting +====================== -Boolean expressions evaluate to either ``0`` or ``1``. -They are typically used to construct the condition in a :ref:`conditional -generator expression<Conditional Generator Expressions>`. +Generator expressions are typically parsed after command arguments. +If a generator expression contains spaces, new lines, semicolons or +other characters that may be interpreted as command argument separators, +the whole expression should be surrounded by quotes when passed to a +command. Failure to do so may result in the expression being split and +it may no longer be recognized as a generator expression. -Available boolean expressions are: +When using :command:`add_custom_command` or :command:`add_custom_target`, +use the ``VERBATIM`` and ``COMMAND_EXPAND_LISTS`` options to obtain robust +argument splitting and quoting. -Logical Operators ------------------ +.. code-block:: cmake + + # WRONG: Embedded space will be treated as an argument separator. + # This ends up not being seen as a generator expression at all. + add_custom_target(run_some_tool + COMMAND some_tool -I$<JOIN:$<TARGET_PROPERTY:tgt,INCLUDE_DIRECTORIES>, -I> + VERBATIM + ) + +.. code-block:: cmake + + # Better, but still not robust. Quotes prevent the space from splitting the + # expression. However, the tool will receive the expanded value as a single + # argument. + add_custom_target(run_some_tool + COMMAND some_tool "-I$<JOIN:$<TARGET_PROPERTY:tgt,INCLUDE_DIRECTORIES>, -I>" + VERBATIM + ) + +.. code-block:: cmake + + # Nearly correct. Using a semicolon to separate arguments and adding the + # COMMAND_EXPAND_LISTS option means that paths with spaces will be handled + # correctly. Quoting the whole expression ensures it is seen as a generator + # expression. But if the target property is empty, we will get a bare -I + # with nothing after it. + add_custom_target(run_some_tool + COMMAND some_tool "-I$<JOIN:$<TARGET_PROPERTY:tgt,INCLUDE_DIRECTORIES>,;-I>" + COMMAND_EXPAND_LISTS + VERBATIM + ) + +Using variables to build up a more complex generator expression is also a +good way to reduce errors and improve readability. The above example can be +improved further like so: + +.. code-block:: cmake + + # The $<BOOL:...> check prevents adding anything if the property is empty, + # assuming the property value cannot be one of CMake's false constants. + set(prop "$<TARGET_PROPERTY:tgt,INCLUDE_DIRECTORIES>") + add_custom_target(run_some_tool + COMMAND some_tool "$<$<BOOL:${prop}>:-I$<JOIN:${prop},;-I>>" + COMMAND_EXPAND_LISTS + VERBATIM + ) + +A common mistake is to try to split a generator expression across multiple +lines with indenting: + +.. code-block:: cmake + + # WRONG: New lines and spaces all treated as argument separators, so the + # generator expression is split and not recognized correctly. + target_compile_definitions(tgt PRIVATE + $<$<AND: + $<CXX_COMPILER_ID:GNU>, + $<VERSION_GREATER_EQUAL:$<CXX_COMPILER_VERSION>,5> + >:HAVE_5_OR_LATER> + ) + +Again, use helper variables with well-chosen names to build up a readable +expression instead: + +.. code-block:: cmake + + set(is_gnu "$<CXX_COMPILER_ID:GNU>") + set(v5_or_later "$<VERSION_GREATER_EQUAL:$<CXX_COMPILER_VERSION>,5>") + set(meet_requirements "$<AND:${is_gnu},${v5_or_later}>") + target_compile_definitions(tgt PRIVATE + "$<${meet_requirements}:HAVE_5_OR_LATER>" + ) + +Debugging +========= + +Since generator expressions are evaluated during generation of the buildsystem, +and not during processing of ``CMakeLists.txt`` files, it is not possible to +inspect their result with the :command:`message()` command. One possible way +to generate debug messages is to add a custom target: + +.. code-block:: cmake + + add_custom_target(genexdebug COMMAND ${CMAKE_COMMAND} -E echo "$<...>") + +After running ``cmake``, you can then build the ``genexdebug`` target to print +the result of the ``$<...>`` expression (i.e. run the command +``cmake --build ... --target genexdebug``). + +Another way is to write debug messages to a file with :command:`file(GENERATE)`: + +.. code-block:: cmake + + file(GENERATE OUTPUT filename CONTENT "$<...>") + +Generator Expression Reference +============================== + +.. note:: + + This reference deviates from most of the CMake documentation in that it + omits angular brackets ``<...>`` around placeholders like ``condition``, + ``string``, ``target``, etc. This is to prevent an opportunity for those + placeholders to be misinterpreted as generator expressions. + +.. _`Conditional Generator Expressions`: + +Conditional Expressions +----------------------- + +A fundamental category of generator expressions relates to conditional logic. +Two forms of conditional generator expressions are supported: + +.. genex:: $<condition:true_string> + + Evaluates to ``true_string`` if ``condition`` is ``1``, or an empty string + if ``condition`` evaluates to ``0``. Any other value for ``condition`` + results in an error. + +.. genex:: $<IF:condition,true_string,false_string> + + .. versionadded:: 3.8 + + Evaluates to ``true_string`` if ``condition`` is ``1``, or ``false_string`` + if ``condition`` is ``0``. Any other value for ``condition`` results in an + error. + +Typically, the ``condition`` is itself a generator expression. For instance, +the following expression expands to ``DEBUG_MODE`` when the ``Debug`` +configuration is used, and the empty string for all other configurations: + +.. code-block:: cmake + + $<$<CONFIG:Debug>:DEBUG_MODE> + +Boolean-like ``condition`` values other than ``1`` or ``0`` can be handled +by wrapping them with the ``$<BOOL:...>`` generator expression: .. genex:: $<BOOL:string> @@ -58,46 +207,71 @@ Logical Operators Otherwise evaluates to ``1``. +The ``$<BOOL:...>`` generator expression is often used when a ``condition`` +is provided by a CMake variable: + +.. code-block:: cmake + + $<$<BOOL:${HAVE_SOME_FEATURE}>:-DENABLE_SOME_FEATURE> + + +.. _`Boolean Generator Expressions`: + +Logical Operators +----------------- + +The common boolean logic operators are supported: + .. genex:: $<AND:conditions> - where ``conditions`` is a comma-separated list of boolean expressions. - Evaluates to ``1`` if all conditions are ``1``. - Otherwise evaluates to ``0``. + where ``conditions`` is a comma-separated list of boolean expressions, + all of which must evaluate to either ``1`` or ``0``. The whole expression + evaluates to ``1`` if all conditions are ``1``. If any condition is ``0``, + the whole expression evaluates to ``0``. .. genex:: $<OR:conditions> where ``conditions`` is a comma-separated list of boolean expressions. - Evaluates to ``1`` if at least one of the conditions is ``1``. - Otherwise evaluates to ``0``. + all of which must evaluate to either ``1`` or ``0``. The whole expression + evaluates to ``1`` if at least one of the ``conditions`` is ``1``. If all + ``conditions`` evaluate to ``0``, the whole expression evaluates to ``0``. .. genex:: $<NOT:condition> + ``condition`` must be ``0`` or ``1``. The result of the expression is ``0`` if ``condition`` is ``1``, else ``1``. +.. _`Comparison Expressions`: + +Primary Comparison Expressions +------------------------------ + +CMake supports a variety of generator expressions that compare things. +This section covers the primary and most widely used comparison types. +Other more specific comparison types are documented in their own separate +sections further below. + String Comparisons ------------------- +^^^^^^^^^^^^^^^^^^ .. genex:: $<STREQUAL:string1,string2> ``1`` if ``string1`` and ``string2`` are equal, else ``0``. The comparison is case-sensitive. For a case-insensitive comparison, combine with a :ref:`string transforming generator expression - <String Transforming Generator Expressions>`, + <String Transforming Generator Expressions>`. For example, the following + evaluates to ``1`` if ``${foo}`` is any of ``BAR``, ``Bar``, ``bar``, etc. .. code-block:: cmake - $<STREQUAL:$<UPPER_CASE:${foo}>,"BAR"> # "1" if ${foo} is any of "BAR", "Bar", "bar", ... + $<STREQUAL:$<UPPER_CASE:${foo}>,BAR> .. genex:: $<EQUAL:value1,value2> ``1`` if ``value1`` and ``value2`` are numerically equal, else ``0``. -.. genex:: $<IN_LIST:string,list> - - .. versionadded:: 3.12 - - ``1`` if ``string`` is member of the semicolon-separated ``list``, else ``0``. - Uses case-sensitive comparisons. +Version Comparisons +^^^^^^^^^^^^^^^^^^^ .. genex:: $<VERSION_LESS:v1,v2> @@ -123,206 +297,548 @@ String Comparisons ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``. -Variable Queries +.. _`String Transforming Generator Expressions`: + +String Transformations +---------------------- + +.. genex:: $<LOWER_CASE:string> + + Content of ``string`` converted to lower case. + +.. genex:: $<UPPER_CASE:string> + + Content of ``string`` converted to upper case. + +.. genex:: $<MAKE_C_IDENTIFIER:...> + + Content of ``...`` converted to a C identifier. The conversion follows the + same behavior as :command:`string(MAKE_C_IDENTIFIER)`. + +List Expressions ---------------- -.. genex:: $<TARGET_EXISTS:target> +.. genex:: $<IN_LIST:string,list> .. versionadded:: 3.12 - ``1`` if ``target`` exists, else ``0``. + ``1`` if ``string`` is an item in the semicolon-separated ``list``, else ``0``. + It uses case-sensitive comparisons. -.. genex:: $<CONFIG:cfgs> +.. genex:: $<JOIN:list,string> - ``1`` if config is any one of the entries in comma-separated list - ``cfgs``, else ``0``. This is a case-insensitive comparison. The mapping in - :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by this - expression when it is evaluated on a property on an :prop_tgt:`IMPORTED` - target. + Joins the list with the content of ``string`` inserted between each item. -.. genex:: $<PLATFORM_ID:platform_ids> +.. genex:: $<REMOVE_DUPLICATES:list> - where ``platform_ids`` is a comma-separated list. - ``1`` if the CMake's platform id matches any one of the entries in - ``platform_ids``, otherwise ``0``. - See also the :variable:`CMAKE_SYSTEM_NAME` variable. + .. versionadded:: 3.15 -.. genex:: $<C_COMPILER_ID:compiler_ids> + 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. - where ``compiler_ids`` is a comma-separated list. - ``1`` if the CMake's compiler id of the C compiler matches any one - of the entries in ``compiler_ids``, otherwise ``0``. - See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +.. genex:: $<FILTER:list,INCLUDE|EXCLUDE,regex> -.. genex:: $<CXX_COMPILER_ID:compiler_ids> + .. versionadded:: 3.15 - where ``compiler_ids`` is a comma-separated list. - ``1`` if the CMake's compiler id of the CXX compiler matches any one - of the entries in ``compiler_ids``, otherwise ``0``. - See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. + Includes or removes items from ``list`` that match the regular expression + ``regex``. -.. genex:: $<CUDA_COMPILER_ID:compiler_ids> +Path Expressions +---------------- - .. versionadded:: 3.15 +Most of the expressions in this section are closely associated with the +:command:`cmake_path` command, providing the same capabilities, but in +the form of a generator expression. - where ``compiler_ids`` is a comma-separated list. - ``1`` if the CMake's compiler id of the CUDA compiler matches any one - of the entries in ``compiler_ids``, otherwise ``0``. - See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +For all generator expressions in this section, paths are expected to be in +cmake-style format. The :ref:`$\<PATH:CMAKE_PATH\> <GenEx PATH-CMAKE_PATH>` +generator expression can be used to convert a native path to a cmake-style +one. -.. genex:: $<OBJC_COMPILER_ID:compiler_ids> +.. _GenEx Path Comparisons: - .. versionadded:: 3.16 +Path Comparisons +^^^^^^^^^^^^^^^^ - where ``compiler_ids`` is a comma-separated list. - ``1`` if the CMake's compiler id of the Objective-C compiler matches any one - of the entries in ``compiler_ids``, otherwise ``0``. - See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +.. genex:: $<PATH_EQUAL:path1,path2> -.. genex:: $<OBJCXX_COMPILER_ID:compiler_ids> + .. versionadded:: 3.24 - .. versionadded:: 3.16 + Compares the lexical representations of two paths. No normalization is + performed on either path. Returns ``1`` if the paths are equal, ``0`` + otherwise. - where ``compiler_ids`` is a comma-separated list. - ``1`` if the CMake's compiler id of the Objective-C++ compiler matches any one - of the entries in ``compiler_ids``, otherwise ``0``. - See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. + See :ref:`cmake_path(COMPARE) <Path COMPARE>` for more details. -.. genex:: $<Fortran_COMPILER_ID:compiler_ids> +.. _GenEx Path Queries: - where ``compiler_ids`` is a comma-separated list. - ``1`` if the CMake's compiler id of the Fortran compiler matches any one - of the entries in ``compiler_ids``, otherwise ``0``. - See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +Path Queries +^^^^^^^^^^^^ -.. genex:: $<HIP_COMPILER_ID:compiler_ids> +These expressions provide the generation-time capabilities equivalent to the +:ref:`Query <Path Query>` options of the :command:`cmake_path` command. +All paths are expected to be in cmake-style format. - .. versionadded:: 3.21 +.. genex:: $<PATH:HAS_*,path> - where ``compiler_ids`` is a comma-separated list. - ``1`` if the CMake's compiler id of the HIP compiler matches any one - of the entries in ``compiler_ids``, otherwise ``0``. - See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. + .. versionadded:: 3.24 -.. genex:: $<ISPC_COMPILER_ID:compiler_ids> + The following operations return ``1`` if the particular path component is + present, ``0`` otherwise. See :ref:`Path Structure And Terminology` for the + meaning of each path component. - .. versionadded:: 3.19 + :: - where ``compiler_ids`` is a comma-separated list. - ``1`` if the CMake's compiler id of the ISPC compiler matches any one - of the entries in ``compiler_ids``, otherwise ``0``. - See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. + $<PATH:HAS_ROOT_NAME,path> + $<PATH:HAS_ROOT_DIRECTORY,path> + $<PATH:HAS_ROOT_PATH,path> + $<PATH:HAS_FILENAME,path> + $<PATH:HAS_EXTENSION,path> + $<PATH:HAS_STEM,path> + $<PATH:HAS_RELATIVE_PART,path> + $<PATH:HAS_PARENT_PATH,path> + + Note the following special cases: + + * For ``HAS_ROOT_PATH``, a true result will only be returned if at least one + of ``root-name`` or ``root-directory`` is non-empty. + + * For ``HAS_PARENT_PATH``, the root directory is also considered to have a + parent, which will be itself. The result is true except if the path + consists of just a :ref:`filename <FILENAME_DEF>`. + +.. genex:: $<PATH:IS_ABSOLUTE,path> + + .. versionadded:: 3.24 + + Returns ``1`` if the path is :ref:`absolute <IS_ABSOLUTE>`, ``0`` otherwise. + +.. genex:: $<PATH:IS_RELATIVE,path> + + .. versionadded:: 3.24 + + This will return the opposite of ``IS_ABSOLUTE``. + +.. genex:: $<PATH:IS_PREFIX[,NORMALIZE],path,input> + + .. versionadded:: 3.24 + + Returns ``1`` if ``path`` is the prefix of ``input``, ``0`` otherwise. + + When the ``NORMALIZE`` option is specified, ``path`` and ``input`` are + :ref:`normalized <Normalization>` before the check. + +.. _GenEx Path Decomposition: + +Path Decomposition +^^^^^^^^^^^^^^^^^^ + +These expressions provide the generation-time capabilities equivalent to the +:ref:`Decomposition <Path Decomposition>` options of the :command:`cmake_path` +command. All paths are expected to be in cmake-style format. + +.. genex:: $<PATH:GET_*,...> + + .. versionadded:: 3.24 + + The following operations retrieve a different component or group of + components from a path. See :ref:`Path Structure And Terminology` for the + meaning of each path component. + + :: + + $<PATH:GET_ROOT_NAME,path> + $<PATH:GET_ROOT_DIRECTORY,path> + $<PATH:GET_ROOT_PATH,path> + $<PATH:GET_FILENAME,path> + $<PATH:GET_EXTENSION[,LAST_ONLY],path> + $<PATH:GET_STEM[,LAST_ONLY],path> + $<PATH:GET_RELATIVE_PART,path> + $<PATH:GET_PARENT_PATH,path> + + If a requested component is not present in the path, an empty string is + returned. + +.. _GenEx Path Transformations: + +Path Transformations +^^^^^^^^^^^^^^^^^^^^ + +These expressions provide the generation-time capabilities equivalent to the +:ref:`Modification <Path Modification>` and :ref:`Generation <Path Generation>` +options of the :command:`cmake_path` command. All paths are expected to be +in cmake-style format. + +.. _GenEx PATH-CMAKE_PATH: + +.. genex:: $<PATH:CMAKE_PATH[,NORMALIZE],path> + + .. versionadded:: 3.24 + + Returns ``path``. If ``path`` is a native path, it is converted into a + cmake-style path with forward-slashes (``/``). On Windows, the long filename + marker is taken into account. + + When the ``NORMALIZE`` option is specified, the path is :ref:`normalized + <Normalization>` after the conversion. + +.. genex:: $<PATH:APPEND,path,input,...> + + .. versionadded:: 3.24 + + Returns all the ``input`` arguments appended to ``path`` using ``/`` as the + ``directory-separator``. Depending on the ``input``, the value of ``path`` + may be discarded. + + See :ref:`cmake_path(APPEND) <APPEND>` for more details. + +.. genex:: $<PATH:REMOVE_FILENAME,path> + + .. versionadded:: 3.24 + + Returns ``path`` with filename component (as returned by + ``$<PATH:GET_FILENAME>``) removed. After removal, any trailing + ``directory-separator`` is left alone, if present. + + See :ref:`cmake_path(REMOVE_FILENAME) <REMOVE_FILENAME>` for more details. + +.. genex:: $<PATH:REPLACE_FILENAME,path,input> + + .. versionadded:: 3.24 + + Returns ``path`` with the filename component replaced by ``input``. If + ``path`` has no filename component (i.e. ``$<PATH:HAS_FILENAME>`` returns + ``0``), ``path`` is unchanged. + + See :ref:`cmake_path(REPLACE_FILENAME) <REPLACE_FILENAME>` for more details. + +.. genex:: $<PATH:REMOVE_EXTENSION[,LAST_ONLY],path> + + .. versionadded:: 3.24 + + Returns ``path`` with the :ref:`extension <EXTENSION_DEF>` removed, if any. + + See :ref:`cmake_path(REMOVE_EXTENSION) <REMOVE_EXTENSION>` for more details. + +.. genex:: $<PATH:REPLACE_EXTENSION[,LAST_ONLY],path,input> + + .. versionadded:: 3.24 + + Returns ``path`` with the :ref:`extension <EXTENSION_DEF>` replaced by + ``input``, if any. + + See :ref:`cmake_path(REPLACE_EXTENSION) <REPLACE_EXTENSION>` for more details. + +.. genex:: $<PATH:NORMAL_PATH,path> + + .. versionadded:: 3.24 + + Returns ``path`` normalized according to the steps described in + :ref:`Normalization`. + +.. genex:: $<PATH:RELATIVE_PATH,path,base_directory> + + .. versionadded:: 3.24 + + Returns ``path``, modified to make it relative to the ``base_directory`` + argument. + + See :ref:`cmake_path(RELATIVE_PATH) <cmake_path-RELATIVE_PATH>` for more + details. + +.. genex:: $<PATH:ABSOLUTE_PATH[,NORMALIZE],path,base_directory> + + .. versionadded:: 3.24 + + Returns ``path`` as absolute. If ``path`` is a relative path + (``$<PATH:IS_RELATIVE>`` returns ``1``), it is evaluated relative to the + given base directory specified by ``base_directory`` argument. + + When the ``NORMALIZE`` option is specified, the path is + :ref:`normalized <Normalization>` after the path computation. + + See :ref:`cmake_path(ABSOLUTE_PATH) <ABSOLUTE_PATH>` for more details. + +Shell Paths +^^^^^^^^^^^ + +.. genex:: $<SHELL_PATH:...> + + .. versionadded:: 3.4 + + Content of ``...`` converted to shell path style. For example, slashes are + converted to backslashes in Windows shells and drive letters are converted + to posix paths in MSYS shells. The ``...`` must be an absolute path. + + .. versionadded:: 3.14 + The ``...`` may be a :ref:`semicolon-separated list <CMake Language Lists>` + of paths, in which case each path is converted individually and a result + list is generated using the shell path separator (``:`` on POSIX and + ``;`` on Windows). Be sure to enclose the argument containing this genex + in double quotes in CMake source code so that ``;`` does not split arguments. + +Configuration Expressions +------------------------- + +.. genex:: $<CONFIG> + + Configuration name. Use this instead of the deprecated :genex:`CONFIGURATION` + generator expression. + +.. genex:: $<CONFIG:cfgs> + + ``1`` if config is any one of the entries in comma-separated list + ``cfgs``, else ``0``. This is a case-insensitive comparison. The mapping in + :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by this + expression when it is evaluated on a property of an :prop_tgt:`IMPORTED` + target. + +.. genex:: $<OUTPUT_CONFIG:...> + + .. versionadded:: 3.20 + + Only valid in :command:`add_custom_command` and :command:`add_custom_target` + as the outer-most generator expression in an argument. + With the :generator:`Ninja Multi-Config` generator, generator expressions + in ``...`` are evaluated using the custom command's "output config". + With other generators, the content of ``...`` is evaluated normally. + +.. genex:: $<COMMAND_CONFIG:...> + + .. versionadded:: 3.20 + + Only valid in :command:`add_custom_command` and :command:`add_custom_target` + as the outer-most generator expression in an argument. + With the :generator:`Ninja Multi-Config` generator, generator expressions + in ``...`` are evaluated using the custom command's "command config". + With other generators, the content of ``...`` is evaluated normally. + +Toolchain And Language Expressions +---------------------------------- + +Platform +^^^^^^^^ + +.. genex:: $<PLATFORM_ID> + + The current system's CMake platform id. + See also the :variable:`CMAKE_SYSTEM_NAME` variable. + +.. genex:: $<PLATFORM_ID:platform_ids> + + where ``platform_ids`` is a comma-separated list. + ``1`` if CMake's platform id matches any one of the entries in + ``platform_ids``, otherwise ``0``. + See also the :variable:`CMAKE_SYSTEM_NAME` variable. + +Compiler Version +^^^^^^^^^^^^^^^^ + +See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable, which is +closely related to the expressions in this sub-section. + +.. genex:: $<C_COMPILER_VERSION> + + The version of the C compiler used. .. genex:: $<C_COMPILER_VERSION:version> ``1`` if the version of the C compiler matches ``version``, otherwise ``0``. - See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. + +.. genex:: $<CXX_COMPILER_VERSION> + + The version of the CXX compiler used. .. genex:: $<CXX_COMPILER_VERSION:version> ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. - See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. + +.. genex:: $<CUDA_COMPILER_VERSION> + + .. versionadded:: 3.15 + + The version of the CUDA compiler used. .. genex:: $<CUDA_COMPILER_VERSION:version> .. versionadded:: 3.15 ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. - See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. + +.. genex:: $<OBJC_COMPILER_VERSION> + + .. versionadded:: 3.16 + + The version of the OBJC compiler used. .. genex:: $<OBJC_COMPILER_VERSION:version> .. versionadded:: 3.16 ``1`` if the version of the OBJC compiler matches ``version``, otherwise ``0``. - See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. + +.. genex:: $<OBJCXX_COMPILER_VERSION> + + .. versionadded:: 3.16 + + The version of the OBJCXX compiler used. .. genex:: $<OBJCXX_COMPILER_VERSION:version> .. versionadded:: 3.16 ``1`` if the version of the OBJCXX compiler matches ``version``, otherwise ``0``. - See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. + +.. genex:: $<Fortran_COMPILER_VERSION> + + The version of the Fortran compiler used. .. genex:: $<Fortran_COMPILER_VERSION:version> ``1`` if the version of the Fortran compiler matches ``version``, otherwise ``0``. - See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. + +.. genex:: $<HIP_COMPILER_VERSION> + + .. versionadded:: 3.21 + + The version of the HIP compiler used. .. genex:: $<HIP_COMPILER_VERSION:version> .. versionadded:: 3.21 ``1`` if the version of the HIP compiler matches ``version``, otherwise ``0``. - See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. + +.. genex:: $<ISPC_COMPILER_VERSION> + + .. versionadded:: 3.19 + + The version of the ISPC compiler used. .. genex:: $<ISPC_COMPILER_VERSION:version> .. versionadded:: 3.19 ``1`` if the version of the ISPC compiler matches ``version``, otherwise ``0``. - See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. -.. genex:: $<TARGET_POLICY:policy> +Compiler Language And ID +^^^^^^^^^^^^^^^^^^^^^^^^ - ``1`` if the ``policy`` was NEW when the 'head' target was created, - else ``0``. If the ``policy`` was not set, the warning message for the policy - will be emitted. This generator expression only works for a subset of - policies. +See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable, which is closely +related to most of the expressions in this sub-section. -.. genex:: $<COMPILE_FEATURES:features> +.. genex:: $<C_COMPILER_ID> - .. versionadded:: 3.1 + CMake's compiler id of the C compiler used. - where ``features`` is a comma-spearated list. - Evaluates to ``1`` if all of the ``features`` are available for the 'head' - target, and ``0`` otherwise. If this expression is used while evaluating - the link implementation of a target and if any dependency transitively - increases the required :prop_tgt:`C_STANDARD` or :prop_tgt:`CXX_STANDARD` - for the 'head' target, an error is reported. See the - :manual:`cmake-compile-features(7)` manual for information on - compile features and a list of supported compilers. +.. genex:: $<C_COMPILER_ID:compiler_ids> -.. _`Boolean COMPILE_LANGUAGE Generator Expression`: + where ``compiler_ids`` is a comma-separated list. + ``1`` if CMake's compiler id of the C compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. -.. genex:: $<COMPILE_LANG_AND_ID:language,compiler_ids> +.. genex:: $<CXX_COMPILER_ID> + + CMake's compiler id of the CXX compiler used. + +.. genex:: $<CXX_COMPILER_ID:compiler_ids> + + where ``compiler_ids`` is a comma-separated list. + ``1`` if CMake's compiler id of the CXX compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + +.. genex:: $<CUDA_COMPILER_ID> .. versionadded:: 3.15 - ``1`` when the language used for compilation unit matches ``language`` and - the CMake's compiler id of the language compiler matches any one of the - entries in ``compiler_ids``, otherwise ``0``. This expression is a short form - for the combination of ``$<COMPILE_LANGUAGE:language>`` and - ``$<LANG_COMPILER_ID:compiler_ids>``. This expression may be used to specify - compile options, compile definitions, and include directories for source files of a - particular language and compiler combination in a target. For example: + CMake's compiler id of the CUDA compiler used. - .. code-block:: cmake +.. genex:: $<CUDA_COMPILER_ID:compiler_ids> - add_executable(myapp main.cpp foo.c bar.cpp zot.cu) - target_compile_definitions(myapp - PRIVATE $<$<COMPILE_LANG_AND_ID:CXX,AppleClang,Clang>:COMPILING_CXX_WITH_CLANG> - $<$<COMPILE_LANG_AND_ID:CXX,Intel>:COMPILING_CXX_WITH_INTEL> - $<$<COMPILE_LANG_AND_ID:C,Clang>:COMPILING_C_WITH_CLANG> - ) + .. versionadded:: 3.15 - This specifies the use of different compile definitions based on both - the compiler id and compilation language. This example will have a - ``COMPILING_CXX_WITH_CLANG`` compile definition when Clang is the CXX - compiler, and ``COMPILING_CXX_WITH_INTEL`` when Intel is the CXX compiler. - Likewise when the C compiler is Clang it will only see the ``COMPILING_C_WITH_CLANG`` - definition. + where ``compiler_ids`` is a comma-separated list. + ``1`` if CMake's compiler id of the CUDA compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. - Without the ``COMPILE_LANG_AND_ID`` generator expression the same logic - would be expressed as: +.. genex:: $<OBJC_COMPILER_ID> - .. code-block:: cmake + .. versionadded:: 3.16 - target_compile_definitions(myapp - PRIVATE $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:AppleClang,Clang>>:COMPILING_CXX_WITH_CLANG> - $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:Intel>>:COMPILING_CXX_WITH_INTEL> - $<$<AND:$<COMPILE_LANGUAGE:C>,$<C_COMPILER_ID:Clang>>:COMPILING_C_WITH_CLANG> - ) + CMake's compiler id of the OBJC compiler used. + +.. genex:: $<OBJC_COMPILER_ID:compiler_ids> + + .. versionadded:: 3.16 + + where ``compiler_ids`` is a comma-separated list. + ``1`` if CMake's compiler id of the Objective-C compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + +.. genex:: $<OBJCXX_COMPILER_ID> + + .. versionadded:: 3.16 + + CMake's compiler id of the OBJCXX compiler used. + +.. genex:: $<OBJCXX_COMPILER_ID:compiler_ids> + + .. versionadded:: 3.16 + + where ``compiler_ids`` is a comma-separated list. + ``1`` if CMake's compiler id of the Objective-C++ compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + +.. genex:: $<Fortran_COMPILER_ID> + + CMake's compiler id of the Fortran compiler used. + +.. genex:: $<Fortran_COMPILER_ID:compiler_ids> + + where ``compiler_ids`` is a comma-separated list. + ``1`` if CMake's compiler id of the Fortran compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + +.. genex:: $<HIP_COMPILER_ID> + + .. versionadded:: 3.21 + + CMake's compiler id of the HIP compiler used. + +.. genex:: $<HIP_COMPILER_ID:compiler_ids> + + .. versionadded:: 3.21 + + where ``compiler_ids`` is a comma-separated list. + ``1`` if CMake's compiler id of the HIP compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + +.. genex:: $<ISPC_COMPILER_ID> + + .. versionadded:: 3.19 + + CMake's compiler id of the ISPC compiler used. + +.. genex:: $<ISPC_COMPILER_ID:compiler_ids> + + .. versionadded:: 3.19 + + where ``compiler_ids`` is a comma-separated list. + ``1`` if CMake's compiler id of the ISPC compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + +.. genex:: $<COMPILE_LANGUAGE> + + .. versionadded:: 3.3 + + The compile language of source files when evaluating compile options. + See :ref:`the related boolean expression + <Boolean COMPILE_LANGUAGE Generator Expression>` + ``$<COMPILE_LANGUAGE:language>`` + for notes about the portability of this generator expression. + +.. _`Boolean COMPILE_LANGUAGE Generator Expression`: .. genex:: $<COMPILE_LANGUAGE:languages> @@ -330,8 +846,8 @@ Variable Queries ``1`` when the language used for compilation unit matches any of the entries in ``languages``, otherwise ``0``. This expression may be used to specify - compile options, compile definitions, and include directories for source files of a - particular language in a target. For example: + compile options, compile definitions, and include directories for source + files of a particular language in a target. For example: .. code-block:: cmake @@ -370,49 +886,82 @@ Variable Queries add_executable(myapp main.cpp) target_link_libraries(myapp myapp_c myapp_cxx) -.. _`Boolean LINK_LANGUAGE Generator Expression`: - -.. genex:: $<LINK_LANG_AND_ID:language,compiler_ids> +.. genex:: $<COMPILE_LANG_AND_ID:language,compiler_ids> - .. versionadded:: 3.18 + .. versionadded:: 3.15 - ``1`` when the language used for link step matches ``language`` and the - CMake's compiler id of the language linker matches any one of the entries - in ``compiler_ids``, otherwise ``0``. This expression is a short form for the - combination of ``$<LINK_LANGUAGE:language>`` and + ``1`` when the language used for compilation unit matches ``language`` and + CMake's compiler id of the ``language`` compiler matches any one of the + entries in ``compiler_ids``, otherwise ``0``. This expression is a short form + for the combination of ``$<COMPILE_LANGUAGE:language>`` and ``$<LANG_COMPILER_ID:compiler_ids>``. This expression may be used to specify - link libraries, link options, link directories and link dependencies of a - particular language and linker combination in a target. For example: + compile options, compile definitions, and include directories for source + files of a particular language and compiler combination in a target. + For example: .. code-block:: cmake - add_library(libC_Clang ...) - add_library(libCXX_Clang ...) - add_library(libC_Intel ...) - add_library(libCXX_Intel ...) + add_executable(myapp main.cpp foo.c bar.cpp zot.cu) + target_compile_definitions(myapp + PRIVATE $<$<COMPILE_LANG_AND_ID:CXX,AppleClang,Clang>:COMPILING_CXX_WITH_CLANG> + $<$<COMPILE_LANG_AND_ID:CXX,Intel>:COMPILING_CXX_WITH_INTEL> + $<$<COMPILE_LANG_AND_ID:C,Clang>:COMPILING_C_WITH_CLANG> + ) - add_executable(myapp main.c) - if (CXX_CONFIG) - target_sources(myapp PRIVATE file.cxx) - endif() - target_link_libraries(myapp - PRIVATE $<$<LINK_LANG_AND_ID:CXX,Clang,AppleClang>:libCXX_Clang> - $<$<LINK_LANG_AND_ID:C,Clang,AppleClang>:libC_Clang> - $<$<LINK_LANG_AND_ID:CXX,Intel>:libCXX_Intel> - $<$<LINK_LANG_AND_ID:C,Intel>:libC_Intel>) + This specifies the use of different compile definitions based on both + the compiler id and compilation language. This example will have a + ``COMPILING_CXX_WITH_CLANG`` compile definition when Clang is the CXX + compiler, and ``COMPILING_CXX_WITH_INTEL`` when Intel is the CXX compiler. + Likewise, when the C compiler is Clang, it will only see the + ``COMPILING_C_WITH_CLANG`` definition. - This specifies the use of different link libraries based on both the - compiler id and link language. This example will have target ``libCXX_Clang`` - as link dependency when ``Clang`` or ``AppleClang`` is the ``CXX`` - linker, and ``libCXX_Intel`` when ``Intel`` is the ``CXX`` linker. - Likewise when the ``C`` linker is ``Clang`` or ``AppleClang``, target - ``libC_Clang`` will be added as link dependency and ``libC_Intel`` when - ``Intel`` is the ``C`` linker. + Without the ``COMPILE_LANG_AND_ID`` generator expression, the same logic + would be expressed as: - See :ref:`the note related to - <Constraints LINK_LANGUAGE Generator Expression>` - ``$<LINK_LANGUAGE:language>`` for constraints about the usage of this - generator expression. + .. code-block:: cmake + + target_compile_definitions(myapp + PRIVATE $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:AppleClang,Clang>>:COMPILING_CXX_WITH_CLANG> + $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:Intel>>:COMPILING_CXX_WITH_INTEL> + $<$<AND:$<COMPILE_LANGUAGE:C>,$<C_COMPILER_ID:Clang>>:COMPILING_C_WITH_CLANG> + ) + +Compile Features +^^^^^^^^^^^^^^^^ + +.. genex:: $<COMPILE_FEATURES:features> + + .. versionadded:: 3.1 + + where ``features`` is a comma-separated list. + Evaluates to ``1`` if all of the ``features`` are available for the 'head' + target, and ``0`` otherwise. If this expression is used while evaluating + the link implementation of a target and if any dependency transitively + increases the required :prop_tgt:`C_STANDARD` or :prop_tgt:`CXX_STANDARD` + for the 'head' target, an error is reported. See the + :manual:`cmake-compile-features(7)` manual for information on + compile features and a list of supported compilers. + +Linker Language And ID +^^^^^^^^^^^^^^^^^^^^^^ + +.. genex:: $<LINK_LANGUAGE> + + .. versionadded:: 3.18 + + The link language of the target when evaluating link options. + See :ref:`the related boolean expression + <Boolean LINK_LANGUAGE Generator Expression>` ``$<LINK_LANGUAGE:languages>`` + for notes about the portability of this generator expression. + + .. note:: + + This generator expression is not supported by the link libraries + properties to avoid side-effects due to the double evaluation of + these properties. + + +.. _`Boolean LINK_LANGUAGE Generator Expression`: .. genex:: $<LINK_LANGUAGE:languages> @@ -428,7 +977,7 @@ Variable Queries add_library(api_C ...) add_library(api_CXX ...) add_library(api INTERFACE) - target_link_options(api INTERFACE $<$<LINK_LANGUAGE:C>:-opt_c> + target_link_options(api INTERFACE $<$<LINK_LANGUAGE:C>:-opt_c> $<$<LINK_LANGUAGE:CXX>:-opt_cxx>) target_link_libraries(api INTERFACE $<$<LINK_LANGUAGE:C>:api_C> $<$<LINK_LANGUAGE:CXX>:api_CXX>) @@ -479,360 +1028,400 @@ Variable Queries evaluation will give ``C`` as link language, so the second pass will correctly add target ``libother`` as link dependency. -.. genex:: $<DEVICE_LINK:list> - - .. versionadded:: 3.18 - - Returns the list if it is the device link step, an empty list otherwise. - The device link step is controlled by :prop_tgt:`CUDA_SEPARABLE_COMPILATION` - and :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties and - policy :policy:`CMP0105`. This expression can only be used to specify link - options. - -.. genex:: $<HOST_LINK:list> +.. genex:: $<LINK_LANG_AND_ID:language,compiler_ids> .. versionadded:: 3.18 - Returns the list if it is the normal link step, an empty list otherwise. - This expression is mainly useful when a device link step is also involved - (see ``$<DEVICE_LINK:list>`` generator expression). This expression can only - be used to specify link options. - -String-Valued Generator Expressions -=================================== - -These expressions expand to some string. -For example, + ``1`` when the language used for link step matches ``language`` and the + CMake's compiler id of the language linker matches any one of the entries + in ``compiler_ids``, otherwise ``0``. This expression is a short form for the + combination of ``$<LINK_LANGUAGE:language>`` and + ``$<LANG_COMPILER_ID:compiler_ids>``. This expression may be used to specify + link libraries, link options, link directories and link dependencies of a + particular language and linker combination in a target. For example: -.. code-block:: cmake + .. code-block:: cmake - include_directories(/usr/include/$<CXX_COMPILER_ID>/) + add_library(libC_Clang ...) + add_library(libCXX_Clang ...) + add_library(libC_Intel ...) + add_library(libCXX_Intel ...) -expands to ``/usr/include/GNU/`` or ``/usr/include/Clang/`` etc, depending on -the compiler identifier. + add_executable(myapp main.c) + if (CXX_CONFIG) + target_sources(myapp PRIVATE file.cxx) + endif() + target_link_libraries(myapp + PRIVATE $<$<LINK_LANG_AND_ID:CXX,Clang,AppleClang>:libCXX_Clang> + $<$<LINK_LANG_AND_ID:C,Clang,AppleClang>:libC_Clang> + $<$<LINK_LANG_AND_ID:CXX,Intel>:libCXX_Intel> + $<$<LINK_LANG_AND_ID:C,Intel>:libC_Intel>) -String-valued expressions may also be combined with other expressions. -Here an example for a string-valued expression within a boolean expressions -within a conditional expression: + This specifies the use of different link libraries based on both the + compiler id and link language. This example will have target ``libCXX_Clang`` + as link dependency when ``Clang`` or ``AppleClang`` is the ``CXX`` + linker, and ``libCXX_Intel`` when ``Intel`` is the ``CXX`` linker. + Likewise when the ``C`` linker is ``Clang`` or ``AppleClang``, target + ``libC_Clang`` will be added as link dependency and ``libC_Intel`` when + ``Intel`` is the ``C`` linker. -.. code-block:: cmake + See :ref:`the note related to + <Constraints LINK_LANGUAGE Generator Expression>` + ``$<LINK_LANGUAGE:language>`` for constraints about the usage of this + generator expression. - $<$<VERSION_LESS:$<CXX_COMPILER_VERSION>,4.2.0>:OLD_COMPILER> +Link Features +^^^^^^^^^^^^^ -expands to ``OLD_COMPILER`` if the -:variable:`CMAKE_CXX_COMPILER_VERSION <CMAKE_<LANG>_COMPILER_VERSION>` is less -than 4.2.0. +.. genex:: $<LINK_LIBRARY:feature,library-list> -And here two nested string-valued expressions: + .. versionadded:: 3.24 -.. code-block:: cmake + Specify a set of libraries to link to a target, along with a ``feature`` + which provides details about *how* they should be linked. For example: - -I$<JOIN:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>, -I> + .. code-block:: cmake -generates a string of the entries in the :prop_tgt:`INCLUDE_DIRECTORIES` target -property with each entry preceded by ``-I``. + add_library(lib1 STATIC ...) + add_library(lib2 ...) + target_link_libraries(lib2 PRIVATE "$<LINK_LIBRARY:WHOLE_ARCHIVE,lib1>") -Expanding on the previous example, if one first wants to check if the -``INCLUDE_DIRECTORIES`` property is non-empty, then it is advisable to -introduce a helper variable to keep the code readable: + This specifies that ``lib2`` should link to ``lib1`` and use the + ``WHOLE_ARCHIVE`` feature when doing so. -.. code-block:: cmake + Feature names are case-sensitive and may only contain letters, numbers and + underscores. Feature names defined in all uppercase are reserved for CMake's + own built-in features. The pre-defined built-in library features are: - set(prop "$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>") # helper variable - $<$<BOOL:${prop}>:-I$<JOIN:${prop}, -I>> + .. include:: ../variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt -The following string-valued generator expressions are available: + Built-in and custom library features are defined in terms of the following + variables: -Escaped Characters ------------------- + * :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>` -String literals to escape the special meaning a character would otherwise have: + The value used for each of these variables is the value as set at the end of + the directory scope in which the target was created. The usage is as follows: -.. genex:: $<ANGLE-R> + 1. If the language-specific + :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` variable + is true, the ``feature`` must be defined by the corresponding + :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` variable. + 2. If no language-specific ``feature`` is supported, then the + :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` variable must be + true and the ``feature`` must be defined by the corresponding + :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variable. - A literal ``>``. Used for example to compare strings that contain a ``>``. + The following limitations should be noted: -.. genex:: $<COMMA> + * The ``library-list`` can specify CMake targets or libraries. + Any CMake target of type :ref:`OBJECT <Object Libraries>` + or :ref:`INTERFACE <Interface Libraries>` will ignore the feature aspect + of the expression and instead be linked in the standard way. - A literal ``,``. Used for example to compare strings which contain a ``,``. + * The ``$<LINK_LIBRARY:...>`` generator expression can only be used to + specify link libraries. In practice, this means it can appear in the + :prop_tgt:`LINK_LIBRARIES`, :prop_tgt:`INTERFACE_LINK_LIBRARIES`, and + :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` target properties, and be + specified in :command:`target_link_libraries` and :command:`link_libraries` + commands. -.. genex:: $<SEMICOLON> + * If a ``$<LINK_LIBRARY:...>`` generator expression appears in the + :prop_tgt:`INTERFACE_LINK_LIBRARIES` property of a target, it will be + included in the imported target generated by a :command:`install(EXPORT)` + command. It is the responsibility of the environment consuming this + import to define the link feature used by this expression. - A literal ``;``. Used to prevent list expansion on an argument with ``;``. + * Each target or library involved in the link step must have at most only + one kind of library feature. The absence of a feature is also incompatible + with all other features. For example: -.. _`Conditional Generator Expressions`: + .. code-block:: cmake -Conditional Expressions ------------------------ + add_library(lib1 ...) + add_library(lib2 ...) + add_library(lib3 ...) -Conditional generator expressions depend on a boolean condition -that must be ``0`` or ``1``. + # lib1 will be associated with feature1 + target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature1,lib1>") -.. genex:: $<condition:true_string> + # lib1 is being linked with no feature here. This conflicts with the + # use of feature1 in the line above and would result in an error. + target_link_libraries(lib3 PRIVATE lib1 lib2) - Evaluates to ``true_string`` if ``condition`` is ``1``. - Otherwise evaluates to the empty string. + Where it isn't possible to use the same feature throughout a build for a + given target or library, the :prop_tgt:`LINK_LIBRARY_OVERRIDE` and + :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties can be + used to resolve such incompatibilities. -.. genex:: $<IF:condition,true_string,false_string> + * The ``$<LINK_LIBRARY:...>`` generator expression does not guarantee + that the list of specified targets and libraries will be kept grouped + together. To manage constructs like ``--start-group`` and ``--end-group``, + as supported by the GNU ``ld`` linker, use the :genex:`LINK_GROUP` + generator expression instead. - .. versionadded:: 3.8 +.. genex:: $<LINK_GROUP:feature,library-list> - Evaluates to ``true_string`` if ``condition`` is ``1``. - Otherwise evaluates to ``false_string``. + .. versionadded:: 3.24 -Typically, the ``condition`` is a :ref:`boolean generator expression -<Boolean Generator Expressions>`. For instance, + Specify a group of libraries to link to a target, along with a ``feature`` + which defines how that group should be linked. For example: -.. code-block:: cmake + .. code-block:: cmake - $<$<CONFIG:Debug>:DEBUG_MODE> + add_library(lib1 STATIC ...) + add_library(lib2 ...) + target_link_libraries(lib2 PRIVATE "$<LINK_GROUP:RESCAN,lib1,external>") -expands to ``DEBUG_MODE`` when the ``Debug`` configuration is used, and -otherwise expands to the empty string. + This specifies that ``lib2`` should link to ``lib1`` and ``external``, and + that both of those two libraries should be included on the linker command + line according to the definition of the ``RESCAN`` feature. -.. _`String Transforming Generator Expressions`: + Feature names are case-sensitive and may only contain letters, numbers and + underscores. Feature names defined in all uppercase are reserved for CMake's + own built-in features. Currently, there is only one pre-defined built-in + group feature: -String Transformations ----------------------- + .. include:: ../variable/LINK_GROUP_PREDEFINED_FEATURES.txt -.. genex:: $<JOIN:list,string> + Built-in and custom group features are defined in terms of the following + variables: - Joins the list with the content of ``string``. + * :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>` -.. genex:: $<REMOVE_DUPLICATES:list> + The value used for each of these variables is the value as set at the end of + the directory scope in which the target was created. The usage is as follows: - .. versionadded:: 3.15 + 1. If the language-specific + :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` variable + is true, the ``feature`` must be defined by the corresponding + :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` variable. + 2. If no language-specific ``feature`` is supported, then the + :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED` variable must be + true and the ``feature`` must be defined by the corresponding + :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` variable. - Removes duplicated items in the given ``list``. + The ``LINK_GROUP`` generator 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. -.. genex:: $<FILTER:list,INCLUDE|EXCLUDE,regex> + Each target or external library involved in the link step is allowed to be + part of multiple groups, but only if all the groups involved specify the + same ``feature``. Such groups will not be merged on the linker command line, + the individual groups will still be preserved. Mixing different group + features for the same target or library is forbidden. - .. versionadded:: 3.15 + .. code-block:: cmake - Includes or removes items from ``list`` that match the regular expression ``regex``. + add_library(lib1 ...) + add_library(lib2 ...) + add_library(lib3 ...) + add_library(lib4 ...) + add_library(lib5 ...) -.. genex:: $<LOWER_CASE:string> + target_link_libraries(lib3 PUBLIC "$<LINK_GROUP:feature1,lib1,lib2>") + target_link_libraries(lib4 PRIVATE "$<LINK_GROUP:feature1,lib1,lib3>") + # lib4 will be linked with the groups {lib1,lib2} and {lib1,lib3}. + # Both groups specify the same feature, so this is fine. - Content of ``string`` converted to lower case. + target_link_libraries(lib5 PRIVATE "$<LINK_GROUP:feature2,lib1,lib3>") + # An error will be raised here because both lib1 and lib3 are part of two + # groups with different features. -.. genex:: $<UPPER_CASE:string> + When a target or an external library is involved in the link step as part of + a group and also as not part of any group, any occurrence of the non-group + link item will be replaced by the groups it belongs to. - Content of ``string`` converted to upper case. + .. code-block:: cmake -.. genex:: $<GENEX_EVAL:expr> + add_library(lib1 ...) + add_library(lib2 ...) + add_library(lib3 ...) + add_library(lib4 ...) - .. versionadded:: 3.12 + target_link_libraries(lib3 PUBLIC lib1) - Content of ``expr`` evaluated as a generator expression in the current - context. This enables consumption of generator expressions whose - evaluation results itself in generator expressions. + target_link_libraries(lib4 PRIVATE lib3 "$<LINK_GROUP:feature1,lib1,lib2>") + # lib4 will only be linked with lib3 and the group {lib1,lib2} -.. genex:: $<TARGET_GENEX_EVAL:tgt,expr> + Because ``lib1`` is part of the group defined for ``lib4``, that group then + gets applied back to the use of ``lib1`` for ``lib3``. The end result will + be as though the linking relationship for ``lib3`` had been specified as: - .. versionadded:: 3.12 + .. code-block:: cmake - Content of ``expr`` evaluated as a generator expression in the context of - ``tgt`` target. This enables consumption of custom target properties that - themselves contain generator expressions. + target_link_libraries(lib3 PUBLIC "$<LINK_GROUP:feature1,lib1,lib2>") - Having the capability to evaluate generator expressions is very useful when - you want to manage custom properties supporting generator expressions. - For example: + Be aware that the precedence of the group over the non-group link item can + result in circular dependencies between groups. If this occurs, a fatal + error is raised because circular dependencies are not allowed for groups. .. code-block:: cmake - add_library(foo ...) + add_library(lib1A ...) + add_library(lib1B ...) + add_library(lib2A ...) + add_library(lib2B ...) + add_library(lib3 ...) - set_property(TARGET foo PROPERTY - CUSTOM_KEYS $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS> - ) + # Non-group linking relationships, these are non-circular so far + target_link_libraries(lib1A PUBLIC lib2A) + target_link_libraries(lib2B PUBLIC lib1B) - add_custom_target(printFooKeys - COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_PROPERTY:foo,CUSTOM_KEYS> + # The addition of these groups creates circular dependencies + target_link_libraries(lib3 PRIVATE + "$<LINK_GROUP:feat,lib1A,lib1B>" + "$<LINK_GROUP:feat,lib2A,lib2B>" ) - This naive implementation of the ``printFooKeys`` custom command is wrong - because ``CUSTOM_KEYS`` target property is not evaluated and the content - is passed as is (i.e. ``$<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>``). - - To have the expected result (i.e. ``FOO_EXTRA_THINGS`` if config is - ``Debug``), it is required to evaluate the output of - ``$<TARGET_PROPERTY:foo,CUSTOM_KEYS>``: + Because of the groups defined for ``lib3``, the linking relationships for + ``lib1A`` and ``lib2B`` effectively get expanded to the equivalent of: .. code-block:: cmake - add_custom_target(printFooKeys - COMMAND ${CMAKE_COMMAND} -E - echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>> - ) - -Variable Queries ----------------- - -.. genex:: $<CONFIG> + target_link_libraries(lib1A PUBLIC "$<LINK_GROUP:feat,lib2A,lib2B>") + target_link_libraries(lib2B PUBLIC "$<LINK_GROUP:feat,lib1A,lib1B>") - Configuration name. + This creates a circular dependency between groups: + ``lib1A --> lib2B --> lib1A``. -.. genex:: $<CONFIGURATION> + The following limitations should also be noted: - Configuration name. Deprecated since CMake 3.0. Use ``CONFIG`` instead. + * The ``library-list`` can specify CMake targets or libraries. + Any CMake target of type :ref:`OBJECT <Object Libraries>` + or :ref:`INTERFACE <Interface Libraries>` will ignore the feature aspect + of the expression and instead be linked in the standard way. -.. genex:: $<PLATFORM_ID> + * The ``$<LINK_GROUP:...>`` generator expression can only be used to + specify link libraries. In practice, this means it can appear in the + :prop_tgt:`LINK_LIBRARIES`, :prop_tgt:`INTERFACE_LINK_LIBRARIES`,and + :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` target properties, and be + specified in :command:`target_link_libraries` and :command:`link_libraries` + commands. - The current system's CMake platform id. - See also the :variable:`CMAKE_SYSTEM_NAME` variable. + * If a ``$<LINK_GROUP:...>`` generator expression appears in the + :prop_tgt:`INTERFACE_LINK_LIBRARIES` property of a target, it will be + included in the imported target generated by a :command:`install(EXPORT)` + command. It is the responsibility of the environment consuming this + import to define the link feature used by this expression. -.. genex:: $<C_COMPILER_ID> - - The CMake's compiler id of the C compiler used. - See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +Link Context +^^^^^^^^^^^^ -.. genex:: $<CXX_COMPILER_ID> - - The CMake's compiler id of the CXX compiler used. - See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. - -.. genex:: $<CUDA_COMPILER_ID> - - The CMake's compiler id of the CUDA compiler used. - See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. - -.. genex:: $<OBJC_COMPILER_ID> - - .. versionadded:: 3.16 - - The CMake's compiler id of the OBJC compiler used. - See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. - -.. genex:: $<OBJCXX_COMPILER_ID> - - .. versionadded:: 3.16 - - The CMake's compiler id of the OBJCXX compiler used. - See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. - -.. genex:: $<Fortran_COMPILER_ID> - - The CMake's compiler id of the Fortran compiler used. - See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. - -.. genex:: $<HIP_COMPILER_ID> - - .. versionadded:: 3.21 - - The CMake's compiler id of the HIP compiler used. - See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. - -.. genex:: $<ISPC_COMPILER_ID> - - .. versionadded:: 3.19 - - The CMake's compiler id of the ISPC compiler used. - See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. - -.. genex:: $<C_COMPILER_VERSION> - - The version of the C compiler used. - See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. - -.. genex:: $<CXX_COMPILER_VERSION> +.. genex:: $<LINK_ONLY:...> - The version of the CXX compiler used. - See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. + .. versionadded:: 3.1 -.. genex:: $<CUDA_COMPILER_VERSION> + 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. - The version of the CUDA compiler used. - See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. + .. versionadded:: 3.24 + ``LINK_ONLY`` may also be used in a :prop_tgt:`LINK_LIBRARIES` target + property. See policy :policy:`CMP0131`. -.. genex:: $<OBJC_COMPILER_VERSION> +.. genex:: $<DEVICE_LINK:list> - .. versionadded:: 3.16 + .. versionadded:: 3.18 - The version of the OBJC compiler used. - See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. + Returns the list if it is the device link step, an empty list otherwise. + The device link step is controlled by :prop_tgt:`CUDA_SEPARABLE_COMPILATION` + and :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties and + policy :policy:`CMP0105`. This expression can only be used to specify link + options. -.. genex:: $<OBJCXX_COMPILER_VERSION> +.. genex:: $<HOST_LINK:list> - .. versionadded:: 3.16 + .. versionadded:: 3.18 - The version of the OBJCXX compiler used. - See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. + Returns the list if it is the normal link step, an empty list otherwise. + This expression is mainly useful when a device link step is also involved + (see :genex:`$<DEVICE_LINK:list>` generator expression). This expression can + only be used to specify link options. -.. genex:: $<Fortran_COMPILER_VERSION> - The version of the Fortran compiler used. - See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +.. _`Target-Dependent Queries`: -.. genex:: $<HIP_COMPILER_VERSION> +Target-Dependent Expressions +---------------------------- - .. versionadded:: 3.21 +These queries refer to a target ``tgt``. Unless otherwise stated, this can +be any runtime artifact, namely: - The version of the HIP compiler used. - See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +* An executable target created by :command:`add_executable`. +* A shared library target (``.so``, ``.dll`` but not their ``.lib`` import + library) created by :command:`add_library`. +* A static library target created by :command:`add_library`. -.. genex:: $<ISPC_COMPILER_VERSION> +In the following, the phrase "the ``tgt`` filename" means the name of the +``tgt`` binary file. This has to be distinguished from the phrase +"the target name", which is just the string ``tgt``. - .. versionadded:: 3.19 +.. genex:: $<TARGET_EXISTS:tgt> - The version of the ISPC compiler used. - See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. + .. versionadded:: 3.12 -.. genex:: $<COMPILE_LANGUAGE> + ``1`` if ``tgt`` exists as a CMake target, else ``0``. - .. versionadded:: 3.3 +.. genex:: $<TARGET_NAME_IF_EXISTS:tgt> - The compile language of source files when evaluating compile options. - See :ref:`the related boolean expression - <Boolean COMPILE_LANGUAGE Generator Expression>` - ``$<COMPILE_LANGUAGE:language>`` - for notes about the portability of this generator expression. + .. versionadded:: 3.12 -.. genex:: $<LINK_LANGUAGE> + The target name ``tgt`` if the target exists, an empty string otherwise. - .. versionadded:: 3.18 + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. - The link language of target when evaluating link options. - See :ref:`the related boolean expression - <Boolean LINK_LANGUAGE Generator Expression>` ``$<LINK_LANGUAGE:language>`` - for notes about the portability of this generator expression. +.. genex:: $<TARGET_NAME:...> - .. note:: + Marks ``...`` as being the name of a target. This is required if exporting + targets to multiple dependent export sets. The ``...`` must be a literal + name of a target, it may not contain generator expressions. - This generator expression is not supported by the link libraries - properties to avoid side-effects due to the double evaluation of - these properties. +.. genex:: $<TARGET_PROPERTY:tgt,prop> -.. _`Target-Dependent Queries`: + Value of the property ``prop`` on the target ``tgt``. -Target-Dependent Queries ------------------------- + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. -These queries refer to a target ``tgt``. This can be any runtime artifact, -namely: +.. genex:: $<TARGET_PROPERTY:prop> -* an executable target created by :command:`add_executable` -* a shared library target (``.so``, ``.dll`` but not their ``.lib`` import library) - created by :command:`add_library` -* a static library target created by :command:`add_library` + Value of the property ``prop`` on the target for which the expression + is being evaluated. Note that for generator expressions in + :ref:`Target Usage Requirements` this is the consuming target rather + than the target specifying the requirement. -In the following, "the ``tgt`` filename" means the name of the ``tgt`` -binary file. This has to be distinguished from "the target name", -which is just the string ``tgt``. +.. genex:: $<TARGET_OBJECTS:tgt> -.. genex:: $<TARGET_NAME_IF_EXISTS:tgt> + .. versionadded:: 3.1 - .. versionadded:: 3.12 + List of objects resulting from building ``tgt``. This would typically be + used on :ref:`object library <Object Libraries>` targets. - The target name ``tgt`` if the target exists, an empty string otherwise. +.. genex:: $<TARGET_POLICY:policy> - Note that ``tgt`` is not added as a dependency of the target this - expression is evaluated on. + ``1`` if the ``policy`` was ``NEW`` when the 'head' target was created, + else ``0``. If the ``policy`` was not set, the warning message for the policy + will be emitted. This generator expression only works for a subset of + policies. .. genex:: $<TARGET_FILE:tgt> Full path to the ``tgt`` binary file. + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on, unless the expression is being used in + :command:`add_custom_command` or :command:`add_custom_target`. + .. genex:: $<TARGET_FILE_BASE_NAME:tgt> .. versionadded:: 3.15 @@ -1027,38 +1616,36 @@ 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_CONTENT_DIR:tgt> +.. genex:: $<TARGET_BUNDLE_DIR_NAME:tgt> - .. versionadded:: 3.9 + .. versionadded:: 3.24 - 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. + 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`). -.. genex:: $<TARGET_PROPERTY:tgt,prop> - - Value of the property ``prop`` on the target ``tgt``. +.. genex:: $<TARGET_BUNDLE_CONTENT_DIR:tgt> - Note that ``tgt`` is not added as a dependency of the target this - expression is evaluated on. + .. versionadded:: 3.9 -.. genex:: $<TARGET_PROPERTY:prop> + Full path to the bundle content directory where ``tgt`` is the name of a + 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. - Value of the property ``prop`` on the target for which the expression - is being evaluated. Note that for generator expressions in - :ref:`Target Usage Requirements` this is the consuming target rather - than the target specifying the requirement. + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). .. genex:: $<TARGET_RUNTIME_DLLS:tgt> @@ -1067,8 +1654,8 @@ which is just the string ``tgt``. List of DLLs that the target depends on at runtime. This is determined by 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. + executables, ``SHARED`` libraries, and ``MODULE`` libraries is an error. + **On non-DLL platforms, this expression always 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 @@ -1083,7 +1670,7 @@ which is just the string ``tgt``. add_custom_command(TARGET exe POST_BUILD COMMAND ${CMAKE_COMMAND} -E copy $<TARGET_RUNTIME_DLLS:exe> $<TARGET_FILE_DIR:exe> COMMAND_EXPAND_LISTS - ) + ) .. note:: @@ -1094,37 +1681,14 @@ which is just the string ``tgt``. section for details. Many :ref:`Find Modules` produce imported targets with the ``UNKNOWN`` type and therefore will be ignored. -.. genex:: $<INSTALL_PREFIX> - - Content of the install prefix when the target is exported via - :command:`install(EXPORT)`, or when evaluated in the - :prop_tgt:`INSTALL_NAME_DIR` property or the ``INSTALL_NAME_DIR`` argument of - :command:`install(RUNTIME_DEPENDENCY_SET)`, and empty otherwise. - -Output-Related Expressions --------------------------- - -.. genex:: $<TARGET_NAME:...> - - Marks ``...`` as being the name of a target. This is required if exporting - targets to multiple dependent export sets. The ``...`` must be a literal - name of a target- it may not contain generator expressions. - -.. genex:: $<LINK_ONLY:...> - - .. 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. +Export And Install Expressions +------------------------------ .. genex:: $<INSTALL_INTERFACE:...> - Content of ``...`` when the property is exported using :command:`install(EXPORT)`, - and empty otherwise. + Content of ``...`` when the property is exported using + :command:`install(EXPORT)`, and empty otherwise. .. genex:: $<BUILD_INTERFACE:...> @@ -1132,70 +1696,85 @@ Output-Related Expressions when the target is used by another target in the same buildsystem. Expands to the empty string otherwise. -.. genex:: $<MAKE_C_IDENTIFIER:...> +.. genex:: $<INSTALL_PREFIX> - Content of ``...`` converted to a C identifier. The conversion follows the - same behavior as :command:`string(MAKE_C_IDENTIFIER)`. + Content of the install prefix when the target is exported via + :command:`install(EXPORT)`, or when evaluated in the + :prop_tgt:`INSTALL_NAME_DIR` property or the ``INSTALL_NAME_DIR`` argument of + :command:`install(RUNTIME_DEPENDENCY_SET)`, and empty otherwise. -.. genex:: $<TARGET_OBJECTS:objLib> +Multi-level Expression Evaluation +--------------------------------- - .. versionadded:: 3.1 +.. genex:: $<GENEX_EVAL:expr> - List of objects resulting from build of ``objLib``. + .. versionadded:: 3.12 -.. genex:: $<SHELL_PATH:...> + Content of ``expr`` evaluated as a generator expression in the current + context. This enables consumption of generator expressions whose + evaluation results itself in generator expressions. - .. versionadded:: 3.4 +.. genex:: $<TARGET_GENEX_EVAL:tgt,expr> - Content of ``...`` converted to shell path style. For example, slashes are - converted to backslashes in Windows shells and drive letters are converted - to posix paths in MSYS shells. The ``...`` must be an absolute path. + .. versionadded:: 3.12 - .. versionadded:: 3.14 - The ``...`` may be a :ref:`semicolon-separated list <CMake Language Lists>` - of paths, in which case each path is converted individually and a result - list is generated using the shell path separator (``:`` on POSIX and - ``;`` on Windows). Be sure to enclose the argument containing this genex - in double quotes in CMake source code so that ``;`` does not split arguments. + Content of ``expr`` evaluated as a generator expression in the context of + ``tgt`` target. This enables consumption of custom target properties that + themselves contain generator expressions. -.. genex:: $<OUTPUT_CONFIG:...> + Having the capability to evaluate generator expressions is very useful when + you want to manage custom properties supporting generator expressions. + For example: - .. versionadded:: 3.20 + .. code-block:: cmake - Only valid in :command:`add_custom_command` and :command:`add_custom_target` - as the outer-most generator expression in an argument. - With the :generator:`Ninja Multi-Config` generator, generator expressions - in ``...`` are evaluated using the custom command's "output config". - With other generators, the content of ``...`` is evaluated normally. + add_library(foo ...) -.. genex:: $<COMMAND_CONFIG:...> + set_property(TARGET foo PROPERTY + CUSTOM_KEYS $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS> + ) - .. versionadded:: 3.20 + add_custom_target(printFooKeys + COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_PROPERTY:foo,CUSTOM_KEYS> + ) - Only valid in :command:`add_custom_command` and :command:`add_custom_target` - as the outer-most generator expression in an argument. - With the :generator:`Ninja Multi-Config` generator, generator expressions - in ``...`` are evaluated using the custom command's "command config". - With other generators, the content of ``...`` is evaluated normally. + This naive implementation of the ``printFooKeys`` custom command is wrong + because ``CUSTOM_KEYS`` target property is not evaluated and the content + is passed as is (i.e. ``$<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>``). -Debugging -========= + To have the expected result (i.e. ``FOO_EXTRA_THINGS`` if config is + ``Debug``), it is required to evaluate the output of + ``$<TARGET_PROPERTY:foo,CUSTOM_KEYS>``: -Since generator expressions are evaluated during generation of the buildsystem, -and not during processing of ``CMakeLists.txt`` files, it is not possible to -inspect their result with the :command:`message()` command. + .. code-block:: cmake -One possible way to generate debug messages is to add a custom target, + add_custom_target(printFooKeys + COMMAND ${CMAKE_COMMAND} -E + echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>> + ) -.. code-block:: cmake +Escaped Characters +------------------ - add_custom_target(genexdebug COMMAND ${CMAKE_COMMAND} -E echo "$<...>") +These expressions evaluate to specific string literals. Use them in place of +the actual string literal where you need to prevent them from having their +special meaning. -The shell command ``make genexdebug`` (invoked after execution of ``cmake``) -would then print the result of ``$<...>``. +.. genex:: $<ANGLE-R> -Another way is to write debug messages to a file: + A literal ``>``. Used for example to compare strings that contain a ``>``. -.. code-block:: cmake +.. genex:: $<COMMA> - file(GENERATE OUTPUT filename CONTENT "$<...>") + A literal ``,``. Used for example to compare strings which contain a ``,``. + +.. genex:: $<SEMICOLON> + + A literal ``;``. Used to prevent list expansion on an argument with ``;``. + +Deprecated Expressions +---------------------- + +.. genex:: $<CONFIGURATION> + + Configuration name. Deprecated since CMake 3.0. Use :genex:`CONFIG` instead. diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index e7d2694..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. 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-policies.7.rst b/Help/manual/cmake-policies.7.rst index 0939a82..43eb200 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -52,6 +52,23 @@ to determine whether to report an error on use of deprecated macros or functions. +Policies Introduced by CMake 3.24 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0139: The if() command supports path comparisons using PATH_EQUAL operator. </policy/CMP0139> + CMP0138: CheckIPOSupported uses flags from calling project. </policy/CMP0138> + 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 ================================= diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst index 03bb5aa..a96c704 100644 --- a/Help/manual/cmake-presets.7.rst +++ b/Help/manual/cmake-presets.7.rst @@ -42,7 +42,22 @@ The root object recognizes the following fields: ``version`` A required integer representing the version of the JSON schema. - The supported versions are ``1``, ``2``, ``3``, and ``4``. + The supported versions are: + + ``1`` + .. versionadded:: 3.19 + + ``2`` + .. versionadded:: 3.20 + + ``3`` + .. versionadded:: 3.21 + + ``4`` + .. versionadded:: 3.23 + + ``5`` + .. versionadded:: 3.24 ``cmakeMinimumRequired`` @@ -715,6 +730,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 @@ -1062,6 +1083,17 @@ Recognized macros include: 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 ddb917a..d88322c 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 @@ -262,10 +263,13 @@ Properties on Targets /prop_tgt/INTERFACE_COMPILE_FEATURES /prop_tgt/INTERFACE_COMPILE_OPTIONS /prop_tgt/INTERFACE_HEADER_SETS + /prop_tgt/INTERFACE_HEADER_SETS_TO_VERIFY /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 @@ -306,6 +310,8 @@ Properties on Targets /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 @@ -376,6 +382,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 @@ -389,6 +396,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 @@ -400,6 +408,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 @@ -416,6 +425,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 @@ -451,6 +461,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 4df0237..7c8a7fa 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -59,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 @@ -172,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 @@ -197,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 @@ -204,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 @@ -239,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 @@ -283,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 @@ -344,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 @@ -395,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 @@ -437,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 @@ -447,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 @@ -487,17 +503,20 @@ 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 /variable/CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD /variable/CMAKE_VS_JUST_MY_CODE_DEBUGGING + /variable/CMAKE_VS_NO_COMPILE_BATCHING /variable/CMAKE_VS_SDK_EXCLUDE_DIRECTORIES /variable/CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES /variable/CMAKE_VS_SDK_INCLUDE_DIRECTORIES @@ -506,6 +525,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 @@ -633,6 +653,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 diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 18bdc5f..38105dd 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -197,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. @@ -326,7 +333,8 @@ Options "cmd": "add_executable", "args": ["foo", "bar"], "time": 1579512535.9687231, - "frame": 2 + "frame": 2, + "global_frame": 4 } The members are: @@ -336,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 @@ -353,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 @@ -365,7 +385,7 @@ Options { "version": { "major": 1, - "minor": 1 + "minor": 2 } } @@ -406,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. @@ -599,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 ======================= @@ -673,11 +700,17 @@ 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. @@ -746,11 +779,16 @@ 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. @@ -843,16 +881,16 @@ Available commands are: 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>...`` +``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. @@ -924,6 +962,12 @@ Available commands are: 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 @@ -1022,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 1e7b077..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. diff --git a/Help/manual/presets/example.json b/Help/manual/presets/example.json index 873c4ad..be5c791 100644 --- a/Help/manual/presets/example.json +++ b/Help/manual/presets/example.json @@ -1,5 +1,5 @@ { - "version": 4, + "version": 5, "cmakeMinimumRequired": { "major": 3, "minor": 23, diff --git a/Help/manual/presets/schema.json b/Help/manual/presets/schema.json index 12f8b5e..c96405c 100644 --- a/Help/manual/presets/schema.json +++ b/Help/manual/presets/schema.json @@ -57,6 +57,21 @@ "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": [ @@ -673,6 +688,28 @@ "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 3 and higher.", @@ -821,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", @@ -998,6 +1034,39 @@ ] } }, + "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 3 and higher.", 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/CMP0097.rst b/Help/policy/CMP0097.rst index 2240874..24957d0 100644 --- a/Help/policy/CMP0097.rst +++ b/Help/policy/CMP0097.rst @@ -4,9 +4,11 @@ CMP0097 .. versionadded:: 3.16 :command:`ExternalProject_Add` with ``GIT_SUBMODULES ""`` initializes no -submodules. +submodules. The policy also applies to :command:`FetchContent_Declare`, +which uses the same download and update features as +:command:`ExternalProject_Add`. -The module provides a ``GIT_SUBMODULES`` option which controls what submodules +The commands provide a ``GIT_SUBMODULES`` option which controls what submodules to initialize and update. Starting with CMake 3.16, explicitly setting ``GIT_SUBMODULES`` to an empty string means no submodules will be initialized or updated. diff --git a/Help/policy/CMP0112.rst b/Help/policy/CMP0112.rst index 5b00d07..25c3896 100644 --- a/Help/policy/CMP0112.rst +++ b/Help/policy/CMP0112.rst @@ -18,6 +18,7 @@ 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`` 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..d5430e4 --- /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 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/policy/CMP0138.rst b/Help/policy/CMP0138.rst new file mode 100644 index 0000000..a86849d --- /dev/null +++ b/Help/policy/CMP0138.rst @@ -0,0 +1,31 @@ +CMP0138 +------- + +.. versionadded:: 3.24 + +:module:`CheckIPOSupported` uses flags from calling project. + +The :module:`CheckIPOSupported` module :command:`check_ipo_supported` +command compiles a test project to determine whether the toolchain +supports :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION`. CMake 3.23 and +below run the check with the default values of the +:variable:`CMAKE_<LANG>_FLAGS` and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` +variables for the current environment and toolchain settings. +However, some projects may modify these flag variables to add +flags that affect availability of the toolchain's IPO features. +CMake 3.24 and above prefer to honor the calling project's values +for these variables. This policy provides compatibility for projects +that have not been updated to expect this behavior. + +The ``OLD`` behavior for this policy is to ignore the calling +project's values of :variable:`CMAKE_<LANG>_FLAGS` and +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`. The ``NEW`` behavior +for this policy is to use the values of those variables as +compiler flags in the test project. + +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/CMP0139.rst b/Help/policy/CMP0139.rst new file mode 100644 index 0000000..5a0f4f7 --- /dev/null +++ b/Help/policy/CMP0139.rst @@ -0,0 +1,17 @@ +CMP0139 +------- + +.. versionadded:: 3.24 + +The :command:`if` command supports path comparisons using ``PATH_EQUAL`` +operator. + +The ``OLD`` behavior for this policy is to ignore the ``PATH_EQUAL`` operator. +The ``NEW`` behavior is to interpret the ``PATH_EQUAL`` operator. + +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/prop_dir/RULE_LAUNCH_COMPILE.rst b/Help/prop_dir/RULE_LAUNCH_COMPILE.rst index 342d0ae..d9b550e 100644 --- a/Help/prop_dir/RULE_LAUNCH_COMPILE.rst +++ b/Help/prop_dir/RULE_LAUNCH_COMPILE.rst @@ -3,5 +3,11 @@ RULE_LAUNCH_COMPILE Specify a launcher for compile rules. -See the global property of the same name for details. This overrides -the global property for a directory. +.. note:: + This property is intended for internal use by :manual:`ctest(1)`. Projects + and developers should use the :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target + properties or the associated :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` + variables instead. + +See the :prop_gbl:`global property <RULE_LAUNCH_COMPILE>` of the same name +for details. This overrides the global property for a directory. diff --git a/Help/prop_dir/RULE_LAUNCH_LINK.rst b/Help/prop_dir/RULE_LAUNCH_LINK.rst index 3cfb236..922c8d5 100644 --- a/Help/prop_dir/RULE_LAUNCH_LINK.rst +++ b/Help/prop_dir/RULE_LAUNCH_LINK.rst @@ -3,5 +3,11 @@ RULE_LAUNCH_LINK Specify a launcher for link rules. -See the global property of the same name for details. This overrides -the global property for a directory. +.. note:: + This property is intended for internal use by :manual:`ctest(1)`. Projects + and developers should use the :prop_tgt:`<LANG>_LINKER_LAUNCHER` target + properties or the associated :variable:`CMAKE_<LANG>_LINKER_LAUNCHER` + variables instead. + +See the :prop_gbl:`global property <RULE_LAUNCH_LINK>` of the same name for +details. This overrides the global property for a directory. diff --git a/Help/prop_gbl/RULE_LAUNCH_COMPILE.rst b/Help/prop_gbl/RULE_LAUNCH_COMPILE.rst index e0df878..a43e9e5 100644 --- a/Help/prop_gbl/RULE_LAUNCH_COMPILE.rst +++ b/Help/prop_gbl/RULE_LAUNCH_COMPILE.rst @@ -3,6 +3,12 @@ RULE_LAUNCH_COMPILE Specify a launcher for compile rules. +.. note:: + This property is intended for internal use by :manual:`ctest(1)`. Projects + and developers should use the :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target + properties or the associated :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` + variables instead. + :ref:`Makefile Generators` and the :generator:`Ninja` generator prefix compiler commands with the given launcher command line. This is intended to allow launchers to intercept build problems diff --git a/Help/prop_gbl/RULE_LAUNCH_LINK.rst b/Help/prop_gbl/RULE_LAUNCH_LINK.rst index 567bb68..da376fe 100644 --- a/Help/prop_gbl/RULE_LAUNCH_LINK.rst +++ b/Help/prop_gbl/RULE_LAUNCH_LINK.rst @@ -3,6 +3,12 @@ RULE_LAUNCH_LINK Specify a launcher for link rules. +.. note:: + This property is intended for internal use by :manual:`ctest(1)`. Projects + and developers should use the :prop_tgt:`<LANG>_LINKER_LAUNCHER` target + properties or the associated :variable:`CMAKE_<LANG>_LINKER_LAUNCHER` + variables instead. + :ref:`Makefile Generators` and the :generator:`Ninja` generator prefix link and archive commands with the given launcher command line. This is intended to allow launchers to intercept build problems diff --git a/Help/prop_sf/VS_CSHARP_tagname.rst b/Help/prop_sf/VS_CSHARP_tagname.rst index 75720f8..77b1e16 100644 --- a/Help/prop_sf/VS_CSHARP_tagname.rst +++ b/Help/prop_sf/VS_CSHARP_tagname.rst @@ -16,7 +16,7 @@ Example usage: .. code-block:: cmake - set_source_files_property(<filename> + set_source_files_properties(<filename> PROPERTIES VS_CSHARP_DependentUpon <other file> VS_CSHARP_SubType "Form") diff --git a/Help/prop_test/ENVIRONMENT_MODIFICATION.rst b/Help/prop_test/ENVIRONMENT_MODIFICATION.rst index a80651a..ad3e190 100644 --- a/Help/prop_test/ENVIRONMENT_MODIFICATION.rst +++ b/Help/prop_test/ENVIRONMENT_MODIFICATION.rst @@ -19,17 +19,19 @@ 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/CUDA_ARCHITECTURES.rst b/Help/prop_tgt/CUDA_ARCHITECTURES.rst index 191f78f..05c2599 100644 --- a/Help/prop_tgt/CUDA_ARCHITECTURES.rst +++ b/Help/prop_tgt/CUDA_ARCHITECTURES.rst @@ -34,6 +34,11 @@ The ``CUDA_ARCHITECTURES`` may be set to one of the following special values: 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/INTERFACE_HEADER_SETS_TO_VERIFY.rst b/Help/prop_tgt/INTERFACE_HEADER_SETS_TO_VERIFY.rst new file mode 100644 index 0000000..b0d63f3 --- /dev/null +++ b/Help/prop_tgt/INTERFACE_HEADER_SETS_TO_VERIFY.rst @@ -0,0 +1,13 @@ +INTERFACE_HEADER_SETS_TO_VERIFY +------------------------------- + +.. versionadded:: 3.24 + +Used to specify which ``PUBLIC`` and ``INTERFACE`` header sets of a target +should be verified. + +This property contains a semicolon-separated list of header sets which +should be verified if :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` is set to +``TRUE``. If the list is empty, all ``PUBLIC`` and ``INTERFACE`` header sets +are verified. (If the project does not want to verify any header sets on the +target, simply set :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` to ``FALSE``.) diff --git a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst index af3d9c2..53f5838 100644 --- a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst +++ b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst @@ -26,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..6243bb1 --- /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_LINK_LIBRARIES_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_LINK_LIBRARIES_DIRECT`` or +``INTERFACE_LINK_LIBRARIES_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_LINK_LIBRARIES_DIRECT``, + ``INTERFACE_LINK_LIBRARIES_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_LINK_LIBRARIES_DIRECT``, + ``INTERFACE_LINK_LIBRARIES_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_LINK_LIBRARIES_DIRECT`` + and ``INTERFACE_LINK_LIBRARIES_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_LINK_LIBRARIES_DIRECT`` or + ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE``. + +One may limit the effects of ``INTERFACE_LINK_LIBRARIES_DIRECT`` and +``INTERFACE_LINK_LIBRARIES_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 requirements). +* ``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 requirements). +* ``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/LINK_LIBRARIES.rst b/Help/prop_tgt/LINK_LIBRARIES.rst index 29baf8c..b5c1d89 100644 --- a/Help/prop_tgt/LINK_LIBRARIES.rst +++ b/Help/prop_tgt/LINK_LIBRARIES.rst @@ -14,9 +14,17 @@ 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 -for available expressions. See the :manual:`cmake-buildsystem(7)` manual -for more on defining buildsystem properties. +Contents of ``LINK_LIBRARIES`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>` with the +syntax ``$<...>``. Policy :policy:`CMP0131` affects the behavior of the +:genex:`LINK_ONLY` generator expression for this property. + +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 index a9af74d..0749c6f 100644 --- a/Help/prop_tgt/LINK_LIBRARIES_ONLY_TARGETS.rst +++ b/Help/prop_tgt/LINK_LIBRARIES_ONLY_TARGETS.rst @@ -8,6 +8,8 @@ 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`. +Checks are also applied to libraries added to a target through the +:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` properties of its dependencies. CMake will verify that link items that might be target names actually name existing targets. An item is considered a possible target name if: diff --git a/Help/prop_tgt/LINK_LIBRARY_OVERRIDE.rst b/Help/prop_tgt/LINK_LIBRARY_OVERRIDE.rst new file mode 100644 index 0000000..916a7c6 --- /dev/null +++ b/Help/prop_tgt/LINK_LIBRARY_OVERRIDE.rst @@ -0,0 +1,65 @@ +LINK_LIBRARY_OVERRIDE +--------------------- + +.. versionadded:: 3.24 + +Override the library features associated with libraries from +:genex:`LINK_LIBRARY` generator expressions. This can be used to resolve +incompatible library features that result from specifying different features +for the same library in different :genex:`LINK_LIBRARY` generator expressions. + +This property supports overriding multiple libraries and features. It expects +a :ref:`semicolon-separated list <CMake Language Lists>`, where each list item +has the following form:: + + feature[,link-item]* + +For each comma-separated ``link-item``, any existing library feature associated +with it will be ignored for the target this property is set on. The item +will instead be associated with the specified ``feature``. Each ``link-item`` +can be anything that would be accepted as part of a ``library-list`` in a +:genex:`LINK_LIBRARY` generator expression. + +.. code-block:: cmake + + add_library(lib1 ...) + add_library(lib2 ...) + add_library(lib3 ...) + + target_link_libraries(lib1 PUBLIC "$<LINK_LIBRARY:feature1,external>") + target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature2,lib1>") + target_link_libraries(lib3 PRIVATE lib1 lib2) + + # lib1 is associated with both feature2 and no feature. Without any override, + # this would result in a fatal error at generation time for lib3. + # Define an override to resolve the incompatible feature associations. + set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE "feature2,lib1,external") + + # lib1 and external will now be associated with feature2 instead when linking lib3 + +It is also possible to override any feature with the pre-defined ``DEFAULT`` +library feature. This effectively discards any feature for that link item, +for that target only (``lib3`` in this example): + +.. code-block:: cmake + + # When linking lib3, discard any library feature for lib1, and use feature2 for external + set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE + "DEFAULT,lib1" + "feature2,external" + ) + +The above example also demonstrates how to specify different feature overrides +for different link items. See the :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` +target property for an alternative way of overriding library features for +individual libraries, which may be simpler in some cases. If both properties +are defined and specify an override for the same link item, +:prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` takes precedence over +``LINK_LIBRARY_OVERRIDE``. + +Contents of ``LINK_LIBRARY_OVERRIDE`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +For more information about library features, see the +: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..4d3dd4f --- /dev/null +++ b/Help/prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY.rst @@ -0,0 +1,51 @@ +LINK_LIBRARY_OVERRIDE_<LIBRARY> +------------------------------- + +.. versionadded:: 3.24 + +Override the library feature associated with ``<LIBRARY>`` from +:genex:`LINK_LIBRARY` generator expressions. This can be used to resolve +incompatible library features that result from specifying different features +for ``<LIBRARY>`` in different :genex:`LINK_LIBRARY` generator expressions. + +When set on a target, this property holds a single library feature name, which +will be applied to ``<LIBRARY>`` when linking that target. + +.. code-block:: cmake + + add_library(lib1 ...) + add_library(lib2 ...) + add_library(lib3 ...) + + target_link_libraries(lib1 PUBLIC "$<LINK_LIBRARY:feature1,external>") + target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature2,lib1>") + target_link_libraries(lib3 PRIVATE lib1 lib2) + + # lib1 is associated with both feature2 and no feature. Without any override, + # this would result in a fatal error at generation time for lib3. + # Define an override to resolve the incompatible feature associations. + set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE_lib1 feature2) + + # lib1 will now be associated with feature2 instead when linking lib3 + +It is also possible to override any feature with the pre-defined ``DEFAULT`` +library feature. This effectively discards any feature for that link item, +for that target only (``lib3`` in this example): + +.. code-block:: cmake + + # When linking lib3, discard any library feature for lib1 + set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE_lib1 DEFAULT) + +See the :prop_tgt:`LINK_LIBRARY_OVERRIDE` target property for an alternative +way of overriding library features for multiple libraries at once. If both +properties are defined and specify an override for the same link item, +``LINK_LIBRARY_OVERRIDE_<LIBRARY>`` takes precedence over +:prop_tgt:`LINK_LIBRARY_OVERRIDE`. + +Contents of ``LINK_LIBRARY_OVERRIDE_<LIBRARY>`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +For more information about library features, see the +:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` and +:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables. diff --git a/Help/prop_tgt/RULE_LAUNCH_COMPILE.rst b/Help/prop_tgt/RULE_LAUNCH_COMPILE.rst index e92ab86..3f4305f 100644 --- a/Help/prop_tgt/RULE_LAUNCH_COMPILE.rst +++ b/Help/prop_tgt/RULE_LAUNCH_COMPILE.rst @@ -3,5 +3,11 @@ RULE_LAUNCH_COMPILE Specify a launcher for compile rules. -See the global property of the same name for details. This overrides -the global and directory property for a target. +.. note:: + This property is intended for internal use by :manual:`ctest(1)`. Projects + and developers should use the :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target + properties or the associated :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` + variables instead. + +See the :prop_gbl:`global property <RULE_LAUNCH_COMPILE>` of the same name +for details. This overrides the global and directory property for a target. diff --git a/Help/prop_tgt/RULE_LAUNCH_LINK.rst b/Help/prop_tgt/RULE_LAUNCH_LINK.rst index f330033..da93be2 100644 --- a/Help/prop_tgt/RULE_LAUNCH_LINK.rst +++ b/Help/prop_tgt/RULE_LAUNCH_LINK.rst @@ -3,5 +3,11 @@ RULE_LAUNCH_LINK Specify a launcher for link rules. -See the global property of the same name for details. This overrides -the global and directory property for a target. +.. note:: + This property is intended for internal use by :manual:`ctest(1)`. Projects + and developers should use the :prop_tgt:`<LANG>_LINKER_LAUNCHER` target + properties or the associated :variable:`CMAKE_<LANG>_LINKER_LAUNCHER` + variables instead. + +See the :prop_gbl:`global property <RULE_LAUNCH_LINK>` of the same name for +details. This overrides the global and directory property for a target. 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..1b3f878 --- /dev/null +++ b/Help/prop_tgt/VERIFY_INTERFACE_HEADER_SETS.rst @@ -0,0 +1,30 @@ +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, interface 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, if C++ is enabled globally, the header is compiled as C++. +Otherwise, if C is enabled globally, the header is compiled as C. Otherwise, +the header file is not compiled. + +If the project wishes to control which header sets are verified by this +property, you can set :prop_tgt:`INTERFACE_HEADER_SETS_TO_VERIFY`. 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..e14ae58 --- /dev/null +++ b/Help/prop_tgt/VS_NO_COMPILE_BATCHING.rst @@ -0,0 +1,24 @@ +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. + +This property is initialized by the :variable:`CMAKE_VS_NO_COMPILE_BATCHING` +variable if it is set when a target is created. + +Example +^^^^^^^ + +This shows setting the property 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_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 index 47c4243..70a6175 100644 --- a/Help/release/3.23.rst +++ b/Help/release/3.23.rst @@ -187,7 +187,7 @@ CPack * The ``CPack.distribution.dist.in`` template used by the :cpack_gen:`CPack productbuild Generator` and - :cpack_gen:`CPack PackageMaker Generator` was updated to use a new + 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. diff --git a/Help/release/3.24.rst b/Help/release/3.24.rst new file mode 100644 index 0000000..02252e0 --- /dev/null +++ b/Help/release/3.24.rst @@ -0,0 +1,350 @@ +CMake 3.24 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.23 include the following. + +New Features +============ + +Presets +------- + +* :manual:`cmake-presets(7)` files now support schema version ``5``. + +* :manual:`cmake-presets(7)` files now support a ``${pathListSep}`` macro, + which expands to ``:`` or ``;`` based on the platform. + +* :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. + +Generators +---------- + +* The :generator:`Green Hills MULTI` generator now generates build + rules to re-run CMake if any CMake files are updated. + +* The :ref:`Visual Studio Generators` now support ``SYSTEM`` headers + when using VS 2019 Update 11 or later. + +Command-Line +------------ + +* :manual:`cmake(1)` gained the ``--fresh`` command-line option to remove + any existing ``CMakeCache.txt`` file and associated ``CMakeFiles/`` + directory, when configuring a build tree, thus starting a new configuration + as if the build tree were freshly created. + +* :manual:`cmake(1)` gained the ``--compile-no-warning-as-error`` command-line + option which causes the effects of the :prop_tgt:`COMPILE_WARNING_AS_ERROR` + target property and :variable:`CMAKE_COMPILE_WARNING_AS_ERROR` variable + to be ignored. + +* The :manual:`cmake(1)` ``--trace=json-v1`` trace format gained fields + ``global_frame`` and ``line_end``. + +* 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. + +* 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. + +Compilers +--------- + +* LLVM's `flang`_ Fortran compiler is now supported on some platforms, + with compiler id ``LLVMFlang``. + +.. _`flang`: https://github.com/llvm/llvm-project/tree/main/flang + +* ADSP compiler support (SHARC and Blackfin) now covers both CCES and + VDSP++ installations, with required configuration now done in the + compiler module itself rather than the ``Generic-ADSP`` platform module. + +Platforms +--------- + +* 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. + +Commands +-------- + +* The :command:`cmake_host_system_information` command, on Windows, + gained a ``QUERY WINDOWS_REGISTRY`` mode. + See its :ref:`Query Windows registry` section. + +* The :command:`cmake_language` command gained a new + ``SET_DEPENDENCY_PROVIDER`` sub-command. When a dependency provider is set, + calls to :command:`find_package` and :command:`FetchContent_MakeAvailable` + can be redirected through a custom command, which can choose to fulfill the + request directly, modify how the request is processed, or leave it to be + fulfilled by the built-in implementation. See :ref:`dependency_providers`. + +* The :command:`file(DOWNLOAD)` command gained options ``RANGE_START`` and + ``RANGE_END`` to specify a range of bytes to download. This can be + useful for downloading parts of big binary files. + +* The :command:`find_file`, :command:`find_path`, :command:`find_library`, + :command:`find_program`, and :command:`find_package` commands gained the + ``NO_CMAKE_INSTALL_PREFIX`` option to control searching + :variable:`CMAKE_INSTALL_PREFIX`. + +* The :command:`find_file`, :command:`find_path`, :command:`find_library`, + :command:`find_program`, and :command:`find_package` commands gained the + ability to specify which Windows Registry views must be queried. + +* The :command:`find_package` command gained a ``GLOBAL`` option that + allows for the promotion of imported targets to global scope for the + duration of the :command:`find_package` call. + +* The :command:`if` command gained the capability to compare paths by + using the ``PATH_EQUAL`` operator. See policy :policy:`CMP0139`. + +Variables +--------- + +* The :variable:`CMAKE_COLOR_DIAGNOSTICS` variable was added to control + color diagnostics generated by compilers. This variable also controls + color build system messages with :ref:`Makefile Generators`, replacing + :variable:`CMAKE_COLOR_MAKEFILE`. + + The :envvar:`CMAKE_COLOR_DIAGNOSTICS` environment variable was added to set + a default value for :variable:`CMAKE_COLOR_DIAGNOSTICS`. + +* The :variable:`CMAKE_COMPILE_WARNING_AS_ERROR` variable and corresponding + :prop_tgt:`COMPILE_WARNING_AS_ERROR` target property were added to enable + compilation with a compiler-specific flag to treat warnings as errors, + such as ``-Werror``. + +* 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). + +* The :variable:`CMAKE_FIND_PACKAGE_TARGETS_GLOBAL` variable was added to + toggle behavior of the :command:`find_package` command's new ``GLOBAL`` + option. + +* The :variable:`CMAKE_FIND_USE_INSTALL_PREFIX` variable was added 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. + +* 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. + +* 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. + +* The :variable:`CMAKE_VERIFY_INTERFACE_HEADER_SETS` variable and + corresponding :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` target property + were added to enable build rules that verify all headers in header sets + can be used on their own. + +* The :variable:`CMAKE_VS_NO_COMPILE_BATCHING` variable and corresponding + :prop_tgt:`VS_NO_COMPILE_BATCHING` target property were added to + tell :ref:`Visual Studio Generators` whether to disable compiler + parallelism and call the compiler with one source file at a time. + +* 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`. + +* The :variable:`CMAKE_XCODE_XCCONFIG` variable and corresponding + :prop_tgt:`XCODE_XCCONFIG` target property were added to tell + the :generator:`Xcode` generator to handle ``xcconfig`` files. + +Properties +---------- + +* 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:`INTERFACE_HEADER_SETS_TO_VERIFY` target property was + added to specify which header sets should be verified by + :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS`. + +* The :prop_tgt:`LINK_LIBRARIES` target property now supports + the :genex:`$<LINK_ONLY:...>` generator expression. + See policy :policy:`CMP0131`. + +* 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. + +Modules +------- + +* The :module:`ExternalProject` module :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. + Policy :policy:`CMP0135` was added to enable the option by default. + +* The :module:`FetchContent` module and the :command:`find_package` command + now support integration 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. + +* The :module:`FindJNI` module now provides imported targets. + +* 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. + +* The :module:`FindVulkan` module now supports components to select which + VulkanSDK tool and libraries to find in addition to the Vulkan SDK headers + and library. + +* The :module:`FindZLIB` gained a new ``ZLIB_USE_STATIC_LIBS`` variable to + search only for static libraries. + +Generator Expressions +--------------------- + +* The :genex:`LINK_LIBRARY` generator expression was added to manage how + libraries are specified during the link step. + The :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` and + :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables 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. + + The :genex:`LINK_LIBRARY` generator expression can link frameworks in + various ways when targeting ``Apple`` platforms. + The following features were added: + + * ``FRAMEWORK`` + * ``NEEDED_FRAMEWORK`` + * ``REEXPORT_FRAMEWORK`` + * ``WEAK_FRAMEWORK`` + + The :genex:`LINK_LIBRARY` generator expression can link libraries in + various ways when targeting ``Apple`` platforms. + The following features were added: + + * ``NEEDED_LIBRARY`` + * ``REEXPORT_LIBRARY`` + * ``WEAK_LIBRARY`` + + 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`` + +* The :genex:`LINK_GROUP` generator expression was added to manage the + grouping of libraries during the link step. The + :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` and + :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` variables are used to define + features usable with the :genex:`LINK_GROUP` generator expression. + This release defines the ``RESCAN`` feature, which can be used to handle + circular references among static libraries when using toolchains for + Linux, BSD, SunOS and GNU toolchains for Windows. + +* The :genex:`PATH` generator expression was added to manage paths. + +* The :genex:`PATH_EQUAL` generator expression was added to manage path + comparisons. + +* The :genex:`TARGET_BUNDLE_DIR_NAME` generator expression + was added to evaluate to the name of the bundle directory + for a given bundle target. + +CTest +----- + +* :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``. + +CPack +----- + +* 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. + +* 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`_. + +Deprecated and Removed Features +=============================== + +* 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. + +* The deprecated :cpack_gen:`CPack PackageMaker Generator` has been removed. + +* The :module:`FindGLUT` module no longer provides the undocumented + ``GLUT_LIBRARY`` and ``GLUT_INCLUDE_PATH`` result variables. + +Other Changes +============= + +* 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`. + +* The :module:`CheckIPOSupported` module :command:`check_ipo_supported` + command now uses the caller's :variable:`CMAKE_<LANG>_FLAGS` + and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` values. + See policy :policy:`CMP0138`. + +* The :generator:`MSYS Makefiles` and :generator:`MinGW Makefiles` + generators, when a compiler is not explicitly specified, now select + the first compiler (of any name) found in directories listed by the + ``PATH`` environment variable. + +* The :command:`try_compile` command + :ref:`whole-project <Try Compiling Whole Projects>` signature + now propagates platform variables. See policy :policy:`CMP0137`. + +* The :command:`while` command now diagnoses errors during condition + evaluation. See policy :policy:`CMP0130`. + +* The precompiled macOS binaries provided on `cmake.org`_ no longer attach a + SLA to the ``.dmg`` packages. This was removed because macOS 12 deprecated + the tools used to attach ``.dmg`` resources. + +* A precompiled Windows ``arm64`` binary is now provided on `cmake.org`_. + +.. _`cmake.org`: https://cmake.org/download/ diff --git a/Help/release/index.rst b/Help/release/index.rst index ee677a3..4dfac8a 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -13,6 +13,7 @@ Releases .. toctree:: :maxdepth: 1 + 3.24 <3.24> 3.23 <3.23> 3.22 <3.22> 3.21 <3.21> diff --git a/Help/variable/CMAKE_ADSP_ROOT.rst b/Help/variable/CMAKE_ADSP_ROOT.rst new file mode 100644 index 0000000..f6f3927 --- /dev/null +++ b/Help/variable/CMAKE_ADSP_ROOT.rst @@ -0,0 +1,11 @@ +CMAKE_ADSP_ROOT +--------------- + +.. versionadded:: 3.24 + +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_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_COMPILER_IS_GNUCC.rst b/Help/variable/CMAKE_COMPILER_IS_GNUCC.rst index 91cf848..4b799c0 100644 --- a/Help/variable/CMAKE_COMPILER_IS_GNUCC.rst +++ b/Help/variable/CMAKE_COMPILER_IS_GNUCC.rst @@ -1,7 +1,7 @@ CMAKE_COMPILER_IS_GNUCC ----------------------- -.. versionadded:: 3.7 - True if the ``C`` compiler is GNU. -Use :variable:`CMAKE_C_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` instead. + +This variable is deprecated. Use +:variable:`CMAKE_C_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` instead. diff --git a/Help/variable/CMAKE_COMPILER_IS_GNUCXX.rst b/Help/variable/CMAKE_COMPILER_IS_GNUCXX.rst index e67718a..29069d2 100644 --- a/Help/variable/CMAKE_COMPILER_IS_GNUCXX.rst +++ b/Help/variable/CMAKE_COMPILER_IS_GNUCXX.rst @@ -1,7 +1,7 @@ CMAKE_COMPILER_IS_GNUCXX ------------------------ -.. versionadded:: 3.7 - True if the C++ (``CXX``) compiler is GNU. -Use :variable:`CMAKE_CXX_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` instead. + +This variable is deprecated. Use +:variable:`CMAKE_CXX_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` instead. diff --git a/Help/variable/CMAKE_COMPILER_IS_GNUG77.rst b/Help/variable/CMAKE_COMPILER_IS_GNUG77.rst index f69c01a..05303dc 100644 --- a/Help/variable/CMAKE_COMPILER_IS_GNUG77.rst +++ b/Help/variable/CMAKE_COMPILER_IS_GNUG77.rst @@ -1,7 +1,7 @@ CMAKE_COMPILER_IS_GNUG77 ------------------------ -.. versionadded:: 3.7 - True if the ``Fortran`` compiler is GNU. -Use :variable:`CMAKE_Fortran_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` instead. + +This variable is deprecated. Use +:variable:`CMAKE_Fortran_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` instead. 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_FIND_PACKAGE_REDIRECTS_DIR.rst b/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst new file mode 100644 index 0000000..5d45fb0 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst @@ -0,0 +1,28 @@ +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-examples` +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..fc9b315 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_TARGETS_GLOBAL.rst @@ -0,0 +1,12 @@ +CMAKE_FIND_PACKAGE_TARGETS_GLOBAL +--------------------------------- + +.. versionadded:: 3.24 + +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_LANG_COMPILER_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_ID.rst index cd7d5cd..6a0a1d9 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_ID.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_ID.rst @@ -18,7 +18,8 @@ include: Clang = LLVM Clang (clang.llvm.org) Cray = Cray Compiler (cray.com) Embarcadero, Borland = Embarcadero (embarcadero.com) - Flang = Flang LLVM Fortran Compiler + Flang = Classic Flang Fortran Compiler (https://github.com/flang-compiler/flang) + LLVMFlang = LLVM Flang Fortran Compiler (https://github.com/llvm/llvm-project/tree/main/flang) Fujitsu = Fujitsu HPC compiler (Trad mode) FujitsuClang = Fujitsu HPC compiler (Clang mode) G95 = G95 Fortran (g95.org) 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..7c929d0 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE.rst @@ -0,0 +1,16 @@ +CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE> +--------------------------------------- + +.. versionadded:: 3.24 + +This variable defines how to link a group of libraries for the specified +``<FEATURE>`` when a :genex:`LINK_GROUP` generator expression is used and +the link language for the target is ``<LANG>``. +For this variable to have any effect, the associated +:variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` variable +must be set to true. + +The :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` variable should be defined +instead for features that are independent of the link language. + +.. include:: CMAKE_LINK_GROUP_USING_FEATURE.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..b314c5a --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE_SUPPORTED.rst @@ -0,0 +1,14 @@ +CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED +------------------------------------------------- + +.. versionadded:: 3.24 + +This variable specifies whether the ``<FEATURE>`` is supported for the link +language ``<LANG>``. If this variable is true, then the ``<FEATURE>`` must +be defined by :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>`, and the +more generic :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED` and +:variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` variables are not used. + +If ``CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED`` is false or is not +set, then the :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED` variable +will determine whether ``<FEATURE>`` is deemed to be 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..39fcff8 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE.rst @@ -0,0 +1,16 @@ +CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE> +----------------------------------------- + +.. versionadded:: 3.24 + +This variable defines how to link a library or framework for the specified +``<FEATURE>`` when a :genex:`LINK_LIBRARY` generator expression is used and +the link language for the target is ``<LANG>``. +For this variable to have any effect, the associated +:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` variable +must be set to true. + +The :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variable should be defined +instead for features that are independent of the link language. + +.. include:: CMAKE_LINK_LIBRARY_USING_FEATURE.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..90b7f8b --- /dev/null +++ b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.rst @@ -0,0 +1,22 @@ +CMAKE_LINK_GROUP_USING_<FEATURE> +-------------------------------- + +.. versionadded:: 3.24 + +This variable defines how to link a group of libraries for the specified +``<FEATURE>`` when a :genex:`LINK_GROUP` generator expression is used. +Both of the following conditions must be met for this variable to have any +effect: + +* The associated :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED` + variable must be set to true. + +* There is no language-specific definition for the same ``<FEATURE>``. + This means :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` + cannot be true for the link language used by the target for which the + :genex:`LINK_GROUP` generator expression is evaluated. + +The :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` variable should be +defined instead for features that are dependent on the link language. + +.. include:: CMAKE_LINK_GROUP_USING_FEATURE.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..23ea157 --- /dev/null +++ b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.txt @@ -0,0 +1,78 @@ +Feature names are case-sensitive and may only contain letters, numbers +and underscores. Feature names defined in all uppercase are reserved for +CMake's own built-in features (see `Predefined Features`_ further below). + + +Feature Definitions +^^^^^^^^^^^^^^^^^^^ + +A group feature definition is a list that contains exactly two elements: + +:: + + <PREFIX> <SUFFIX> + +On the linker command line, ``<PREFIX>`` will precede the list of libraries +in the group and ``<SUFFIX>`` will follow after. + +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 project may define two or more static libraries which have circular +dependencies between them. In order for the linker to resolve all symbols +at link time, it may need to search repeatedly among the libraries until no +new undefined references are created. Different linkers use different syntax +for achieving this. The following example shows how this may be implemented +for some linkers. Note that this is for illustration purposes only. +Projects should use the built-in ``RESCAN`` group feature instead +(see `Predefined Features`_), which provides a more complete and more robust +implementation of this functionality. + +.. 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(lib2 SHARED ...) + + if(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED) + target_link_libraries(lib2 PRIVATE "$<LINK_GROUP:cross_refs,lib1,external>") + else() + target_link_libraries(lib2 PRIVATE lib1 external) + endif() + +CMake will generate the following linker command line fragments when linking +``lib2``: + +* ``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`` + + +Predefined Features +^^^^^^^^^^^^^^^^^^^ + +The following built-in group features are pre-defined by CMake: + +.. include:: LINK_GROUP_PREDEFINED_FEATURES.txt 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..8b4ee6e --- /dev/null +++ b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED.rst @@ -0,0 +1,12 @@ +CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED +------------------------------------------ + +.. versionadded:: 3.24 + +This variable specifies whether the ``<FEATURE>`` is supported regardless of +the link language. If this variable is true, then the ``<FEATURE>`` must +be defined by :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>`. + +Note that this variable has no effect if +:variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` is true for +the link language of the target. 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..c652733 --- /dev/null +++ b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.rst @@ -0,0 +1,19 @@ +CMAKE_LINK_LIBRARY_USING_<FEATURE> +---------------------------------- + +.. versionadded:: 3.24 + +This variable defines how to link a library or framework for the specified +``<FEATURE>`` when a :genex:`LINK_LIBRARY` generator expression is used. +Both of the following conditions must be met for this variable to have any +effect: + +* The associated :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` + variable must be set to true. + +* There is no language-specific definition for the same ``<FEATURE>``. + This means :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` + cannot be true for the link language used by the target for which the + :genex:`LINK_LIBRARY` generator expression is evaluated. + +.. include:: CMAKE_LINK_LIBRARY_USING_FEATURE.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..4b13b7c --- /dev/null +++ b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.txt @@ -0,0 +1,150 @@ +Feature names are case-sensitive and may only contain letters, numbers +and underscores. Feature names defined in all uppercase are reserved for +CMake's own built-in features (see `Predefined Features`_ further below). + + +Feature Definitions +^^^^^^^^^^^^^^^^^^^ + +A library feature definition is a list that contains one or three elements: + +:: + + [<PREFIX>] <LIBRARY_EXPRESSION> [<SUFFIX>] + +When ``<PREFIX>`` and ``<SUFFIX>`` are specified, they precede and follow +respectively the whole list of libraries specified in the +:genex:`LINK_LIBRARY` expression, not each library item individually. +There is no guarantee that the list of specified libraries will be kept +grouped together though, so the ``<PREFIX>`` and ``<SUFFIX>`` may appear +more than once if the library list is reorganized by CMake to satisfy other +constraints. This means constructs like ``--start-group`` and ``--end-group``, +as supported by the GNU ``ld`` linker, cannot be used in this way. The +:genex:`LINK_GROUP` generator expression should be used instead for such +constructs. + +``<LIBRARY_EXPRESSION>`` is used to specify the pattern for constructing the +corresponding fragment on the linker command line for each library. +The following placeholders can be used in the expression: + +* ``<LIBRARY>`` is expanded to the full path to the library for CMake targets, + or to a platform-specific value based on the item otherwise (the same as + ``<LINK_ITEM>`` on Windows, or the library base name for other platforms). +* ``<LINK_ITEM>`` is expanded to how the library would normally be linked on + the linker command line. +* ``<LIB_ITEM>`` is expanded to the full path to the library for CMake targets, + or the item itself exactly as specified in the ``<LIBRARY_EXPRESSION>`` + otherwise. + +In addition to the above, it is possible to have one pattern for paths +(CMake targets and external libraries specified with file paths) and another +for other items specified by name only. The ``PATH{}`` and ``NAME{}`` wrappers +can be used to provide the expansion for those two cases, respectively. +When wrappers are used, both must be present. For example: + +.. code-block:: cmake + + set(CMAKE_LINK_LIBRARY_USING_weak_library + "PATH{-weak_library <LIBRARY>}NAME{LINKER:-weak-l<LIB_ITEM>}" + ) + +For all three elements of this variable (``<PREFIX>``, ``<LIBRARY_EXPRESSION>``, +and ``<SUFFIX>``), 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 to prevent the linker from discarding any symbols from a +static library. Different linkers use different syntax for achieving this. +The following example shows how this may be implemented for some linkers. +Note that this is for illustration purposes only. Projects should use the +built-in ``WHOLE_ARCHIVE`` feature instead (see `Predefined Features`_), which +provides a more complete and more robust implementation of this functionality. + +.. 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) + # The -force_load Apple linker option requires a file name + set(external_lib + "$<IF:$<LINK_LANG_AND_ID:C,AppleClang>,libexternal.a,external>" + ) + target_link_libraries(lib2 PRIVATE + "$<LINK_LIBRARY:load_archive,lib1,${external_lib}>" + ) + else() + target_link_libraries(lib2 PRIVATE lib1 external) + endif() + +CMake will generate the following link expressions: + +* ``AppleClang``: ``-force_load /path/to/lib1.a -force_load libexternal.a`` +* ``GNU``: ``-Wl,--push-state,--whole-archive /path/to/lib1.a -lexternal -Wl,--pop-state`` +* ``MSVC``: ``/WHOLEARCHIVE:/path/to/lib1.lib /WHOLEARCHIVE:external.lib`` + +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). Different flags must be used for a +library specified by file path compared to one specified by name. +This constraint can be solved using ``PATH{}`` and ``NAME{}`` wrappers. +Again, the following example shows how this may be implemented for some +linkers, but it is for illustration purposes only. Projects should use the +built-in ``WEAK_FRAMEWORK`` or ``WEAK_LIBRARY`` features instead (see +`Predefined Features`_), which provide more complete and more robust +implementations of this functionality. + +.. 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 linker command line fragment when linking +``main`` using the ``AppleClang`` toolchain: + +``-weak_library /path/to/lib -Xlinker -weak-lexternal``. + + +Predefined Features +^^^^^^^^^^^^^^^^^^^ + +The following built-in library features are pre-defined by CMake: + +.. include:: LINK_LIBRARY_PREDEFINED_FEATURES.txt 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_OSX_VARIABLE.txt b/Help/variable/CMAKE_OSX_VARIABLE.txt index 16f3c1a..5670980 100644 --- a/Help/variable/CMAKE_OSX_VARIABLE.txt +++ b/Help/variable/CMAKE_OSX_VARIABLE.txt @@ -3,7 +3,8 @@ The value of this variable should be set prior to the first because it may influence configuration of the toolchain and flags. It is intended to be set locally by the user creating a build tree. This variable should be set as a ``CACHE`` entry (or else CMake may -remove it while initializing a cache entry of the same name). +remove it while initializing a cache entry of the same name) unless +policy :policy:`CMP0126` is set to ``NEW``. Despite the ``OSX`` part in the variable name(s) they apply also to other SDKs than macOS like iOS, tvOS, or watchOS. diff --git a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst index 8c84f91..9dce760 100644 --- a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst @@ -36,6 +36,8 @@ only for the policies that do not warn by default: 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_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..c68a36c --- /dev/null +++ b/Help/variable/CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES.rst @@ -0,0 +1,12 @@ +CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES +--------------------------------------- + +.. versionadded:: 3.24 + +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_NO_COMPILE_BATCHING.rst b/Help/variable/CMAKE_VS_NO_COMPILE_BATCHING.rst new file mode 100644 index 0000000..2fb163e --- /dev/null +++ b/Help/variable/CMAKE_VS_NO_COMPILE_BATCHING.rst @@ -0,0 +1,20 @@ +CMAKE_VS_NO_COMPILE_BATCHING +---------------------------- + +.. versionadded:: 3.24 + +Turn off compile batching when using :ref:`Visual Studio Generators`. + +This variable is used to initialize the :prop_tgt:`VS_NO_COMPILE_BATCHING` +property on all targets when they are created. See that target property for +additional information. + +Example +^^^^^^^ + +This shows setting the property for the target ``foo`` using the variable. + +.. code-block:: cmake + + set(CMAKE_VS_NO_COMPILE_BATCHING ON) + add_library(foo SHARED foo.cpp) diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst index 84d7212..5c13bb7 100644 --- a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst @@ -9,4 +9,4 @@ The :ref:`Visual Studio Generators` for VS 2013 and above support using either the 32-bit or 64-bit host toolchains by specifying a ``host=x86`` or ``host=x64`` value in the :variable:`CMAKE_GENERATOR_TOOLSET` option. CMake provides the selected toolchain architecture preference in this -variable (``x86``, ``x64``, or empty). +variable (``x86``, ``x64``, ``ARM64`` or empty). 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_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_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/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/LINK_GROUP_PREDEFINED_FEATURES.txt b/Help/variable/LINK_GROUP_PREDEFINED_FEATURES.txt new file mode 100644 index 0000000..557886e --- /dev/null +++ b/Help/variable/LINK_GROUP_PREDEFINED_FEATURES.txt @@ -0,0 +1,22 @@ +``RESCAN`` + Some linkers are single-pass only. For such linkers, circular references + between libraries typically result in unresolved symbols. This feature + instructs the linker to search the specified static libraries repeatedly + until no new undefined references are created. + + Normally, a 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 a library that + appears later on the command line, the linker would not be able to resolve + that reference. By grouping the static libraries with the ``RESCAN`` + feature, they will all be searched repeatedly until all possible references + are resolved. This will use linker options like ``--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 when using toolchains that target Linux, BSD, and + SunOS. It can also be used when targeting Windows platforms if the 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..8ae6c57 --- /dev/null +++ b/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt @@ -0,0 +1,96 @@ +``DEFAULT`` + This feature corresponds to standard linking, essentially equivalent to + using no feature at all. It is typically only used with the + :prop_tgt:`LINK_LIBRARY_OVERRIDE` and + :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties. + +``WHOLE_ARCHIVE`` + Force inclusion of all members of a static library. This feature is only + supported for the following platforms, with limitations as noted: + + * Linux. + * All BSD variants. + * SunOS. + * All Apple variants. 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``). Due to a limitation of the Apple linker, it + cannot be specified as a plain library name like ``foo``, where ``foo`` + is not a CMake target. + * Windows. When using a MSVC or MSVC-like toolchain, the MSVC version must + be greater than 1900. + * Cygwin. + * MSYS. + +``FRAMEWORK`` + This option tells the linker to search for the specified framework using + the ``-framework`` linker option. It can only be used on Apple platforms, + and only with a linker that understands the option used (i.e. the linker + provided with Xcode, or one compatible with it). + + The framework can be specified as a CMake framework target, a bare framework + name, or a file path. If a target is given, that target must have the + :prop_tgt:`FRAMEWORK` target property set to true. For a file path, if it + contains a directory part, that directory will be added as a framework + search path. + + .. code-block:: cmake + + add_library(lib SHARED ...) + target_link_libraries(lib PRIVATE "$<LINK_LIBRARY:FRAMEWORK,/path/to/my_framework>") + + # The constructed linker command line will contain: + # -F/path/to -framework my_framework + + File paths must conform to one of the following patterns (``*`` is a + wildcard, and optional parts are shown as ``[...]``): + + * ``[/path/to/]FwName[.framework]`` + * ``[/path/to/]FwName.framework/FwName`` + * ``[/path/to/]FwName.framework/Versions/*/FwName`` + + Note that CMake recognizes and automatically handles framework targets, + even without using the ``$<LINK_LIBRARY:FRAMEWORK,...>`` expression. + The generator expression can still be used with a CMake target if the + project wants to be explicit about it, but it is not required to do so. + The linker command line may have some differences between using the + generator expression or not, but the final result should be the same. + On the other hand, if a file path is given, CMake will recognize some paths + automatically, but not all cases. The project may want to use + ``$<LINK_LIBRARY:FRAMEWORK,...>`` for file paths so that the expected + behavior is clear. + +``NEEDED_FRAMEWORK`` + This is similar to the ``FRAMEWORK`` feature, except it forces the linker + to link with the framework even if no symbols are used from it. It uses + the ``-needed_framework`` option and has the same linker constraints as + ``FRAMEWORK``. + +``REEXPORT_FRAMEWORK`` + This is similar to the ``FRAMEWORK`` feature, except it tells the linker + that the framework should be available to clients linking to the library + being created. It uses the ``-reexport_framework`` option and has the + same linker constraints as ``FRAMEWORK``. + +``WEAK_FRAMEWORK`` + This is similar to the ``FRAMEWORK`` feature, except it forces the linker + to mark the framework and all references to it as weak imports. It uses + the ``-weak_framework`` option and has the same linker constraints as + ``FRAMEWORK``. + +``NEEDED_LIBRARY`` + This is similar to the ``NEEDED_FRAMEWORK`` feature, except it is for use + with non-framework targets or libraries (Apple platforms only). + It uses the ``-needed_library`` or ``-needed-l`` option as appropriate, + and has the same linker constraints as ``NEEDED_FRAMEWORK``. + +``REEXPORT_LIBRARY`` + This is similar to the ``REEXPORT_FRAMEWORK`` feature, except it is for use + with non-framework targets or libraries (Apple platforms only). + It uses the ``-reexport_library`` or ``-reexport-l`` option as appropriate, + and has the same linker constraints as ``REEXPORT_FRAMEWORK``. + +``WEAK_LIBRARY`` + This is similar to the ``WEAK_FRAMEWORK`` feature, except it is for use + with non-framework targets or libraries (Apple platforms only). + It uses the ``-weak_library`` or ``-weak-l`` option as appropriate, + and has the same linker constraints as ``WEAK_FRAMEWORK``. diff --git a/Help/variable/PROJECT-NAME_IS_TOP_LEVEL.rst b/Help/variable/PROJECT-NAME_IS_TOP_LEVEL.rst index 6718ecf..ca3a769 100644 --- a/Help/variable/PROJECT-NAME_IS_TOP_LEVEL.rst +++ b/Help/variable/PROJECT-NAME_IS_TOP_LEVEL.rst @@ -13,9 +13,16 @@ the current directory scope or above, see the The variable value will be true in: * the top-level directory of the project -* the top-level directory of an external project added by :module:`ExternalProject` +* the top-level directory of an external project added by + :module:`ExternalProject` +* a directory added by :command:`add_subdirectory` that does not also contain + a :command:`project` call +* a directory added by :command:`FetchContent_MakeAvailable`, + if the fetched content does not contain a :command:`project` call The variable value will be false in: -* a directory added by :command:`add_subdirectory` -* a directory added by :module:`FetchContent` +* a directory added by :command:`add_subdirectory` that also contains + a :command:`project` call +* a directory added by :command:`FetchContent_MakeAvailable`, + if the fetched content contains a :command:`project` call diff --git a/Help/variable/PROJECT_IS_TOP_LEVEL.rst b/Help/variable/PROJECT_IS_TOP_LEVEL.rst index 7e40704..871dfdb 100644 --- a/Help/variable/PROJECT_IS_TOP_LEVEL.rst +++ b/Help/variable/PROJECT_IS_TOP_LEVEL.rst @@ -24,9 +24,16 @@ options: The variable value will be true in: * the top-level directory of the project -* the top-level directory of an external project added by :module:`ExternalProject` +* the top-level directory of an external project added by + :module:`ExternalProject` +* a directory added by :command:`add_subdirectory` that does not also contain + a :command:`project` call +* a directory added by :command:`FetchContent_MakeAvailable`, + if the fetched content does not contain a :command:`project` call The variable value will be false in: -* a directory added by :command:`add_subdirectory` -* a directory added by :module:`FetchContent` +* a directory added by :command:`add_subdirectory` that also contains + a :command:`project` call +* a directory added by :command:`FetchContent_MakeAvailable`, + if the fetched content contains a :command:`project` call |