diff --git a/.clang-tidy b/.clang-tidy index c790467ae..1b776e17f 100644 --- a/.clang-tidy +++ b/.clang-tidy @@ -15,6 +15,7 @@ misc-*,\ -misc-no-recursion,\ -misc-non-private-member-variables-in-classes,\ -misc-static-assert,\ +-misc-use-anonymous-namespace,\ modernize-*,\ -modernize-avoid-c-arrays,\ -modernize-macro-to-enum,\ diff --git a/Auxiliary/cmake-mode.el b/Auxiliary/cmake-mode.el index a11becbe2..6bd23bf38 100644 --- a/Auxiliary/cmake-mode.el +++ b/Auxiliary/cmake-mode.el @@ -372,7 +372,7 @@ optional argument topic will be appended to the argument list." (interactive "s") (let* ((bufname (if buffer buffer (concat "*CMake" type (if topic "-") topic "*"))) (buffer (if (get-buffer bufname) (get-buffer bufname) (generate-new-buffer bufname))) - (command (concat cmake-mode-cmake-executable " " type " " topic)) + (command (concat cmake-mode-cmake-executable " " type " " (if topic (shell-quote-argument topic) topic))) ;; Turn of resizing of mini-windows for shell-command. (resize-mini-windows nil) ) @@ -391,7 +391,7 @@ optional argument topic will be appended to the argument list." (interactive "s") (let* ((bufname (if buffer buffer (concat "*CMake" type (if topic "-") topic "*"))) (buffer (if (get-buffer bufname) (get-buffer bufname) (generate-new-buffer bufname))) - (command (concat cmake-mode-cmake-executable " " type " " topic)) + (command (concat cmake-mode-cmake-executable " " type " " (if topic (shell-quote-argument topic) topic))) ;; Turn of resizing of mini-windows for shell-command. (resize-mini-windows nil) ) diff --git a/Auxiliary/vim/syntax/cmake.vim b/Auxiliary/vim/syntax/cmake.vim index 5e936c29d..bc8b06a64 100644 --- a/Auxiliary/vim/syntax/cmake.vim +++ b/Auxiliary/vim/syntax/cmake.vim @@ -73,6 +73,7 @@ syn keyword cmakeProperty contained \ AUTOGEN_ORIGIN_DEPENDS \ AUTOGEN_PARALLEL \ AUTOGEN_SOURCE_GROUP + \ AUTOGEN_USE_SYSTEM_INCLUDE \ AUTOGEN_TARGETS_FOLDER \ AUTOGEN_TARGET_DEPENDS \ AUTOMOC @@ -128,7 +129,10 @@ syn keyword cmakeProperty contained \ CPACK_WIX_ACL \ CROSSCOMPILING_EMULATOR \ CUDA_ARCHITECTURES + \ CUDA_CUBIN_COMPILATION \ CUDA_EXTENSIONS + \ CUDA_FATBIN_COMPILATION + \ CUDA_OPTIX_COMPILATION \ CUDA_PTX_COMPILATION \ CUDA_RESOLVE_DEVICE_SYMBOLS \ CUDA_RUNTIME_LIBRARY @@ -217,6 +221,7 @@ syn keyword cmakeProperty contained \ INSTALL_RPATH \ INSTALL_RPATH_USE_LINK_PATH \ INTERFACE_AUTOUIC_OPTIONS + \ INTERFACE_AUTOMOC_MACRO_NAMES \ INTERFACE_COMPILE_DEFINITIONS \ INTERFACE_COMPILE_FEATURES \ INTERFACE_COMPILE_OPTIONS @@ -320,6 +325,7 @@ syn keyword cmakeProperty contained \ SKIP_AUTORCC \ SKIP_AUTOUIC \ SKIP_BUILD_RPATH + \ SKIP_LINTING \ SKIP_PRECOMPILE_HEADERS \ SKIP_REGULAR_EXPRESSION \ SKIP_RETURN_CODE @@ -459,6 +465,7 @@ syn keyword cmakeVariable contained \ BUILD_SHARED_LIBS \ CACHE \ CMAKE_ABSOLUTE_DESTINATION_FILES + \ CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY \ CMAKE_AIX_EXPORT_ALL_SYMBOLS \ CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS \ CMAKE_ANDROID_API @@ -678,6 +685,7 @@ syn keyword cmakeVariable contained \ CMAKE_ASM_VISIBILITY_PRESET \ CMAKE_AUTOGEN_ORIGIN_DEPENDS \ CMAKE_AUTOGEN_PARALLEL + \ CMAKE_AUTOGEN_USE_SYSTEM_INCLUDE \ CMAKE_AUTOGEN_VERBOSE \ CMAKE_AUTOMOC \ CMAKE_AUTOMOC_COMPILER_PREDEFINES @@ -686,11 +694,14 @@ syn keyword cmakeVariable contained \ CMAKE_AUTOMOC_MOC_OPTIONS \ CMAKE_AUTOMOC_PATH_PREFIX \ CMAKE_AUTOMOC_RELAXED_MODE + \ CMAKE_AUTOMOC_EXECUTABLE \ CMAKE_AUTORCC \ CMAKE_AUTORCC_OPTIONS + \ CMAKE_AUTORCC_EXECUTABLE \ CMAKE_AUTOUIC \ CMAKE_AUTOUIC_OPTIONS \ CMAKE_AUTOUIC_SEARCH_PATHS + \ CMAKE_AUTOUIC_EXECUTABLE \ CMAKE_BACKWARDS_COMPATIBILITY \ CMAKE_BINARY_DIR \ CMAKE_BUILD_RPATH @@ -2095,6 +2106,7 @@ syn keyword cmakeKWadd_custom_command contained \ COMMENT \ CROSSCOMPILING_EMULATOR \ DEPENDS + \ DEPENDS_EXPLICIT_ONLY \ DEPFILE \ GENERATED \ IMPLICIT_DEPENDS @@ -2735,6 +2747,7 @@ syn keyword cmakeKWfile contained \ READ_SYMLINK \ REAL_PATH \ REGEX + \ RELATIVE \ RELATIVE_PATH \ RELEASE \ REMOVE diff --git a/CMakeLists.txt b/CMakeLists.txt index 0ce42fb3a..d559c0855 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,7 +1,7 @@ # Distributed under the OSI-approved BSD 3-Clause License. See accompanying # file Copyright.txt or https://cmake.org/licensing for details. -cmake_minimum_required(VERSION 3.13...3.24 FATAL_ERROR) +cmake_minimum_required(VERSION 3.13...3.25 FATAL_ERROR) set(CMAKE_USER_MAKE_RULES_OVERRIDE_C ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideC.cmake) set(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideCXX.cmake) @@ -131,6 +131,23 @@ if(CMake_BUILD_LTO) endif() endif() +# Check whether to build support for the debugger mode. +if(NOT CMake_TEST_EXTERNAL_CMAKE) + if(NOT DEFINED CMake_ENABLE_DEBUGGER) + # The debugger uses cppdap, which does not compile everywhere. + if(CMAKE_SYSTEM_NAME MATCHES "Windows|Darwin|Linux|BSD|DragonFly|CYGWIN|MSYS" + AND NOT (CMAKE_CXX_COMPILER_ID STREQUAL "MSVC" AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 19.16) + AND NOT (CMAKE_CXX_COMPILER_ID STREQUAL "XLClang" AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 16.1) + ) + set(CMake_ENABLE_DEBUGGER 1) + else() + set(CMake_ENABLE_DEBUGGER 0) + endif() + endif() +else() + set(CMake_ENABLE_DEBUGGER 0) +endif() + #----------------------------------------------------------------------- # a macro to deal with system libraries, implemented as a macro # simply to improve readability of the main script @@ -141,7 +158,7 @@ macro(CMAKE_HANDLE_SYSTEM_LIBRARIES) # Allow the user to enable/disable all system utility library options by # defining CMAKE_USE_SYSTEM_LIBRARIES or CMAKE_USE_SYSTEM_LIBRARY_${util}. - set(UTILITIES BZIP2 CURL EXPAT FORM JSONCPP LIBARCHIVE LIBLZMA LIBRHASH LIBUV NGHTTP2 ZLIB ZSTD) + set(UTILITIES BZIP2 CPPDAP CURL EXPAT FORM JSONCPP LIBARCHIVE LIBLZMA LIBRHASH LIBUV NGHTTP2 ZLIB ZSTD) foreach(util IN LISTS UTILITIES) if(NOT DEFINED CMAKE_USE_SYSTEM_LIBRARY_${util} AND DEFINED CMAKE_USE_SYSTEM_LIBRARIES) @@ -169,6 +186,9 @@ macro(CMAKE_HANDLE_SYSTEM_LIBRARIES) # Optionally use system utility libraries. option(CMAKE_USE_SYSTEM_LIBARCHIVE "Use system-installed libarchive" "${CMAKE_USE_SYSTEM_LIBRARY_LIBARCHIVE}") + if(CMake_ENABLE_DEBUGGER) + option(CMAKE_USE_SYSTEM_CPPDAP "Use system-installed cppdap" "${CMAKE_USE_SYSTEM_LIBRARY_CPPDAP}") + endif() option(CMAKE_USE_SYSTEM_CURL "Use system-installed curl" "${CMAKE_USE_SYSTEM_LIBRARY_CURL}") option(CMAKE_USE_SYSTEM_EXPAT "Use system-installed expat" "${CMAKE_USE_SYSTEM_LIBRARY_EXPAT}") CMAKE_DEPENDENT_OPTION(CMAKE_USE_SYSTEM_ZLIB "Use system-installed zlib" @@ -182,7 +202,8 @@ macro(CMAKE_HANDLE_SYSTEM_LIBRARIES) CMAKE_DEPENDENT_OPTION(CMAKE_USE_SYSTEM_NGHTTP2 "Use system-installed nghttp2" "${CMAKE_USE_SYSTEM_LIBRARY_NGHTTP2}" "NOT CMAKE_USE_SYSTEM_CURL" ON) option(CMAKE_USE_SYSTEM_FORM "Use system-installed libform" "${CMAKE_USE_SYSTEM_LIBRARY_FORM}") - option(CMAKE_USE_SYSTEM_JSONCPP "Use system-installed jsoncpp" "${CMAKE_USE_SYSTEM_LIBRARY_JSONCPP}") + CMAKE_DEPENDENT_OPTION(CMAKE_USE_SYSTEM_JSONCPP "Use system-installed jsoncpp" + "${CMAKE_USE_SYSTEM_LIBRARY_JSONCPP}" "NOT CMAKE_USE_SYSTEM_CPPDAP" ON) option(CMAKE_USE_SYSTEM_LIBRHASH "Use system-installed librhash" "${CMAKE_USE_SYSTEM_LIBRARY_LIBRHASH}") option(CMAKE_USE_SYSTEM_LIBUV "Use system-installed libuv" "${CMAKE_USE_SYSTEM_LIBRARY_LIBUV}") diff --git a/CompileFlags.cmake b/CompileFlags.cmake index 6331af11c..f94e079ad 100644 --- a/CompileFlags.cmake +++ b/CompileFlags.cmake @@ -8,7 +8,7 @@ if(WIN32 AND CMAKE_C_COMPILER_ID STREQUAL "Intel") set(_INTEL_WINDOWS 1) endif() -if(WIN32 AND CMAKE_C_COMPILER_ID STREQUAL "Clang" +if(WIN32 AND CMAKE_C_COMPILER_ID MATCHES "^(Clang|IntelLLVM)$" AND "x${CMAKE_CXX_SIMULATE_ID}" STREQUAL "xMSVC") set(_CLANG_MSVC_WINDOWS 1) endif() @@ -22,18 +22,19 @@ if(MSVC OR _INTEL_WINDOWS OR _CLANG_MSVC_WINDOWS) else() endif() -if(MSVC) - set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} ${CMAKE_CXX_LINKER_WRAPPER_FLAG}-stack:10000000") -endif() - # MSVC 14.28 enables C5105, but the Windows SDK 10.0.18362.0 triggers it. if(CMAKE_C_COMPILER_ID STREQUAL "MSVC" AND NOT CMAKE_C_COMPILER_VERSION VERSION_LESS 19.28) set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -wd5105") set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -wd5105") endif() -if(_CLANG_MSVC_WINDOWS AND "x${CMAKE_CXX_COMPILER_FRONTEND_VARIANT}" STREQUAL "xGNU") - set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -Xlinker -stack:20000000") +# Use a stack size large enough for CMake_DEFAULT_RECURSION_LIMIT. +if(MSVC) + string(APPEND CMAKE_EXE_LINKER_FLAGS " ${CMAKE_CXX_LINKER_WRAPPER_FLAG}-stack:10000000") +elseif(MINGW OR MSYS OR CYGWIN) + string(APPEND CMAKE_EXE_LINKER_FLAGS " -Wl,--stack,10000000") +elseif(_CLANG_MSVC_WINDOWS AND "x${CMAKE_CXX_COMPILER_FRONTEND_VARIANT}" STREQUAL "xGNU") + string(APPEND CMAKE_EXE_LINKER_FLAGS " -Xlinker -stack:20000000") endif() #silence duplicate symbol warnings on AIX diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index bd55e24c7..fe26d2b9a 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -132,6 +132,9 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: .. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace:: |prefix_XXX_SUBDIR| for each ```` in :variable:`CMAKE_PREFIX_PATH` +.. |ENV_CMAKE_PREFIX_PATH_XXX_SUBDIR| replace:: + |prefix_XXX_SUBDIR| for each ```` in :envvar:`CMAKE_PREFIX_PATH` + .. |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR| replace:: |prefix_XXX_SUBDIR| for each ``/[s]bin`` in ``PATH``, and |entry_XXX_SUBDIR| for other entries in ``PATH`` @@ -140,21 +143,40 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: |prefix_XXX_SUBDIR| for each ```` in :variable:`CMAKE_SYSTEM_PREFIX_PATH` -1. .. versionadded:: 3.12 - If called from within a find module or any other script loaded by a call to - :command:`find_package()`, search prefixes unique to the - current package being found. Specifically, look in the - :variable:`_ROOT` CMake variable and the - :envvar:`_ROOT` environment variable. - The package root variables are maintained as a stack, so if called from - nested find modules or config packages, root paths from the parent's find - module or config package will be searched after paths from the current - module or package. In other words, the search order would be - ``_ROOT``, ``ENV{_ROOT}``, - ``_ROOT``, ``ENV{_ROOT}``, etc. - This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting - the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``. - See policy :policy:`CMP0074`. +1. If called from within a find module or any other script loaded by a call to + :command:`find_package()`, search prefixes unique to the + current package being found. See policy :policy:`CMP0074`. + + .. versionadded:: 3.12 + + Specifically, search paths specified by the following variables, in order: + + a. :variable:`_ROOT` CMake variable, + where ```` is the case-preserved package name. + + b. :variable:`_ROOT` CMake variable, + where ```` is the upper-cased package name. + See policy :policy:`CMP0144`. + + .. versionadded:: 3.27 + + c. :envvar:`_ROOT` environment variable, + where ```` is the case-preserved package name. + + d. :envvar:`_ROOT` environment variable, + where ```` is the upper-cased package name. + See policy :policy:`CMP0144`. + + .. versionadded:: 3.27 + + The package root variables are maintained as a stack, so if called from + nested find modules or config packages, root paths from the parent's find + module or config package will be searched after paths from the current + module or package. In other words, the search order would be + ``_ROOT``, ``ENV{_ROOT}``, + ``_ROOT``, ``ENV{_ROOT}``, etc. + This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting + the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``. * |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| @@ -175,9 +197,9 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``. - * |CMAKE_PREFIX_PATH_XXX| - * |CMAKE_XXX_PATH| - * |CMAKE_XXX_MAC_PATH| + * |ENV_CMAKE_PREFIX_PATH_XXX| + * |ENV_CMAKE_XXX_PATH| + * |ENV_CMAKE_XXX_MAC_PATH| 4. Search the paths specified by the ``HINTS`` option. These should be paths computed by system introspection, such as a diff --git a/Help/command/UNSET_NOTE.txt b/Help/command/UNSET_NOTE.txt new file mode 100644 index 000000000..8dc912533 --- /dev/null +++ b/Help/command/UNSET_NOTE.txt @@ -0,0 +1,9 @@ +.. note:: + + When evaluating :ref:`Variable References` of the form ``${VAR}``, CMake + first searches for a normal variable with that name. If no such normal + variable exists, CMake will then search for a cache entry with that name. + Because of this, **unsetting a normal variable can expose a cache variable + that was previously hidden**. To force a variable reference of the form + ``${VAR}`` to return an empty string, use ``set( "")``, which + clears the normal variable but leaves it defined. diff --git a/Help/command/add_compile_options.rst b/Help/command/add_compile_options.rst index 0ccebc679..869d0c2ce 100644 --- a/Help/command/add_compile_options.rst +++ b/Help/command/add_compile_options.rst @@ -11,6 +11,11 @@ Adds options to the :prop_dir:`COMPILE_OPTIONS` directory property. These options are used when compiling targets from the current directory and below. +.. note:: + + These options are not used when linking. + See the :command:`add_link_options` command for that. + Arguments ^^^^^^^^^ @@ -48,5 +53,15 @@ See Also * The command :command:`target_compile_options` adds target-specific options. +* This command adds compile options for all languages. + Use the :genex:`COMPILE_LANGUAGE` generator expression to specify + per-language compile options. + * The source file property :prop_sf:`COMPILE_OPTIONS` adds options to one source file. + +* :command:`add_link_options` adds options for linking. + +* :variable:`CMAKE__FLAGS` and :variable:`CMAKE__FLAGS_` + add language-wide flags passed to all invocations of the compiler. + This includes invocations that drive compiling and those that drive linking. diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index 293d3f01b..f1be3094d 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -25,7 +25,8 @@ The first signature is for adding a custom command to produce an output: [DEPFILE depfile] [JOB_POOL job_pool] [VERBATIM] [APPEND] [USES_TERMINAL] - [COMMAND_EXPAND_LISTS]) + [COMMAND_EXPAND_LISTS] + [DEPENDS_EXPLICIT_ONLY]) This defines a command to generate specified ``OUTPUT`` file(s). A target created in the same directory (``CMakeLists.txt`` file) @@ -357,6 +358,24 @@ The options are: :ref:`Makefile Generators`, :ref:`Visual Studio Generators`, and the :generator:`Xcode` generator. +``DEPENDS_EXPLICIT_ONLY`` + + .. versionadded:: 3.27 + + Indicate that the command's ``DEPENDS`` argument represents all files + required by the command and implicit dependencies are not required. + + Without this option, if any target uses the output of the custom command, + CMake will consider that target's dependencies as implicit dependencies for + the custom command in case this custom command requires files implicitly + created by those targets. + + This option can be enabled on all custom commands by setting + :variable:`CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY` to ``ON``. + + Only the :ref:`Ninja Generators` actually use this information to remove + unnecessary implicit dependencies. + Examples: Generating Files ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -459,7 +478,7 @@ target is already built, the command will not execute. [BYPRODUCTS [files...]] [WORKING_DIRECTORY dir] [COMMENT comment] - [VERBATIM] [USES_TERMINAL] + [VERBATIM] [COMMAND_EXPAND_LISTS]) This defines a new command that will be associated with building the @@ -470,9 +489,12 @@ When the command will happen is determined by which of the following is specified: ``PRE_BUILD`` - On :ref:`Visual Studio Generators`, run before any other rules are - executed within the target. - On other generators, run just before ``PRE_LINK`` commands. + This option has unique behavior for the :ref:`Visual Studio Generators`. + When using one of the Visual Studio generators, the command will run before + any other rules are executed within the target. With all other generators, + this option behaves the same as ``PRE_LINK`` instead. Because of this, + it is recommended to avoid using ``PRE_BUILD`` except when it is known that + a Visual Studio generator is being used. ``PRE_LINK`` Run after sources have been compiled but before linking the binary or running the librarian or archiver tool of a static library. diff --git a/Help/command/add_link_options.rst b/Help/command/add_link_options.rst index c09e10690..df7271543 100644 --- a/Help/command/add_link_options.rst +++ b/Help/command/add_link_options.rst @@ -38,3 +38,7 @@ See Also * :command:`link_libraries` * :command:`target_link_libraries` * :command:`target_link_options` + +* :variable:`CMAKE__FLAGS` and :variable:`CMAKE__FLAGS_` + add language-wide flags passed to all invocations of the compiler. + This includes invocations that drive compiling and those that drive linking. diff --git a/Help/command/add_test.rst b/Help/command/add_test.rst index 53555a4b0..02dd3986a 100644 --- a/Help/command/add_test.rst +++ b/Help/command/add_test.rst @@ -12,13 +12,24 @@ Add a test to the project to be run by :manual:`ctest(1)`. Adds a test called ````. The test name may contain arbitrary characters, expressed as a :ref:`Quoted Argument` or :ref:`Bracket Argument` -if necessary. See policy :policy:`CMP0110`. The options are: +if necessary. See policy :policy:`CMP0110`. + +CMake only generates tests if the :command:`enable_testing` command has been +invoked. The :module:`CTest` module invokes ``enable_testing`` automatically +unless ``BUILD_TESTING`` is set to ``OFF``. + +Tests added with the ``add_test(NAME)`` signature support using +:manual:`generator expressions ` +in test properties set by :command:`set_property(TEST)` or +:command:`set_tests_properties`. Test properties may only be set in the +directory the test is created in. + +``add_test`` options are: ``COMMAND`` - Specify the test command-line. If ```` specifies an - executable target (created by :command:`add_executable`) it will - automatically be replaced by the location of the executable created - at build time. + Specify the test command-line. If ```` specifies an executable + target created by :command:`add_executable`, it will automatically be + replaced by the location of the executable created at build time. The command may be specified using :manual:`generator expressions `. @@ -27,38 +38,29 @@ if necessary. See policy :policy:`CMP0110`. The options are: Restrict execution of the test only to the named configurations. ``WORKING_DIRECTORY`` - Set the :prop_test:`WORKING_DIRECTORY` test property to - specify the working directory in which to execute the test. - If not specified the test will be run with the current working - directory set to the build directory corresponding to the - current source directory. - - The working directory may be specified using - :manual:`generator expressions `. + Set the test property :prop_test:`WORKING_DIRECTORY` in which to execute the + test. If not specified, the test will be run in + :variable:`CMAKE_CURRENT_BINARY_DIR`. The working directory may be specified + using :manual:`generator expressions `. ``COMMAND_EXPAND_LISTS`` .. versionadded:: 3.16 - Lists in ``COMMAND`` arguments will be expanded, including those - created with + Lists in ``COMMAND`` arguments will be expanded, including those created with :manual:`generator expressions `. -The given test command is expected to exit with code ``0`` to pass and -non-zero to fail, or vice-versa if the :prop_test:`WILL_FAIL` test -property is set. Any output written to stdout or stderr will be -captured by :manual:`ctest(1)` but does not affect the pass/fail status -unless the :prop_test:`PASS_REGULAR_EXPRESSION`, -:prop_test:`FAIL_REGULAR_EXPRESSION` or -:prop_test:`SKIP_REGULAR_EXPRESSION` test property is used. +If the test command exits with code ``0`` the test passes. Non-zero exit code +is a "failed" test. The test property :prop_test:`WILL_FAIL` inverts this +logic. Note that system-level test failures such as segmentation faults or +heap errors will still fail the test even if ``WILL_FALL`` is true. Output +written to stdout or stderr is captured by :manual:`ctest(1)` and only +affects the pass/fail status via the :prop_test:`PASS_REGULAR_EXPRESSION`, +:prop_test:`FAIL_REGULAR_EXPRESSION`, or :prop_test:`SKIP_REGULAR_EXPRESSION` +test properties. .. versionadded:: 3.16 Added :prop_test:`SKIP_REGULAR_EXPRESSION` property. -Tests added with the ``add_test(NAME)`` signature support using -:manual:`generator expressions ` -in test properties set by :command:`set_property(TEST)` or -:command:`set_tests_properties`. - Example usage: .. code-block:: cmake @@ -71,16 +73,9 @@ This creates a test ``mytest`` whose command runs a ``testDriver`` tool passing the configuration name and the full path to the executable file produced by target ``myexe``. -.. note:: - - CMake will generate tests only if the :command:`enable_testing` - command has been invoked. The :module:`CTest` module invokes the - command automatically unless the ``BUILD_TESTING`` option is turned - ``OFF``. - --------------------------------------------------------------------- -This command also supports a simpler, but less flexible, signature: +The command syntax above is recommended over the older, less flexible form: .. code-block:: cmake diff --git a/Help/command/cmake_file_api.rst b/Help/command/cmake_file_api.rst new file mode 100644 index 000000000..e7ee7e7ad --- /dev/null +++ b/Help/command/cmake_file_api.rst @@ -0,0 +1,78 @@ +cmake_file_api +-------------- + +.. versionadded:: 3.27 + +Enables interacting with the :manual:`CMake file API `. + +.. signature:: + cmake_file_api(QUERY ...) + + The ``QUERY`` subcommand adds a file API query for the current CMake + invocation. + + .. code-block:: cmake + + cmake_file_api( + QUERY + API_VERSION + [CODEMODEL ...] + [CACHE ...] + [CMAKEFILES ...] + [TOOLCHAINS ...] + ) + + The ``API_VERSION`` must always be given. Currently, the only supported + value for ```` is 1. See :ref:`file-api v1` for details of the + reply content and location. + + Each of the optional keywords ``CODEMODEL``, ``CACHE``, ``CMAKEFILES`` and + ``TOOLCHAINS`` correspond to one of the object kinds that can be requested + by the project. The ``configureLog`` object kind cannot be set with this + command, since it must be set before CMake starts reading the top level + ``CMakeLists.txt`` file. + + For each of the optional keywords, the ```` list must contain one + or more version values of the form ``major`` or ``major.minor``, where + ``major`` and ``minor`` are integers. Projects should list the versions they + accept in their preferred order, as only the first supported value from the + list will be selected. The command will ignore versions with a ``major`` + version higher than any major version it supports for that object kind. + It will raise an error if it encounters an invalid version number, or if none + of the requested versions is supported. + + For each type of object kind requested, a query equivalent to a shared, + stateless query will be added internally. No query file will be created in + the file system. The reply *will* be written to the file system at + generation time. + + It is not an error to add a query for the same thing more than once, whether + from query files or from multiple calls to ``cmake_file_api(QUERY)``. + The final set of queries will be a merged combination of all queries + specified on disk and queries submitted by the project. + +Example +^^^^^^^ + +A project may want to use replies from the file API at build time to implement +some form of verification task. Instead of relying on something outside of +CMake to create a query file, the project can use ``cmake_file_api(QUERY)`` +to request the required information for the current run. It can then create +a custom command to run at build time, knowing that the requested information +should always be available. + +.. code-block:: cmake + + cmake_file_api( + QUERY + API_VERSION 1 + CODEMODEL 2.3 + TOOLCHAINS 1 + ) + + add_custom_target(verify_project + COMMAND ${CMAKE_COMMAND} + -D BUILD_DIR=${CMAKE_BINARY_DIR} + -D CONFIG=$ + -P ${CMAKE_CURRENT_SOURCE_DIR}/verify_project.cmake + ) diff --git a/Help/command/cmake_language.rst b/Help/command/cmake_language.rst index 8801a9fdf..707568cf7 100644 --- a/Help/command/cmake_language.rst +++ b/Help/command/cmake_language.rst @@ -27,163 +27,155 @@ those created via the :command:`macro` or :command:`function` commands. Calling Commands ^^^^^^^^^^^^^^^^ -.. _CALL: - -.. code-block:: cmake - +.. signature:: cmake_language(CALL [...]) -Calls the named ```` with the given arguments (if any). -For example, the code: + Calls the named ```` with the given arguments (if any). + For example, the code: -.. code-block:: cmake + .. code-block:: cmake - set(message_command "message") - cmake_language(CALL ${message_command} STATUS "Hello World!") + set(message_command "message") + cmake_language(CALL ${message_command} STATUS "Hello World!") -is equivalent to + is equivalent to -.. code-block:: cmake + .. code-block:: cmake - message(STATUS "Hello World!") + message(STATUS "Hello World!") -.. note:: - To ensure consistency of the code, the following commands are not allowed: + .. note:: + To ensure consistency of the code, the following commands are not allowed: - * ``if`` / ``elseif`` / ``else`` / ``endif`` - * ``block`` / ``endblock`` - * ``while`` / ``endwhile`` - * ``foreach`` / ``endforeach`` - * ``function`` / ``endfunction`` - * ``macro`` / ``endmacro`` + * ``if`` / ``elseif`` / ``else`` / ``endif`` + * ``block`` / ``endblock`` + * ``while`` / ``endwhile`` + * ``foreach`` / ``endforeach`` + * ``function`` / ``endfunction`` + * ``macro`` / ``endmacro`` Evaluating Code ^^^^^^^^^^^^^^^ -.. _EVAL: - -.. code-block:: cmake - +.. signature:: cmake_language(EVAL CODE ...) + :target: EVAL -Evaluates the ``...`` as CMake code. + Evaluates the ``...`` as CMake code. -For example, the code: + For example, the code: -.. code-block:: cmake + .. code-block:: cmake - set(A TRUE) - set(B TRUE) - set(C TRUE) - set(condition "(A AND B) OR C") + set(A TRUE) + set(B TRUE) + set(C TRUE) + set(condition "(A AND B) OR C") - cmake_language(EVAL CODE " - if (${condition}) - message(STATUS TRUE) - else() - message(STATUS FALSE) - endif()" - ) + cmake_language(EVAL CODE " + if (${condition}) + message(STATUS TRUE) + else() + message(STATUS FALSE) + endif()" + ) -is equivalent to + is equivalent to -.. code-block:: cmake + .. code-block:: cmake - set(A TRUE) - set(B TRUE) - set(C TRUE) - set(condition "(A AND B) OR C") - - file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake " - if (${condition}) - message(STATUS TRUE) - else() - message(STATUS FALSE) - endif()" - ) + set(A TRUE) + set(B TRUE) + set(C TRUE) + set(condition "(A AND B) OR C") - include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake) + file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake " + if (${condition}) + message(STATUS TRUE) + else() + message(STATUS FALSE) + endif()" + ) + + include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake) Deferring Calls ^^^^^^^^^^^^^^^ .. versionadded:: 3.19 -.. _DEFER: - -.. code-block:: cmake - +.. signature:: cmake_language(DEFER ... CALL [...]) -Schedules a call to the named ```` with the given arguments (if any) -to occur at a later time. By default, deferred calls are executed as if -written at the end of the current directory's ``CMakeLists.txt`` file, -except that they run even after a :command:`return` call. Variable -references in arguments are evaluated at the time the deferred call is -executed. + Schedules a call to the named ```` with the given arguments (if any) + to occur at a later time. By default, deferred calls are executed as if + written at the end of the current directory's ``CMakeLists.txt`` file, + except that they run even after a :command:`return` call. Variable + references in arguments are evaluated at the time the deferred call is + executed. -The options are: + The options are: -``DIRECTORY `` - Schedule the call for the end of the given directory instead of the - current directory. The ```` may reference either a source - directory or its corresponding binary directory. Relative paths are - treated as relative to the current source directory. + ``DIRECTORY `` + Schedule the call for the end of the given directory instead of the + current directory. The ```` may reference either a source + directory or its corresponding binary directory. Relative paths are + treated as relative to the current source directory. - The given directory must be known to CMake, being either the top-level - directory or one added by :command:`add_subdirectory`. Furthermore, - the given directory must not yet be finished processing. This means - it can be the current directory or one of its ancestors. + The given directory must be known to CMake, being either the top-level + directory or one added by :command:`add_subdirectory`. Furthermore, + the given directory must not yet be finished processing. This means + it can be the current directory or one of its ancestors. -``ID `` - Specify an identification for the deferred call. - The ```` may not be empty and may not begin with a capital letter ``A-Z``. - The ```` may begin with an underscore (``_``) only if it was generated - automatically by an earlier call that used ``ID_VAR`` to get the id. + ``ID `` + Specify an identification for the deferred call. + The ```` may not be empty and may not begin with a capital letter ``A-Z``. + The ```` may begin with an underscore (``_``) only if it was generated + automatically by an earlier call that used ``ID_VAR`` to get the id. -``ID_VAR `` - Specify a variable in which to store the identification for the - deferred call. If ``ID `` is not given, a new identification - will be generated and the generated id will start with an underscore (``_``). + ``ID_VAR `` + Specify a variable in which to store the identification for the + deferred call. If ``ID `` is not given, a new identification + will be generated and the generated id will start with an underscore (``_``). -The currently scheduled list of deferred calls may be retrieved: + The currently scheduled list of deferred calls may be retrieved: -.. code-block:: cmake + .. code-block:: cmake - cmake_language(DEFER [DIRECTORY ] GET_CALL_IDS ) + cmake_language(DEFER [DIRECTORY ] GET_CALL_IDS ) -This will store in ```` a :ref:`semicolon-separated list ` of deferred call ids. The ids are for the directory scope in which -the calls have been deferred to (i.e. where they will be executed), which can -be different to the scope in which they were created. The ``DIRECTORY`` -option can be used to specify the scope for which to retrieve the call ids. -If that option is not given, the call ids for the current directory scope will -be returned. + This will store in ```` a :ref:`semicolon-separated list ` of deferred call ids. The ids are for the directory scope in which + the calls have been deferred to (i.e. where they will be executed), which can + be different to the scope in which they were created. The ``DIRECTORY`` + option can be used to specify the scope for which to retrieve the call ids. + If that option is not given, the call ids for the current directory scope + will be returned. -Details of a specific call may be retrieved from its id: + Details of a specific call may be retrieved from its id: -.. code-block:: cmake + .. code-block:: cmake - cmake_language(DEFER [DIRECTORY ] GET_CALL ) + cmake_language(DEFER [DIRECTORY ] GET_CALL ) -This will store in ```` a :ref:`semicolon-separated list ` in which the first element is the name of the command to be -called, and the remaining elements are its unevaluated arguments (any -contained ``;`` characters are included literally and cannot be distinguished -from multiple arguments). If multiple calls are scheduled with the same id, -this retrieves the first one. If no call is scheduled with the given id in -the specified ``DIRECTORY`` scope (or the current directory scope if no -``DIRECTORY`` option is given), this stores an empty string in the variable. + This will store in ```` a :ref:`semicolon-separated list ` in which the first element is the name of the command to be + called, and the remaining elements are its unevaluated arguments (any + contained ``;`` characters are included literally and cannot be distinguished + from multiple arguments). If multiple calls are scheduled with the same id, + this retrieves the first one. If no call is scheduled with the given id in + the specified ``DIRECTORY`` scope (or the current directory scope if no + ``DIRECTORY`` option is given), this stores an empty string in the variable. -Deferred calls may be canceled by their id: + Deferred calls may be canceled by their id: -.. code-block:: cmake + .. code-block:: cmake - cmake_language(DEFER [DIRECTORY ] CANCEL_CALL ...) + cmake_language(DEFER [DIRECTORY ] CANCEL_CALL ...) -This cancels all deferred calls matching any of the given ids in the specified -``DIRECTORY`` scope (or the current directory scope if no ``DIRECTORY`` option -is given). Unknown ids are silently ignored. + This cancels all deferred calls matching any of the given ids in the specified + ``DIRECTORY`` scope (or the current directory scope if no ``DIRECTORY`` option + is given). Unknown ids are silently ignored. Deferred Call Examples """""""""""""""""""""" @@ -229,8 +221,6 @@ also prints:: Deferred Message 1 Deferred Message 2 - -.. _SET_DEPENDENCY_PROVIDER: .. _dependency_providers: Dependency Providers @@ -241,51 +231,50 @@ Dependency Providers .. note:: A high-level introduction to this feature can be found in the :ref:`Using Dependencies Guide `. -.. code-block:: cmake - +.. signature:: cmake_language(SET_DEPENDENCY_PROVIDER SUPPORTED_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 ```` specified when the provider -was set, CMake calls the provider's ```` 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 ```` -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 ```` must -already exist when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called. -As a special case, providing an empty string for the ```` and no -```` 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. + 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 ```` specified when the provider + was set, CMake calls the provider's ```` 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 ```` + 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 ```` must + already exist when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called. + As a special case, providing an empty string for the ```` and no + ```` 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 """"""""""""""""" @@ -499,23 +488,21 @@ Getting current message log level .. versionadded:: 3.25 -.. _GET_MESSAGE_LOG_LEVEL: .. _query_message_log_level: -.. code-block:: cmake - +.. signature:: cmake_language(GET_MESSAGE_LOG_LEVEL ) -Writes the current :command:`message` logging level -into the given ````. + Writes the current :command:`message` logging level + into the given ````. -See :command:`message` for the possible logging levels. + See :command:`message` for the possible logging levels. -The current message logging level can be set either using the -:option:`--log-level ` -command line option of the :manual:`cmake(1)` program or using -the :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable. + The current message logging level can be set either using the + :option:`--log-level ` + command line option of the :manual:`cmake(1)` program or using + the :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable. -If both the command line option and the variable are set, the command line -option takes precedence. If neither are set, the default logging level -is returned. + If both the command line option and the variable are set, the command line + option takes precedence. If neither are set, the default logging level + is returned. diff --git a/Help/command/configure_file.rst b/Help/command/configure_file.rst index 6f4cedfa6..07dc2e159 100644 --- a/Help/command/configure_file.rst +++ b/Help/command/configure_file.rst @@ -12,10 +12,10 @@ Copy a file to another location and modify its contents. [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ]) Copies an ```` file to an ```` file and substitutes -variable values referenced as ``@VAR@`` or ``${VAR}`` in the input -file content. Each variable reference will be replaced with the -current value of the variable, or the empty string if the variable -is not defined. Furthermore, input lines of the form +variable values referenced as ``@VAR@``, ``${VAR}``, ``$CACHE{VAR}`` or +``$ENV{VAR}`` in the input file content. Each variable reference will be +replaced with the current value of the variable, or the empty string if +the variable is not defined. Furthermore, input lines of the form .. code-block:: c diff --git a/Help/command/enable_language.rst b/Help/command/enable_language.rst index 21b38bade..2f1cc2355 100644 --- a/Help/command/enable_language.rst +++ b/Help/command/enable_language.rst @@ -13,10 +13,6 @@ variables that are created by the project command. .. include:: SUPPORTED_LANGUAGES.txt -By default ``C`` and ``CXX`` are enabled if no language options are given. -Specify language ``NONE``, or use the ``LANGUAGES`` keyword and list no languages, -to skip enabling any languages. - This command must be called in file scope, not in a function call. Furthermore, it must be called in the highest directory common to all targets using the named language directly for compiling sources or diff --git a/Help/command/file.rst b/Help/command/file.rst index df895d080..30a7f4de7 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -26,7 +26,7 @@ Synopsis `Reading`_ file(`READ`_ [...]) file(`STRINGS`_ [...]) - file(`\ `_ ) + file(`\`_ ) file(`TIMESTAMP`_ [...]) file(`GET_RUNTIME_DEPENDENCIES`_ [...]) @@ -68,1202 +68,1184 @@ Synopsis Reading ^^^^^^^ -.. _READ: - -.. code-block:: cmake - +.. signature:: file(READ [OFFSET ] [LIMIT ] [HEX]) -Read content from a file called ```` and store it in a -````. Optionally start from the given ```` and -read at most ```` bytes. The ``HEX`` option causes data to -be converted to a hexadecimal representation (useful for binary data). If the -``HEX`` option is specified, letters in the output (``a`` through ``f``) are in -lowercase. - -.. _STRINGS: - -.. code-block:: cmake + Read content from a file called ```` and store it in a + ````. Optionally start from the given ```` and + read at most ```` bytes. The ``HEX`` option causes data to + be converted to a hexadecimal representation (useful for binary data). + If the ``HEX`` option is specified, letters in the output + (``a`` through ``f``) are in lowercase. +.. signature:: file(STRINGS [...]) -Parse a list of ASCII strings from ```` and store it in -````. Binary data in the file are ignored. Carriage return -(``\r``, CR) characters are ignored. The options are: - -``LENGTH_MAXIMUM `` - Consider only strings of at most a given length. + Parse a list of ASCII strings from ```` and store it in + ````. Binary data in the file are ignored. Carriage return + (``\r``, CR) characters are ignored. The options are: -``LENGTH_MINIMUM `` - Consider only strings of at least a given length. + ``LENGTH_MAXIMUM `` + Consider only strings of at most a given length. -``LIMIT_COUNT `` - Limit the number of distinct strings to be extracted. + ``LENGTH_MINIMUM `` + Consider only strings of at least a given length. -``LIMIT_INPUT `` - Limit the number of input bytes to read from the file. + ``LIMIT_COUNT `` + Limit the number of distinct strings to be extracted. -``LIMIT_OUTPUT `` - Limit the number of total bytes to store in the ````. + ``LIMIT_INPUT `` + Limit the number of input bytes to read from the file. -``NEWLINE_CONSUME`` - Treat newline characters (``\n``, LF) as part of string content - instead of terminating at them. + ``LIMIT_OUTPUT `` + Limit the number of total bytes to store in the ````. -``NO_HEX_CONVERSION`` - Intel Hex and Motorola S-record files are automatically converted to - binary while reading unless this option is given. + ``NEWLINE_CONSUME`` + Treat newline characters (``\n``, LF) as part of string content + instead of terminating at them. -``REGEX `` - Consider only strings that match the given regular expression, - as described under :ref:`string(REGEX) `. + ``NO_HEX_CONVERSION`` + Intel Hex and Motorola S-record files are automatically converted to + binary while reading unless this option is given. -``ENCODING `` - .. versionadded:: 3.1 + ``REGEX `` + Consider only strings that match the given regular expression, + as described under :ref:`string(REGEX) `. - Consider strings of a given encoding. Currently supported encodings are: - ``UTF-8``, ``UTF-16LE``, ``UTF-16BE``, ``UTF-32LE``, ``UTF-32BE``. - If the ``ENCODING`` option is not provided and the file has a Byte Order Mark, - the ``ENCODING`` option will be defaulted to respect the Byte Order Mark. + ``ENCODING `` + .. versionadded:: 3.1 - .. versionadded:: 3.2 - Added the ``UTF-16LE``, ``UTF-16BE``, ``UTF-32LE``, ``UTF-32BE`` encodings. + Consider strings of a given encoding. Currently supported encodings are: + ``UTF-8``, ``UTF-16LE``, ``UTF-16BE``, ``UTF-32LE``, ``UTF-32BE``. + If the ``ENCODING`` option is not provided and the file + has a Byte Order Mark, the ``ENCODING`` option will be defaulted + to respect the Byte Order Mark. -For example, the code + .. versionadded:: 3.2 + Added the ``UTF-16LE``, ``UTF-16BE``, ``UTF-32LE``, ``UTF-32BE`` encodings. -.. code-block:: cmake + For example, the code - file(STRINGS myfile.txt myfile) + .. code-block:: cmake -stores a list in the variable ``myfile`` in which each item is a line -from the input file. + file(STRINGS myfile.txt myfile) -.. _HASH: - -.. code-block:: cmake + stores a list in the variable ``myfile`` in which each item is a line + from the input file. +.. signature:: file( ) + :target: -Compute a cryptographic hash of the content of ```` and -store it in a ````. The supported ```` algorithm names -are those listed by the :ref:`string(\) ` -command. - -.. _TIMESTAMP: - -.. code-block:: cmake + Compute a cryptographic hash of the content of ```` and + store it in a ````. The supported ```` algorithm names + are those listed by the :command:`string()` command. +.. signature:: file(TIMESTAMP [] [UTC]) -Compute a string representation of the modification time of ```` -and store it in ````. Should the command be unable to obtain a -timestamp variable will be set to the empty string (""). - -See the :command:`string(TIMESTAMP)` command for documentation of -the ```` and ``UTC`` options. + Compute a string representation of the modification time of ```` + and store it in ````. Should the command be unable to obtain a + timestamp variable will be set to the empty string (""). -.. _GET_RUNTIME_DEPENDENCIES: + See the :command:`string(TIMESTAMP)` command for documentation of + the ```` and ``UTC`` options. -.. code-block:: cmake +.. signature:: + file(GET_RUNTIME_DEPENDENCIES [...]) - file(GET_RUNTIME_DEPENDENCIES - [RESOLVED_DEPENDENCIES_VAR ] - [UNRESOLVED_DEPENDENCIES_VAR ] - [CONFLICTING_DEPENDENCIES_PREFIX ] - [EXECUTABLES [...]] - [LIBRARIES [...]] - [MODULES [...]] - [DIRECTORIES [...]] - [BUNDLE_EXECUTABLE ] - [PRE_INCLUDE_REGEXES [...]] - [PRE_EXCLUDE_REGEXES [...]] - [POST_INCLUDE_REGEXES [...]] - [POST_EXCLUDE_REGEXES [...]] - [POST_INCLUDE_FILES [...]] - [POST_EXCLUDE_FILES [...]] - ) + .. versionadded:: 3.16 -.. versionadded:: 3.16 + Recursively get the list of libraries depended on by the given files: -Recursively get the list of libraries depended on by the given files. + .. code-block:: cmake -Please note that this sub-command is not intended to be used in project mode. -It is intended for use at install time, either from code generated by the -:command:`install(RUNTIME_DEPENDENCY_SET)` command, or from code provided by -the project via :command:`install(CODE)` or :command:`install(SCRIPT)`. -For example: - -.. code-block:: cmake - - install(CODE [[ file(GET_RUNTIME_DEPENDENCIES - # ... + [RESOLVED_DEPENDENCIES_VAR ] + [UNRESOLVED_DEPENDENCIES_VAR ] + [CONFLICTING_DEPENDENCIES_PREFIX ] + [EXECUTABLES [...]] + [LIBRARIES [...]] + [MODULES [...]] + [DIRECTORIES [...]] + [BUNDLE_EXECUTABLE ] + [PRE_INCLUDE_REGEXES [...]] + [PRE_EXCLUDE_REGEXES [...]] + [POST_INCLUDE_REGEXES [...]] + [POST_EXCLUDE_REGEXES [...]] + [POST_INCLUDE_FILES [...]] + [POST_EXCLUDE_FILES [...]] ) - ]]) - -The arguments are as follows: - -``RESOLVED_DEPENDENCIES_VAR `` - Name of the variable in which to store the list of resolved dependencies. - -``UNRESOLVED_DEPENDENCIES_VAR `` - Name of the variable in which to store the list of unresolved dependencies. - If this variable is not specified, and there are any unresolved dependencies, - an error is issued. - -``CONFLICTING_DEPENDENCIES_PREFIX `` - Variable prefix in which to store conflicting dependency information. - Dependencies are conflicting if two files with the same name are found in - two different directories. The list of filenames that conflict are stored in - ``_FILENAMES``. For each filename, the list of paths - that were found for that filename are stored in - ``_``. - -``EXECUTABLES `` - List of executable files to read for dependencies. These are executables that - are typically created with :command:`add_executable`, but they do not have to - be created by CMake. On Apple platforms, the paths to these files determine - the value of ``@executable_path`` when recursively resolving the libraries. - Specifying any kind of library (``STATIC``, ``MODULE``, or ``SHARED``) here - will result in undefined behavior. - -``LIBRARIES `` - List of library files to read for dependencies. These are libraries that are - typically created with :command:`add_library(SHARED)`, but they do not have - to be created by CMake. Specifying ``STATIC`` libraries, ``MODULE`` - libraries, or executables here will result in undefined behavior. - -``MODULES `` - List of loadable module files to read for dependencies. These are modules - that are typically created with :command:`add_library(MODULE)`, but they do - not have to be created by CMake. They are typically used by calling - ``dlopen()`` at runtime rather than linked at link time with ``ld -l``. - Specifying ``STATIC`` libraries, ``SHARED`` libraries, or executables here - will result in undefined behavior. - -``DIRECTORIES `` - List of additional directories to search for dependencies. On Linux - platforms, these directories are searched if the dependency is not found in - any of the other usual paths. If it is found in such a directory, a warning - is issued, because it means that the file is incomplete (it does not list all - of the directories that contain its dependencies). On Windows platforms, - these directories are searched if the dependency is not found in any of the - other search paths, but no warning is issued, because searching other paths - is a normal part of Windows dependency resolution. On Apple platforms, this - argument has no effect. - -``BUNDLE_EXECUTABLE `` - Executable to treat as the "bundle executable" when resolving libraries. On - Apple platforms, this argument determines the value of ``@executable_path`` - when recursively resolving libraries for ``LIBRARIES`` and ``MODULES`` files. - It has no effect on ``EXECUTABLES`` files. On other platforms, it has no - effect. This is typically (but not always) one of the executables in the - ``EXECUTABLES`` argument which designates the "main" executable of the - package. - -The following arguments specify filters for including or excluding libraries to -be resolved. See below for a full description of how they work. - -``PRE_INCLUDE_REGEXES `` - List of pre-include regexes through which to filter the names of - not-yet-resolved dependencies. - -``PRE_EXCLUDE_REGEXES `` - List of pre-exclude regexes through which to filter the names of - not-yet-resolved dependencies. - -``POST_INCLUDE_REGEXES `` - List of post-include regexes through which to filter the names of resolved - dependencies. - -``POST_EXCLUDE_REGEXES `` - List of post-exclude regexes through which to filter the names of resolved - dependencies. - -``POST_INCLUDE_FILES `` - .. versionadded:: 3.21 - - List of post-include filenames through which to filter the names of resolved - dependencies. Symlinks are resolved when attempting to match these filenames. - -``POST_EXCLUDE_FILES `` - .. versionadded:: 3.21 - - List of post-exclude filenames through which to filter the names of resolved - dependencies. Symlinks are resolved when attempting to match these filenames. - -These arguments can be used to exclude unwanted system libraries when -resolving the dependencies, or to include libraries from a specific -directory. The filtering works as follows: - -1. If the not-yet-resolved dependency matches any of the - ``PRE_INCLUDE_REGEXES``, steps 2 and 3 are skipped, and the dependency - resolution proceeds to step 4. -2. If the not-yet-resolved dependency matches any of the - ``PRE_EXCLUDE_REGEXES``, dependency resolution stops for that dependency. -3. Otherwise, dependency resolution proceeds. -4. ``file(GET_RUNTIME_DEPENDENCIES)`` searches for the dependency according to - the linking rules of the platform (see below). -5. If the dependency is found, and its full path matches one of the - ``POST_INCLUDE_REGEXES`` or ``POST_INCLUDE_FILES``, the full path is added - to the resolved dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` - recursively resolves that library's own dependencies. Otherwise, resolution - proceeds to step 6. -6. If the dependency is found, but its full path matches one of the - ``POST_EXCLUDE_REGEXES`` or ``POST_EXCLUDE_FILES``, it is not added to the - resolved dependencies, and dependency resolution stops for that dependency. -7. If the dependency is found, and its full path does not match either - ``POST_INCLUDE_REGEXES``, ``POST_INCLUDE_FILES``, ``POST_EXCLUDE_REGEXES``, - or ``POST_EXCLUDE_FILES``, the full path is added to the resolved - dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` recursively resolves - that library's own dependencies. - -Different platforms have different rules for how dependencies are resolved. -These specifics are described here. - -On Linux platforms, library resolution works as follows: - -1. If the depending file does not have any ``RUNPATH`` entries, and the library - exists in one of the depending file's ``RPATH`` entries, or its parents', in - that order, the dependency is resolved to that file. -2. Otherwise, if the depending file has any ``RUNPATH`` entries, and the - library exists in one of those entries, the dependency is resolved to that - file. -3. Otherwise, if the library exists in one of the directories listed by - ``ldconfig``, the dependency is resolved to that file. -4. Otherwise, if the library exists in one of the ``DIRECTORIES`` entries, the - dependency is resolved to that file. In this case, a warning is issued, - because finding a file in one of the ``DIRECTORIES`` means that the - depending file is not complete (it does not list all the directories from - which it pulls dependencies). -5. Otherwise, the dependency is unresolved. - -On Windows platforms, library resolution works as follows: - -1. The dependent DLL name is converted to lowercase. Windows DLL names are - case-insensitive, and some linkers mangle the case of the DLL dependency - names. However, this makes it more difficult for ``PRE_INCLUDE_REGEXES``, - ``PRE_EXCLUDE_REGEXES``, ``POST_INCLUDE_REGEXES``, and - ``POST_EXCLUDE_REGEXES`` to properly filter DLL names - every regex would - have to check for both uppercase and lowercase letters. For example: - - .. code-block:: cmake - - file(GET_RUNTIME_DEPENDENCIES - # ... - PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$" - ) - - Converting the DLL name to lowercase allows the regexes to only match - lowercase names, thus simplifying the regex. For example: - - .. code-block:: cmake - - file(GET_RUNTIME_DEPENDENCIES - # ... - PRE_INCLUDE_REGEXES "^mylibrary\\.dll$" - ) - - This regex will match ``mylibrary.dll`` regardless of how it is cased, - either on disk or in the depending file. (For example, it will match - ``mylibrary.dll``, ``MyLibrary.dll``, and ``MYLIBRARY.DLL``.) - - Please note that the directory portion of any resolved DLLs retains its - casing and is not converted to lowercase. Only the filename portion is - converted. - -2. (**Not yet implemented**) If the depending file is a Windows Store app, and - the dependency is listed as a dependency in the application's package - manifest, the dependency is resolved to that file. -3. Otherwise, if the library exists in the same directory as the depending - file, the dependency is resolved to that file. -4. Otherwise, if the library exists in either the operating system's - ``system32`` directory or the ``Windows`` directory, in that order, the - dependency is resolved to that file. -5. Otherwise, if the library exists in one of the directories specified by - ``DIRECTORIES``, in the order they are listed, the dependency is resolved to - that file. In this case, a warning is not issued, because searching other - directories is a normal part of Windows library resolution. -6. Otherwise, the dependency is unresolved. - -On Apple platforms, library resolution works as follows: - -1. If the dependency starts with ``@executable_path/``, and an ``EXECUTABLES`` - argument is in the process of being resolved, and replacing - ``@executable_path/`` with the directory of the executable yields an - existing file, the dependency is resolved to that file. -2. Otherwise, if the dependency starts with ``@executable_path/``, and there is - a ``BUNDLE_EXECUTABLE`` argument, and replacing ``@executable_path/`` with - the directory of the bundle executable yields an existing file, the - dependency is resolved to that file. -3. Otherwise, if the dependency starts with ``@loader_path/``, and replacing - ``@loader_path/`` with the directory of the depending file yields an - existing file, the dependency is resolved to that file. -4. Otherwise, if the dependency starts with ``@rpath/``, and replacing - ``@rpath/`` with one of the ``RPATH`` entries of the depending file yields - an existing file, the dependency is resolved to that file. Note that - ``RPATH`` entries that start with ``@executable_path/`` or ``@loader_path/`` - also have these items replaced with the appropriate path. -5. Otherwise, if the dependency is an absolute file that exists, the dependency - is resolved to that file. -6. Otherwise, the dependency is unresolved. - -This function accepts several variables that determine which tool is used for -dependency resolution: - -.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM - - Determines which operating system and executable format the files are built - for. This could be one of several values: - - * ``linux+elf`` - * ``windows+pe`` - * ``macos+macho`` - - If this variable is not specified, it is determined automatically by system - introspection. - -.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL - - Determines the tool to use for dependency resolution. It could be one of - several values, depending on the value of - :variable:`CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`: - - ================================================= ============================================= - ``CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`` ``CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL`` - ================================================= ============================================= - ``linux+elf`` ``objdump`` - ``windows+pe`` ``dumpbin`` - ``windows+pe`` ``objdump`` - ``macos+macho`` ``otool`` - ================================================= ============================================= - - If this variable is not specified, it is determined automatically by system - introspection. - -.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND - - Determines the path to the tool to use for dependency resolution. This is the - actual path to ``objdump``, ``dumpbin``, or ``otool``. - - If this variable is not specified, it is determined by the value of - ``CMAKE_OBJDUMP`` if set, else by system introspection. - - .. versionadded:: 3.18 - Use ``CMAKE_OBJDUMP`` if set. - -Writing -^^^^^^^ - -.. _WRITE: -.. _APPEND: - -.. code-block:: cmake - - file(WRITE ...) - file(APPEND ...) - -Write ```` into a file called ````. If the file does -not exist, it will be created. If the file already exists, ``WRITE`` -mode will overwrite it and ``APPEND`` mode will append to the end. -Any directories in the path specified by ```` that do not -exist will be created. - -If the file is a build input, use the :command:`configure_file` command -to update the file only when its content changes. - -.. _TOUCH: -.. _TOUCH_NOCREATE: - -.. code-block:: cmake - - file(TOUCH [...]) - file(TOUCH_NOCREATE [...]) - -.. versionadded:: 3.12 -Create a file with no content if it does not yet exist. If the file already -exists, its access and/or modification will be updated to the time when the -function call is executed. + Please note that this sub-command is not intended to be used in project mode. + It is intended for use at install time, either from code generated by the + :command:`install(RUNTIME_DEPENDENCY_SET)` command, or from code provided by + the project via :command:`install(CODE)` or :command:`install(SCRIPT)`. + For example: + + .. code-block:: cmake + + install(CODE [[ + file(GET_RUNTIME_DEPENDENCIES + # ... + ) + ]]) + + The arguments are as follows: + + ``RESOLVED_DEPENDENCIES_VAR `` + Name of the variable in which to store the list of resolved dependencies. + + ``UNRESOLVED_DEPENDENCIES_VAR `` + Name of the variable in which to store the list of unresolved + dependencies. If this variable is not specified, and there are any + unresolved dependencies, an error is issued. + + ``CONFLICTING_DEPENDENCIES_PREFIX `` + Variable prefix in which to store conflicting dependency information. + Dependencies are conflicting if two files with the same name are found in + two different directories. The list of filenames that conflict are stored + in ``_FILENAMES``. For each filename, the list + of paths that were found for that filename are stored in + ``_``. + + ``EXECUTABLES `` + List of executable files to read for dependencies. These are executables + that are typically created with :command:`add_executable`, but they do + not have to be created by CMake. On Apple platforms, the paths to these + files determine the value of ``@executable_path`` when recursively + resolving the libraries. Specifying any kind of library (``STATIC``, + ``MODULE``, or ``SHARED``) here will result in undefined behavior. + + ``LIBRARIES `` + List of library files to read for dependencies. These are libraries that + are typically created with :command:`add_library(SHARED)`, but they do + not have to be created by CMake. Specifying ``STATIC`` libraries, + ``MODULE`` libraries, or executables here will result in undefined + behavior. + + ``MODULES `` + List of loadable module files to read for dependencies. These are modules + that are typically created with :command:`add_library(MODULE)`, but they + do not have to be created by CMake. They are typically used by calling + ``dlopen()`` at runtime rather than linked at link time with ``ld -l``. + Specifying ``STATIC`` libraries, ``SHARED`` libraries, or executables + here will result in undefined behavior. + + ``DIRECTORIES `` + List of additional directories to search for dependencies. On Linux + platforms, these directories are searched if the dependency is not found + in any of the other usual paths. If it is found in such a directory, a + warning is issued, because it means that the file is incomplete (it does + not list all of the directories that contain its dependencies). + On Windows platforms, these directories are searched if the dependency + is not found in any of the other search paths, but no warning is issued, + because searching other paths is a normal part of Windows dependency + resolution. On Apple platforms, this argument has no effect. + + ``BUNDLE_EXECUTABLE `` + Executable to treat as the "bundle executable" when resolving libraries. + On Apple platforms, this argument determines the value of + ``@executable_path`` when recursively resolving libraries for + ``LIBRARIES`` and ``MODULES`` files. It has no effect on ``EXECUTABLES`` + files. On other platforms, it has no effect. This is typically (but not + always) one of the executables in the ``EXECUTABLES`` argument which + designates the "main" executable of the package. + + The following arguments specify filters for including or excluding libraries + to be resolved. See below for a full description of how they work. + + ``PRE_INCLUDE_REGEXES `` + List of pre-include regexes through which to filter the names of + not-yet-resolved dependencies. + + ``PRE_EXCLUDE_REGEXES `` + List of pre-exclude regexes through which to filter the names of + not-yet-resolved dependencies. + + ``POST_INCLUDE_REGEXES `` + List of post-include regexes through which to filter the names of + resolved dependencies. + + ``POST_EXCLUDE_REGEXES `` + List of post-exclude regexes through which to filter the names of + resolved dependencies. + + ``POST_INCLUDE_FILES `` + .. versionadded:: 3.21 + + List of post-include filenames through which to filter the names of + resolved dependencies. Symlinks are resolved when attempting to match + these filenames. + + ``POST_EXCLUDE_FILES `` + .. versionadded:: 3.21 + + List of post-exclude filenames through which to filter the names of + resolved dependencies. Symlinks are resolved when attempting to match + these filenames. + + These arguments can be used to exclude unwanted system libraries when + resolving the dependencies, or to include libraries from a specific + directory. The filtering works as follows: + + 1. If the not-yet-resolved dependency matches any of the + ``PRE_INCLUDE_REGEXES``, steps 2 and 3 are skipped, and the dependency + resolution proceeds to step 4. + + 2. If the not-yet-resolved dependency matches any of the + ``PRE_EXCLUDE_REGEXES``, dependency resolution stops for that dependency. + + 3. Otherwise, dependency resolution proceeds. + + 4. ``file(GET_RUNTIME_DEPENDENCIES)`` searches for the dependency according + to the linking rules of the platform (see below). + + 5. If the dependency is found, and its full path matches one of the + ``POST_INCLUDE_REGEXES`` or ``POST_INCLUDE_FILES``, the full path is added + to the resolved dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` + recursively resolves that library's own dependencies. Otherwise, resolution + proceeds to step 6. + + 6. If the dependency is found, but its full path matches one of the + ``POST_EXCLUDE_REGEXES`` or ``POST_EXCLUDE_FILES``, it is not added to the + resolved dependencies, and dependency resolution stops for that dependency. + + 7. If the dependency is found, and its full path does not match either + ``POST_INCLUDE_REGEXES``, ``POST_INCLUDE_FILES``, ``POST_EXCLUDE_REGEXES``, + or ``POST_EXCLUDE_FILES``, the full path is added to the resolved + dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` recursively resolves + that library's own dependencies. + + Different platforms have different rules for how dependencies are resolved. + These specifics are described here. + + On Linux platforms, library resolution works as follows: + + 1. If the depending file does not have any ``RUNPATH`` entries, and the + library exists in one of the depending file's ``RPATH`` entries, or its + parents', in that order, the dependency is resolved to that file. + 2. Otherwise, if the depending file has any ``RUNPATH`` entries, and the + library exists in one of those entries, the dependency is resolved to that + file. + 3. Otherwise, if the library exists in one of the directories listed by + ``ldconfig``, the dependency is resolved to that file. + 4. Otherwise, if the library exists in one of the ``DIRECTORIES`` entries, + the dependency is resolved to that file. In this case, a warning is + issued, because finding a file in one of the ``DIRECTORIES`` means that + the depending file is not complete (it does not list all the directories + from which it pulls dependencies). + + 5. Otherwise, the dependency is unresolved. -Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a file -does not exist it will be silently ignored. + On Windows platforms, library resolution works as follows: -With TOUCH and TOUCH_NOCREATE the contents of an existing file will not be -modified. + 1. DLL dependency names are converted to lowercase for matching filters. + Windows DLL names are case-insensitive, and some linkers mangle the + case of the DLL dependency names. However, this makes it more difficult + for ``PRE_INCLUDE_REGEXES``, ``PRE_EXCLUDE_REGEXES``, + ``POST_INCLUDE_REGEXES``, and ``POST_EXCLUDE_REGEXES`` to properly + filter DLL names - every regex would have to check for both uppercase + and lowercase letters. For example: -.. _GENERATE: + .. code-block:: cmake -.. code-block:: cmake + file(GET_RUNTIME_DEPENDENCIES + # ... + PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$" + ) - file(GENERATE OUTPUT output-file - - [CONDITION expression] [TARGET target] - [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS | - FILE_PERMISSIONS ...] - [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ]) - -Generate an output file for each build configuration supported by the current -:manual:`CMake Generator `. Evaluate -:manual:`generator expressions ` -from the input content to produce the output content. The options are: + Converting the DLL name to lowercase allows the regexes to only match + lowercase names, thus simplifying the regex. For example: -``CONDITION `` - Generate the output file for a particular configuration only if - the condition is true. The condition must be either ``0`` or ``1`` - after evaluating generator expressions. + .. code-block:: cmake -``CONTENT `` - Use the content given explicitly as input. + file(GET_RUNTIME_DEPENDENCIES + # ... + PRE_INCLUDE_REGEXES "^mylibrary\\.dll$" + ) -``INPUT `` - Use the content from a given file as input. + This regex will match ``mylibrary.dll`` regardless of how it is cased, + either on disk or in the depending file. (For example, it will match + ``mylibrary.dll``, ``MyLibrary.dll``, and ``MYLIBRARY.DLL``.) - .. versionchanged:: 3.10 - A relative path is treated with respect to the value of - :variable:`CMAKE_CURRENT_SOURCE_DIR`. See policy :policy:`CMP0070`. + .. versionchanged:: 3.27 -``OUTPUT `` - Specify the output file name to generate. Use generator expressions - such as :genex:`$` to specify a configuration-specific - output file name. Multiple configurations may generate the same output - file only if the generated content is identical. Otherwise, the - ```` must evaluate to an unique name for each configuration. + The conversion to lowercase only applies while matching filters. + Results reported after filtering case-preserve each DLL name as it is + found on disk, if resolved, and otherwise as it is referenced by the + dependent binary. - .. versionchanged:: 3.10 - A relative path (after evaluating generator expressions) is treated - with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. - See policy :policy:`CMP0070`. + Prior to CMake 3.27, the results were reported with lowercase DLL + file names, but the directory portion retained its casing. -``TARGET `` - .. versionadded:: 3.19 + 2. (**Not yet implemented**) If the depending file is a Windows Store app, + and the dependency is listed as a dependency in the application's package + manifest, the dependency is resolved to that file. - Specify which target to use when evaluating generator expressions that - require a target for evaluation (e.g. - :genex:`$`, - :genex:`$`). + 3. Otherwise, if the library exists in the same directory as the depending + file, the dependency is resolved to that file. -``NO_SOURCE_PERMISSIONS`` - .. versionadded:: 3.20 + 4. Otherwise, if the library exists in either the operating system's + ``system32`` directory or the ``Windows`` directory, in that order, the + dependency is resolved to that file. - The generated file permissions default to the standard 644 value - (-rw-r--r--). + 5. Otherwise, if the library exists in one of the directories specified by + ``DIRECTORIES``, in the order they are listed, the dependency is resolved + to that file. In this case, a warning is not issued, because searching + other directories is a normal part of Windows library resolution. -``USE_SOURCE_PERMISSIONS`` - .. versionadded:: 3.20 + 6. Otherwise, the dependency is unresolved. - Transfer the file permissions of the ``INPUT`` file to the generated file. - This is already the default behavior if none of the three permissions-related - keywords are given (``NO_SOURCE_PERMISSIONS``, ``USE_SOURCE_PERMISSIONS`` - or ``FILE_PERMISSIONS``). The ``USE_SOURCE_PERMISSIONS`` keyword mostly - serves as a way of making the intended behavior clearer at the call site. - It is an error to specify this option without ``INPUT``. + On Apple platforms, library resolution works as follows: -``FILE_PERMISSIONS ...`` - .. versionadded:: 3.20 + 1. If the dependency starts with ``@executable_path/``, and an + ``EXECUTABLES`` argument is in the process of being resolved, and + replacing ``@executable_path/`` with the directory of the executable + yields an existing file, the dependency is resolved to that file. - Use the specified permissions for the generated file. + 2. Otherwise, if the dependency starts with ``@executable_path/``, and there + is a ``BUNDLE_EXECUTABLE`` argument, and replacing ``@executable_path/`` + with the directory of the bundle executable yields an existing file, the + dependency is resolved to that file. -``NEWLINE_STYLE