diff --git a/.clang-tidy b/.clang-tidy index 03e6a5111..6d2edd4f7 100644 --- a/.clang-tidy +++ b/.clang-tidy @@ -5,12 +5,16 @@ bugprone-*,\ -bugprone-easily-swappable-parameters,\ -bugprone-empty-catch,\ -bugprone-implicit-widening-of-multiplication-result,\ +-bugprone-inc-dec-in-conditions,\ -bugprone-macro-parentheses,\ -bugprone-misplaced-widening-cast,\ +-bugprone-multi-level-implicit-pointer-conversion,\ -bugprone-narrowing-conversions,\ -bugprone-switch-missing-default-case,\ -bugprone-too-small-loop-variable,\ -bugprone-unchecked-optional-access,\ +-bugprone-unused-local-non-trivial-variable,\ +-bugprone-unused-return-value,\ misc-*,\ -misc-confusable-identifiers,\ -misc-const-correctness,\ @@ -31,9 +35,12 @@ modernize-*,\ -modernize-use-transparent-functors,\ performance-*,\ -performance-avoid-endl,\ +-performance-enum-size,\ -performance-inefficient-vector-operation,\ -performance-noexcept-swap,\ readability-*,\ +-readability-avoid-nested-conditional-operator,\ +-readability-avoid-return-with-void-value,\ -readability-avoid-unconditional-preprocessor-if,\ -readability-convert-member-functions-to-static,\ -readability-function-cognitive-complexity,\ @@ -45,8 +52,11 @@ readability-*,\ -readability-magic-numbers,\ -readability-make-member-function-const,\ -readability-named-parameter,\ +-readability-redundant-casting,\ -readability-redundant-declaration,\ +-readability-redundant-inline-specifier,\ -readability-redundant-member-init,\ +-readability-reference-to-constructed-temporary,\ -readability-simplify-boolean-expr,\ -readability-static-accessed-through-instance,\ -readability-suspicious-call-argument,\ diff --git a/Auxiliary/bash-completion/cmake b/Auxiliary/bash-completion/cmake index bed7248f7..803e09e4b 100644 --- a/Auxiliary/bash-completion/cmake +++ b/Auxiliary/bash-completion/cmake @@ -2,14 +2,22 @@ _cmake() { - local cur prev words cword split=false - if type -t _init_completion >/dev/null; then - _init_completion -n = || return + local is_old_completion=false + local is_init_completion=false + + local cur prev words cword split was_split + if type -t _comp_initialize >/dev/null; then + _comp_initialize -s || return + elif type -t _init_completion >/dev/null; then + _init_completion -s || return + is_init_completion=true else # manual initialization for older bash completion versions COMPREPLY=() cur="${COMP_WORDS[COMP_CWORD]}" prev="${COMP_WORDS[COMP_CWORD-1]}" + is_old_completion=true + split=false fi # Workaround for options like -DCMAKE_BUILD_TYPE=Release @@ -89,7 +97,9 @@ _cmake() ;; esac - _split_longopt && split=true + if $is_old_completion; then + _split_longopt && split=true + fi case "$prev" in -C|-P|--graphviz|--system-information) @@ -187,7 +197,11 @@ _cmake() ;; esac - $split && return + if ($is_old_completion || $is_init_completion); then + $split && return + else + [[ $was_split ]] && return + fi if [[ "$cur" == -* ]]; then COMPREPLY=( $(compgen -W '$( _parse_help "$1" --help )' -- ${cur}) ) diff --git a/Auxiliary/bash-completion/cpack b/Auxiliary/bash-completion/cpack index cf5751fa6..5fc47ab42 100644 --- a/Auxiliary/bash-completion/cpack +++ b/Auxiliary/bash-completion/cpack @@ -3,7 +3,9 @@ _cpack() { local cur prev words cword - if type -t _init_completion >/dev/null; then + if type -t _comp_initialize >/dev/null; then + _comp_initialize -n = || return + elif type -t _init_completion >/dev/null; then _init_completion -n = || return else # manual initialization for older bash completion versions diff --git a/Auxiliary/bash-completion/ctest b/Auxiliary/bash-completion/ctest index 3c629d203..51cc6820e 100644 --- a/Auxiliary/bash-completion/ctest +++ b/Auxiliary/bash-completion/ctest @@ -3,7 +3,9 @@ _ctest() { local cur prev words cword - if type -t _init_completion >/dev/null; then + if type -t _comp_initialize >/dev/null; then + _comp_initialize -n = || return + elif type -t _init_completion >/dev/null; then _init_completion -n = || return else # manual initialization for older bash completion versions diff --git a/Auxiliary/cmake-mode.el b/Auxiliary/cmake-mode.el index b5e5ff4bb..893c0d4d0 100644 --- a/Auxiliary/cmake-mode.el +++ b/Auxiliary/cmake-mode.el @@ -1,4 +1,4 @@ -;;; cmake-mode.el --- major-mode for editing CMake sources +;;; cmake-mode.el --- major-mode for editing CMake sources -*- lexical-binding: t; -*- ;; Package-Requires: ((emacs "24.1")) @@ -279,7 +279,7 @@ Return t unless search stops due to end of buffer." ;------------------------------------------------------------------------------ -(defun cmake--syntax-propertize-until-bracket-close (syntax) +(defun cmake--syntax-propertize-until-bracket-close (syntax end) ;; This function assumes that a previous search has matched the ;; beginning of a bracket_comment or bracket_argument and that the ;; second capture group has matched the equal signs between the two @@ -307,10 +307,10 @@ Return t unless search stops due to end of buffer." (syntax-propertize-rules ("\\(#\\)\\[\\(=*\\)\\[" (1 - (prog1 "!" (cmake--syntax-propertize-until-bracket-close "!")))) + (prog1 "!" (cmake--syntax-propertize-until-bracket-close "!" end)))) ("\\(\\[\\)\\(=*\\)\\[" (1 - (prog1 "|" (cmake--syntax-propertize-until-bracket-close "|")))))) + (prog1 "|" (cmake--syntax-propertize-until-bracket-close "|" end)))))) ;; Syntax table for this mode. (defvar cmake-mode-syntax-table nil @@ -480,7 +480,8 @@ and store the result as a list in LISTVAR." ;;;###autoload (defun cmake-help () - "Queries for any of the four available help topics and prints out the appropriate page." + "Queries for any of the four available help topics and prints out the +appropriate page." (interactive) (let* ((default-entry (cmake-symbol-at-point)) (command-list (cmake-get-list "command")) diff --git a/Auxiliary/vim/syntax/cmake.vim b/Auxiliary/vim/syntax/cmake.vim index 562935652..5d412c29f 100644 --- a/Auxiliary/vim/syntax/cmake.vim +++ b/Auxiliary/vim/syntax/cmake.vim @@ -450,6 +450,7 @@ syn keyword cmakeProperty contained \ VS_STARTUP_PROJECT \ VS_TOOL_OVERRIDE \ VS_USER_PROPS + \ VS_FILTER_PROPS \ VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION \ VS_WINRT_COMPONENT \ VS_WINRT_EXTENSIONS diff --git a/CMakeCPack.cmake b/CMakeCPack.cmake index 798affd2f..a0c0e54ff 100644 --- a/CMakeCPack.cmake +++ b/CMakeCPack.cmake @@ -229,15 +229,12 @@ endif() set(CPACK_WIX_UPGRADE_GUID "8ffd1d72-b7f1-11e2-8ee5-00238bca4991") -if(MSVC AND NOT "$ENV{WIX}" STREQUAL "") - set(WIX_CUSTOM_ACTION_ENABLED TRUE) +if(CMake_BUILD_WIX_CUSTOM_ACTION) if(CMAKE_CONFIGURATION_TYPES) - set(WIX_CUSTOM_ACTION_MULTI_CONFIG TRUE) + set(CMake_BUILD_WIX_CUSTOM_ACTION_MULTI_CONFIG TRUE) else() - set(WIX_CUSTOM_ACTION_MULTI_CONFIG FALSE) + set(CMake_BUILD_WIX_CUSTOM_ACTION_MULTI_CONFIG FALSE) endif() -else() - set(WIX_CUSTOM_ACTION_ENABLED FALSE) endif() # Set the options file that needs to be included inside CMakeCPackOptions.cmake diff --git a/CMakeCPackOptions.cmake.in b/CMakeCPackOptions.cmake.in index 7aacf8ece..65f266e39 100644 --- a/CMakeCPackOptions.cmake.in +++ b/CMakeCPackOptions.cmake.in @@ -206,6 +206,9 @@ if("${CPACK_GENERATOR}" STREQUAL "DragNDrop") endif() if("${CPACK_GENERATOR}" STREQUAL "WIX") + set(CPACK_WIX_VERSION 4) + set(CPACK_WIX_BUILD_EXTRA_FLAGS "") + # Reset CPACK_PACKAGE_VERSION to deal with WiX restriction. # But the file names still use the full CMake_VERSION value: set(CPACK_PACKAGE_FILE_NAME @@ -246,14 +249,7 @@ if("${CPACK_GENERATOR}" STREQUAL "WIX") CPACK_START_MENU_SHORTCUTS "CMake Web Site" ) - set(CPACK_WIX_LIGHT_EXTRA_FLAGS "-dcl:high") - - if(NOT "$ENV{CMAKE_CI_PACKAGE}" STREQUAL "") - # Suppress validation. It does not work without - # an interactive session or an admin account. - # https://github.com/wixtoolset/issues/issues/3968 - list(APPEND CPACK_WIX_LIGHT_EXTRA_FLAGS "-sval") - endif() + list(APPEND CPACK_WIX_BUILD_EXTRA_FLAGS -dcl high) set(CPACK_WIX_UI_BANNER "@CMake_SOURCE_DIR@/Utilities/Release/WiX/ui_banner.jpg" @@ -265,17 +261,18 @@ if("${CPACK_GENERATOR}" STREQUAL "WIX") set(CPACK_WIX_EXTRA_SOURCES "@CMake_SOURCE_DIR@/Utilities/Release/WiX/install_dir.wxs" - "@CMake_SOURCE_DIR@/Utilities/Release/WiX/cmake_extra_dialog.wxs" + "@CMake_SOURCE_DIR@/Utilities/Release/WiX/options.wxs" + "@CMake_SOURCE_DIR@/Utilities/Release/WiX/options_dlg.wxs" ) - set(_WIX_CUSTOM_ACTION_ENABLED "@WIX_CUSTOM_ACTION_ENABLED@") + set(_WIX_CUSTOM_ACTION_ENABLED "@CMake_BUILD_WIX_CUSTOM_ACTION@") if(_WIX_CUSTOM_ACTION_ENABLED) list(APPEND CPACK_WIX_EXTRA_SOURCES "@CMake_SOURCE_DIR@/Utilities/Release/WiX/cmake_nsis_overwrite_dialog.wxs" ) - list(APPEND CPACK_WIX_CANDLE_EXTRA_FLAGS -dCHECK_NSIS=1) + list(APPEND CPACK_WIX_BUILD_EXTRA_FLAGS -d CHECK_NSIS=1) - set(_WIX_CUSTOM_ACTION_MULTI_CONFIG "@WIX_CUSTOM_ACTION_MULTI_CONFIG@") + set(_WIX_CUSTOM_ACTION_MULTI_CONFIG "@CMake_BUILD_WIX_CUSTOM_ACTION_MULTI_CONFIG@") if(_WIX_CUSTOM_ACTION_MULTI_CONFIG) if(CPACK_BUILD_CONFIG) set(_WIX_CUSTOM_ACTION_CONFIG "${CPACK_BUILD_CONFIG}") @@ -291,7 +288,7 @@ if("${CPACK_GENERATOR}" STREQUAL "WIX") endif() endif() - set(CPACK_WIX_UI_REF "CMakeUI_InstallDir") + set(CPACK_WIX_UI_REF "CMakeUI_InstallDir_$(sys.BUILDARCHSHORT)") set(CPACK_WIX_PATCH_FILE "@CMake_SOURCE_DIR@/Utilities/Release/WiX/patch_path_env.xml" @@ -307,6 +304,6 @@ if("${CPACK_GENERATOR}" STREQUAL "WIX") list(APPEND CPACK_WIX_PATCH_FILE "@CMake_SOURCE_DIR@/Utilities/Release/WiX/patch_desktop_shortcut.xml" ) - list(APPEND CPACK_WIX_CANDLE_EXTRA_FLAGS -dBUILD_QtDialog=1) + list(APPEND CPACK_WIX_BUILD_EXTRA_FLAGS -d BUILD_QtDialog=1) endif() endif() diff --git a/CMakeLists.txt b/CMakeLists.txt index dfbb38db0..081bd7d1d 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.27 FATAL_ERROR) +cmake_minimum_required(VERSION 3.13...3.28 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) @@ -178,6 +178,9 @@ macro(CMAKE_HANDLE_SYSTEM_LIBRARIES) string(TOLOWER "${util}" lutil) set(CMAKE_USE_SYSTEM_${util} "${CMAKE_USE_SYSTEM_LIBRARY_${util}}" CACHE BOOL "Use system-installed ${lutil}" FORCE) + elseif(util STREQUAL "CURL" AND APPLE) + # macOS provides a curl with backends configured by Apple. + set(CMAKE_USE_SYSTEM_LIBRARY_${util} ON) else() set(CMAKE_USE_SYSTEM_LIBRARY_${util} OFF) endif() @@ -215,6 +218,10 @@ macro(CMAKE_HANDLE_SYSTEM_LIBRARIES) mark_as_advanced(CMAKE_USE_SYSTEM_KWIML) # Mention to the user what system libraries are being used. + if(CMAKE_USE_SYSTEM_CURL) + # Avoid messaging about curl-only dependencies. + list(REMOVE_ITEM UTILITIES NGHTTP2) + endif() foreach(util IN LISTS UTILITIES ITEMS KWIML) if(CMAKE_USE_SYSTEM_${util}) message(STATUS "Using system-installed ${util}") diff --git a/CTestCustom.cmake.in b/CTestCustom.cmake.in index 85af8eda8..ae5571542 100644 --- a/CTestCustom.cmake.in +++ b/CTestCustom.cmake.in @@ -12,11 +12,12 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION "warning: \\(Long double usage is reported only once for each file" "warning: To disable this warning use" "could not be inlined" - "libcmexpat.*has no symbols" - "libcmcurl.*has no symbols" + "libcm(curl|expat).*has no symbols" + "cm(curl|expat).build/[^ ]*.o has no symbols" "not sorted slower link editing will result" "stl_deque.h:479" "Utilities.cmzlib." + "Utilities.cmzstd." "Utilities.cmbzip2." "Source.CTest.Curl" "Source.CursesDialog.form" @@ -85,6 +86,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION "[0-9]+ Warning\\(s\\) detected" # SunPro # Ignore false positive on `cm::optional` usage from GCC + "cmFileCommand.cxx:[0-9]*:[0-9]*: warning: '\\*\\(\\(void\\*\\)& tls_verify \\+2\\)' may be used uninitialized in this function \\[-Wmaybe-uninitialized\\]" "cmGlobalNinjaGenerator.cxx:[0-9]*:[0-9]*: warning: '.*cm::optional::_mem\\)\\)' may be used uninitialized \\[-Wmaybe-uninitialized\\]" "cmGlobalNinjaGenerator.cxx:[0-9]*:[0-9]*: note: '.*cm::optional::_mem\\)\\)' was declared here" "cmGlobalNinjaGenerator.cxx:[0-9]*:[0-9]*: warning: '\\*\\(\\(void\\*\\)& modmap_fmt \\+4\\)' may be used uninitialized in this function \\[-Wmaybe-uninitialized\\]" diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index bd80e6e51..77357c0ee 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -84,8 +84,8 @@ The options are: .. versionadded:: 3.20 Arguments to ``BYPRODUCTS`` may use a restricted set of :manual:`generator expressions `. - :ref:`Target-dependent expressions ` are not - permitted. + :ref:`Target-dependent expressions ` + are not permitted. .. versionchanged:: 3.28 In targets using :ref:`file sets`, custom command byproducts are now @@ -269,17 +269,23 @@ The options are: source tree is mentioned as an absolute source file path elsewhere in the current directory. + The output file path may not contain ``<`` or ``>`` characters. + .. versionadded:: 3.20 Arguments to ``OUTPUT`` may use a restricted set of :manual:`generator expressions `. - :ref:`Target-dependent expressions ` are not - permitted. + :ref:`Target-dependent expressions ` + are not permitted. .. versionchanged:: 3.28 In targets using :ref:`file sets`, custom command outputs are now considered private unless they are listed in a non-private file set. See policy :policy:`CMP0154`. + .. versionchanged:: 3.30 + The output file path may now use ``#`` characters, except + when using the :generator:`Borland Makefiles` generator. + ``USES_TERMINAL`` .. versionadded:: 3.2 diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst index 0385a9353..d88e0f0d8 100644 --- a/Help/command/add_custom_target.rst +++ b/Help/command/add_custom_target.rst @@ -60,8 +60,8 @@ The options are: .. versionadded:: 3.20 Arguments to ``BYPRODUCTS`` may use a restricted set of :manual:`generator expressions `. - :ref:`Target-dependent expressions ` are not - permitted. + :ref:`Target-dependent expressions ` + are not permitted. .. versionchanged:: 3.28 In custom targets using :ref:`file sets`, byproducts are now diff --git a/Help/command/add_dependencies.rst b/Help/command/add_dependencies.rst index 23cb4058f..3a51a30b0 100644 --- a/Help/command/add_dependencies.rst +++ b/Help/command/add_dependencies.rst @@ -20,6 +20,17 @@ transitively in its place since the target itself does not build. .. versionadded:: 3.3 Allow adding dependencies to interface libraries. +.. versionadded:: 3.8 + Dependencies will populate the :prop_tgt:`MANUALLY_ADDED_DEPENDENCIES` + property of ````. + +.. versionchanged:: 3.9 + The :ref:`Ninja Generators` use weaker ordering than + other generators in order to improve available concurrency. + They only guarantee that the dependencies' custom commands are + finished before sources in ```` start compiling; this + ensures generated sources are available. + See Also ^^^^^^^^ diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index 5b22cb139..cab380e6d 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -84,6 +84,13 @@ See also :prop_sf:`HEADER_FILE_ONLY` on what to do if some sources are pre-processed, and you want to have the original sources reachable from within IDE. +.. versionchanged:: 3.30 + + On platforms that do not support shared libraries, ``add_library`` + now fails on calls creating ``SHARED`` libraries instead of + automatically converting them to ``STATIC`` libraries as before. + See policy :policy:`CMP0164`. + Object Libraries ^^^^^^^^^^^^^^^^ diff --git a/Help/command/add_subdirectory.rst b/Help/command/add_subdirectory.rst index ae063e6d6..b5fa45966 100644 --- a/Help/command/add_subdirectory.rst +++ b/Help/command/add_subdirectory.rst @@ -20,19 +20,10 @@ typical usage). The ``CMakeLists.txt`` file in the specified source directory will be processed immediately by CMake before processing in the current input file continues beyond this command. -If the ``EXCLUDE_FROM_ALL`` argument is provided then targets in the -subdirectory will not be included in the ``ALL`` target of the parent -directory by default, and will be excluded from IDE project files. -Users must explicitly build targets in the subdirectory. This is -meant for use when the subdirectory contains a separate part of the -project that is useful but not necessary, such as a set of examples. -Typically the subdirectory should contain its own :command:`project` -command invocation so that a full build system will be generated in the -subdirectory (such as a Visual Studio IDE solution file). Note that -inter-target dependencies supersede this exclusion. If a target built by -the parent project depends on a target in the subdirectory, the dependee -target will be included in the parent project build system to satisfy -the dependency. +If the ``EXCLUDE_FROM_ALL`` argument is provided then the +:prop_dir:`EXCLUDE_FROM_ALL` property will be set on the added directory. +This will exclude the directory from a default build. See the directory +property :prop_dir:`EXCLUDE_FROM_ALL` for full details. .. versionadded:: 3.25 If the ``SYSTEM`` argument is provided, the :prop_dir:`SYSTEM` directory diff --git a/Help/command/cmake_language.rst b/Help/command/cmake_language.rst index 38d06bb23..a9c765373 100644 --- a/Help/command/cmake_language.rst +++ b/Help/command/cmake_language.rst @@ -271,6 +271,11 @@ Dependency Providers :command:`project`. Calling ``cmake_language(SET_DEPENDENCY_PROVIDER)`` outside of that context will result in an error. + .. versionadded:: 3.30 + The :prop_gbl:`PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE` global + property can be set if the dependency provider also wants to be enabled + in whole-project calls to :command:`try_compile`. + .. 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 diff --git a/Help/command/cmake_path.rst b/Help/command/cmake_path.rst index 4e6bedb65..39b7b99a8 100644 --- a/Help/command/cmake_path.rst +++ b/Help/command/cmake_path.rst @@ -600,7 +600,7 @@ For example: # filename is now already empty, the following removes nothing cmake_path(REMOVE_FILENAME path) - message("Second path is \"${result}\"") + message("Second path is \"${path}\"") Output:: diff --git a/Help/command/enable_language.rst b/Help/command/enable_language.rst index 2f1cc2355..d587310ed 100644 --- a/Help/command/enable_language.rst +++ b/Help/command/enable_language.rst @@ -9,15 +9,19 @@ Enable languages (CXX/C/OBJC/OBJCXX/Fortran/etc) Enables support for the named languages in CMake. This is the same as the :command:`project` command but does not create any of the extra -variables that are created by the project command. +variables that are created by the :command:`project` command. .. include:: SUPPORTED_LANGUAGES.txt -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 -indirectly through link dependencies. It is simplest to enable all -needed languages in the top-level directory of a project. +The following restrictions apply to where ``enable_language()`` may be called: + +* It must be called in file scope, not in a function call. +* It must not be called before the first call to :command:`project`. + See policy :policy:`CMP0165`. +* It must be called in the highest directory common to all targets + using the named language directly for compiling sources or + indirectly through link dependencies. It is simplest to enable all + needed languages in the top-level directory of a project. The ``OPTIONAL`` keyword is a placeholder for future implementation and does not currently work. Instead you can use the :module:`CheckLanguage` diff --git a/Help/command/file.rst b/Help/command/file.rst index f373e24f3..5b9dfac5a 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -28,7 +28,6 @@ Synopsis file(`STRINGS`_ [...]) file(`\`_ ) file(`TIMESTAMP`_ [...]) - file(`GET_RUNTIME_DEPENDENCIES`_ [...]) `Writing`_ file({`WRITE`_ | `APPEND`_} ...) @@ -65,6 +64,10 @@ Synopsis file(`ARCHIVE_CREATE`_ OUTPUT PATHS ... [...]) file(`ARCHIVE_EXTRACT`_ INPUT [...]) + `Handling Runtime Binaries`_ + file(`GET_RUNTIME_DEPENDENCIES`_ [...]) + + Reading ^^^^^^^ @@ -157,967 +160,667 @@ Reading See the :command:`string(TIMESTAMP)` command for documentation of the ```` and ``UTC`` options. +Writing +^^^^^^^ + .. signature:: - file(GET_RUNTIME_DEPENDENCIES [...]) + file(WRITE ...) + file(APPEND ...) - .. versionadded:: 3.16 + 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. - Recursively get the list of libraries depended on by the given files: + If the file is a build input, use the :command:`configure_file` command + to update the file only when its content changes. - .. code-block:: cmake +.. signature:: + file(TOUCH ...) + file(TOUCH_NOCREATE ...) - 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.12 - 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: + 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. - .. code-block:: cmake + 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. - install(CODE [[ - file(GET_RUNTIME_DEPENDENCIES - # ... - ) - ]]) + With ``TOUCH`` and ``TOUCH_NOCREATE``, the contents of an existing file + will not be modified. - The arguments are as follows: + .. versionchanged:: 3.30 + ```` can be an empty list. CMake 3.29 and earlier required + at least one file to be given. - ``RESOLVED_DEPENDENCIES_VAR `` - Name of the variable in which to store the list of resolved dependencies. +.. signature:: + file(GENERATE [...]) - ``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. + 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. - ``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 - ``_``. + .. code-block:: cmake - ``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. + file(GENERATE OUTPUT + |CONTENT > + [CONDITION ] [TARGET ] + [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS | + FILE_PERMISSIONS ...] + [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ]) - ``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. + The options are: - ``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. + ``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. - ``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. + ``CONTENT `` + Use the content given explicitly as input. - ``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. + ``INPUT `` + Use the content from a given file as input. - The following arguments specify filters for including or excluding libraries - to be resolved. See below for a full description of how they work. + .. versionchanged:: 3.10 + A relative path is treated with respect to the value of + :variable:`CMAKE_CURRENT_SOURCE_DIR`. See policy :policy:`CMP0070`. - ``PRE_INCLUDE_REGEXES ...`` - List of pre-include regexes through which to filter the names of - not-yet-resolved dependencies. + ``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. - ``PRE_EXCLUDE_REGEXES ...`` - List of pre-exclude regexes through which to filter the names of - not-yet-resolved dependencies. + .. 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`. - ``POST_INCLUDE_REGEXES ...`` - List of post-include regexes through which to filter the names of - resolved dependencies. + ``TARGET `` + .. versionadded:: 3.19 - ``POST_EXCLUDE_REGEXES ...`` - List of post-exclude regexes through which to filter the names of - resolved dependencies. + Specify which target to use when evaluating generator expressions that + require a target for evaluation (e.g. + :genex:`$`, + :genex:`$`). - ``POST_INCLUDE_FILES ...`` - .. versionadded:: 3.21 + ``NO_SOURCE_PERMISSIONS`` + .. versionadded:: 3.20 - List of post-include filenames through which to filter the names of - resolved dependencies. Symlinks are resolved when attempting to match - these filenames. + The generated file permissions default to the standard 644 value + (-rw-r--r--). - ``POST_EXCLUDE_FILES ...`` - .. versionadded:: 3.21 + ``USE_SOURCE_PERMISSIONS`` + .. versionadded:: 3.20 - List of post-exclude filenames through which to filter the names of - resolved dependencies. Symlinks are resolved when attempting to match - these filenames. + 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``. - 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: + ``FILE_PERMISSIONS ...`` + .. versionadded:: 3.20 - 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. + Use the specified permissions for the generated file. - 2. If the not-yet-resolved dependency matches any of the - ``PRE_EXCLUDE_REGEXES``, dependency resolution stops for that dependency. + ``NEWLINE_STYLE