diff options
Diffstat (limited to 'Help/command')
| -rw-r--r-- | Help/command/FIND_XXX.txt | 21 | ||||
| -rw-r--r-- | Help/command/FIND_XXX_REGISTRY_VIEW.txt | 41 | ||||
| -rw-r--r-- | Help/command/add_custom_command.rst | 9 | ||||
| -rw-r--r-- | Help/command/cmake_host_system_information.rst | 154 | ||||
| -rw-r--r-- | Help/command/cmake_language.rst | 266 | ||||
| -rw-r--r-- | Help/command/cmake_path.rst | 18 | ||||
| -rw-r--r-- | Help/command/ctest_test.rst | 10 | ||||
| -rw-r--r-- | Help/command/execute_process.rst | 11 | ||||
| -rw-r--r-- | Help/command/file.rst | 19 | ||||
| -rw-r--r-- | Help/command/find_file.rst | 2 | ||||
| -rw-r--r-- | Help/command/find_library.rst | 2 | ||||
| -rw-r--r-- | Help/command/find_package.rst | 116 | ||||
| -rw-r--r-- | Help/command/find_path.rst | 2 | ||||
| -rw-r--r-- | Help/command/find_program.rst | 2 | ||||
| -rw-r--r-- | Help/command/get_filename_component.rst | 10 | ||||
| -rw-r--r-- | Help/command/if.rst | 40 | ||||
| -rw-r--r-- | Help/command/install.rst | 2 | ||||
| -rw-r--r-- | Help/command/message.rst | 3 | ||||
| -rw-r--r-- | Help/command/option.rst | 10 | ||||
| -rw-r--r-- | Help/command/project.rst | 66 | ||||
| -rw-r--r-- | Help/command/target_sources.rst | 4 | ||||
| -rw-r--r-- | Help/command/try_compile.rst | 16 |
22 files changed, 755 insertions, 69 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index ee6c1cc..cd3c78b 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,12 @@ 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`` and + ``CMAKE_STAGING_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..6cab1d1 --- /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`` platforms and will be ignored on other ones. When not +specified, the |FIND_XXX_REGISTRY_VIEW_DEFAULT| view is used when the +:policy:`CMP0134` policy is ``NEW``. Refer to :policy:`CMP0134` for the +default view when the policy is ``OLD``. + +``64`` + Query the 64-bit registry. On 32-bit Windows, it always returns the string + ``/REGISTRY-NOTFOUND``. + +``32`` + Query the 32-bit 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 64-bit + Windows and ``32`` on 32-bit Windows. + +``TARGET`` + Query the registry matching the architecture specified by the + :variable:`CMAKE_SIZEOF_VOID_P` variable. If not defined, fall back to + ``HOST`` view. + +``BOTH`` + Query both views (``32`` and ``64``). The order depends on the following + rules: If the :variable:`CMAKE_SIZEOF_VOID_P` variable is defined, use the + following view depending on the content of this variable: + + * ``8``: ``64_32`` + * ``4``: ``32_64`` + + If the :variable:`CMAKE_SIZEOF_VOID_P` variable is not defined, rely on the + architecture of the host: + + * 64-bit: ``64_32`` + * 32-bit: ``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..65f82d7 100644 --- a/Help/command/ctest_test.rst +++ b/Help/command/ctest_test.rst @@ -172,8 +172,12 @@ 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, along with their +corresponding :manual:`ctest(1)` command line options +``--test-output-size-passed``, ``--test-output-size-failed``, and +``--test-output-truncation``. .. _`Additional Test Measurements`: @@ -235,7 +239,7 @@ The following example demonstrates how to upload test images to CDash. "/dir/to/valid_img.gif</CTestMeasurementFile>" << std::endl; std::cout << - "<CTestMeasurementFile type=\"image/png\" name=\"AlgoResult\"> << + "<CTestMeasurementFile type=\"image/png\" name=\"AlgoResult\">" << "/dir/to/img.png</CTestMeasurementFile>" << std::endl; 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..c96d84e 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 specifies which registry views should be + queried. This keyword is only meaningful on ``Windows`` platforms and will + be ignored on all others. 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,12 @@ 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` and + :variable:`CMAKE_STAGING_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 +448,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 +459,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 +483,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 +619,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. |