From d2d2ffe1c1658a47d17df20d4f6b7231609ea9d0 Mon Sep 17 00:00:00 2001
From: "Joachim Wuttke (h)" <j.wuttke@fz-juelich.de>
Date: Wed, 24 Apr 2024 14:49:20 +0200
Subject: Help: file: document GET_RUNTIME_DEPENDENCIES separately

Moved documentation of file(GET_RUNTIME_DEPENDENCIES ...) from
the 'Reading' section to a separate section at the bottom of
the page. Because it is a very long text, and because this
signature is quite different from all the others in the
'Reading' section.
---
 Help/command/file.rst | 1688 +++++++++++++++++++++++++------------------------
 1 file changed, 847 insertions(+), 841 deletions(-)

diff --git a/Help/command/file.rst b/Help/command/file.rst
index ee7d05d..ef49faa 100644
--- a/Help/command/file.rst
+++ b/Help/command/file.rst
@@ -28,7 +28,6 @@ Synopsis
     file(`STRINGS`_ <filename> <out-var> [...])
     file(`\<HASH\>`_ <filename> <out-var>)
     file(`TIMESTAMP`_ <filename> <out-var> [...])
-    file(`GET_RUNTIME_DEPENDENCIES`_ [...])
 
   `Writing`_
     file({`WRITE`_ | `APPEND`_} <filename> <content>...)
@@ -65,6 +64,10 @@ Synopsis
     file(`ARCHIVE_CREATE`_ OUTPUT <archive> PATHS <paths>... [...])
     file(`ARCHIVE_EXTRACT`_ INPUT <archive> [...])
 
+  `Handling Runtime Binaries`_
+    file(`GET_RUNTIME_DEPENDENCIES`_ [...])
+
+
 Reading
 ^^^^^^^
 
@@ -157,1121 +160,1124 @@ Reading
   See the :command:`string(TIMESTAMP)` command for documentation of
   the ``<format>`` and ``UTC`` options.
 
+Writing
+^^^^^^^
+
 .. signature::
-  file(GET_RUNTIME_DEPENDENCIES [...])
+  file(WRITE <filename> <content>...)
+  file(APPEND <filename> <content>...)
 
-  .. versionadded:: 3.16
+  Write ``<content>`` into a file called ``<filename>``.  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 ``<filename>`` 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 <files>...)
+  file(TOUCH_NOCREATE <files>...)
 
-    file(GET_RUNTIME_DEPENDENCIES
-      [RESOLVED_DEPENDENCIES_VAR <deps_var>]
-      [UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>]
-      [CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>]
-      [EXECUTABLES <executable_files>...]
-      [LIBRARIES <library_files>...]
-      [MODULES <module_files>...]
-      [DIRECTORIES <directories>...]
-      [BUNDLE_EXECUTABLE <bundle_executable_file>]
-      [PRE_INCLUDE_REGEXES <regexes>...]
-      [PRE_EXCLUDE_REGEXES <regexes>...]
-      [POST_INCLUDE_REGEXES <regexes>...]
-      [POST_EXCLUDE_REGEXES <regexes>...]
-      [POST_INCLUDE_FILES <files>...]
-      [POST_EXCLUDE_FILES <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:
+.. signature::
+  file(GENERATE [...])
 
-    ``RESOLVED_DEPENDENCIES_VAR <deps_var>``
-      Name of the variable in which to store the list of resolved dependencies.
+  Generate an output file for each build configuration supported by the current
+  :manual:`CMake Generator <cmake-generators(7)>`.  Evaluate
+  :manual:`generator expressions <cmake-generator-expressions(7)>`
+  from the input content to produce the output content.
 
-    ``UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_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.
+  .. code-block:: cmake
 
-    ``CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_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 ``<conflicting_deps_prefix>_FILENAMES``. For each filename, the list
-      of paths that were found for that filename are stored in
-      ``<conflicting_deps_prefix>_<filename>``.
+    file(GENERATE OUTPUT <output-file>
+         <INPUT <input-file>|CONTENT <content>>
+         [CONDITION <expression>] [TARGET <target>]
+         [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
+          FILE_PERMISSIONS <permissions>...]
+         [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
 
-    ``EXECUTABLES <executable_files>...``
-      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.
+  The options are:
 
-    ``LIBRARIES <library_files>...``
-      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.
+    ``CONDITION <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.
 
-    ``MODULES <module_files>...``
-      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.
+    ``CONTENT <content>``
+      Use the content given explicitly as input.
 
-    ``DIRECTORIES <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.
+    ``INPUT <input-file>``
+      Use the content from a given file as input.
 
-    ``BUNDLE_EXECUTABLE <bundle_executable_file>``
-      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.
+      .. versionchanged:: 3.10
+        A relative path is treated with respect to the value of
+        :variable:`CMAKE_CURRENT_SOURCE_DIR`.  See policy :policy:`CMP0070`.
 
-  The following arguments specify filters for including or excluding libraries
-  to be resolved. See below for a full description of how they work.
+    ``OUTPUT <output-file>``
+      Specify the output file name to generate.  Use generator expressions
+      such as :genex:`$<CONFIG>` 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
+      ``<output-file>`` must evaluate to an unique name for each configuration.
 
-    ``PRE_INCLUDE_REGEXES <regexes>...``
-      List of pre-include 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`.
 
-    ``PRE_EXCLUDE_REGEXES <regexes>...``
-      List of pre-exclude regexes through which to filter the names of
-      not-yet-resolved dependencies.
+    ``TARGET <target>``
+      .. versionadded:: 3.19
 
-    ``POST_INCLUDE_REGEXES <regexes>...``
-      List of post-include 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:`$<COMPILE_FEATURES:...>`,
+      :genex:`$<TARGET_PROPERTY:prop>`).
 
-    ``POST_EXCLUDE_REGEXES <regexes>...``
-      List of post-exclude regexes through which to filter the names of
-      resolved dependencies.
+    ``NO_SOURCE_PERMISSIONS``
+      .. versionadded:: 3.20
 
-    ``POST_INCLUDE_FILES <files>...``
-      .. versionadded:: 3.21
+      The generated file permissions default to the standard 644 value
+      (-rw-r--r--).
 
-      List of post-include filenames through which to filter the names of
-      resolved dependencies. Symlinks are resolved when attempting to match
-      these filenames.
+    ``USE_SOURCE_PERMISSIONS``
+      .. versionadded:: 3.20
 
-    ``POST_EXCLUDE_FILES <files>...``
-      .. versionadded:: 3.21
+      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``.
 
-      List of post-exclude filenames through which to filter the names of
-      resolved dependencies. Symlinks are resolved when attempting to match
-      these filenames.
+    ``FILE_PERMISSIONS <permissions>...``
+      .. versionadded:: 3.20
 
-  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:
+      Use the specified permissions for the generated file.
 
-  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.
+    ``NEWLINE_STYLE <style>``
+      .. versionadded:: 3.20
 
-  2. If the not-yet-resolved dependency matches any of the
-     ``PRE_EXCLUDE_REGEXES``, dependency resolution stops for that dependency.
+      Specify the newline style for the generated file.  Specify
+      ``UNIX`` or ``LF`` for ``\n`` newlines, or specify
+      ``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines.
 
-  3. Otherwise, dependency resolution proceeds.
+  Exactly one ``CONTENT`` or ``INPUT`` option must be given.  A specific
+  ``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``.
+  Generated files are modified and their timestamp updated on subsequent cmake
+  runs only if their content is changed.
 
-  4. ``file(GET_RUNTIME_DEPENDENCIES)`` searches for the dependency according
-     to the linking rules of the platform (see below).
+  Note also that ``file(GENERATE)`` does not create the output file until the
+  generation phase. The output file will not yet have been written when the
+  ``file(GENERATE)`` command returns, it is written only after processing all
+  of a project's ``CMakeLists.txt`` files.
 
-  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.
+.. signature::
+  file(CONFIGURE OUTPUT <output-file>
+       CONTENT <content>
+       [ESCAPE_QUOTES] [@ONLY]
+       [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
+  :target: CONFIGURE
 
-  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.
+  .. versionadded:: 3.18
 
-  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.
+  Generate an output file using the input given by ``CONTENT`` and substitute
+  variable values referenced as ``@VAR@`` or ``${VAR}`` contained therein. The
+  substitution rules behave the same as the :command:`configure_file` command.
+  In order to match :command:`configure_file`'s behavior, generator expressions
+  are not supported for both ``OUTPUT`` and ``CONTENT``.
 
-  Different platforms have different rules for how dependencies are resolved.
-  These specifics are described here.
+  The arguments are:
 
-  On Linux platforms, library resolution works as follows:
+    ``OUTPUT <output-file>``
+      Specify the output file name to generate. A relative path is treated with
+      respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
+      ``<output-file>`` does not support generator expressions.
 
-  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:
+    ``CONTENT <content>``
+      Use the content given explicitly as input.
+      ``<content>`` does not support generator expressions.
 
-  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:
+    ``ESCAPE_QUOTES``
+      Escape any substituted quotes with backslashes (C-style).
 
-     .. code-block:: cmake
+    ``@ONLY``
+      Restrict variable replacement to references of the form ``@VAR@``.
+      This is useful for configuring scripts that use ``${VAR}`` syntax.
 
-       file(GET_RUNTIME_DEPENDENCIES
-         # ...
-         PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$"
-         )
+    ``NEWLINE_STYLE <style>``
+      Specify the newline style for the output file.  Specify
+      ``UNIX`` or ``LF`` for ``\n`` newlines, or specify
+      ``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines.
 
-     Converting the DLL name to lowercase allows the regexes to only match
-     lowercase names, thus simplifying the regex. For example:
+Filesystem
+^^^^^^^^^^
 
-     .. code-block:: cmake
+.. signature::
+  file(GLOB <variable>
+       [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
+       <globbing-expressions>...)
+  file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS]
+       [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
+       <globbing-expressions>...)
 
-       file(GET_RUNTIME_DEPENDENCIES
-         # ...
-         PRE_INCLUDE_REGEXES "^mylibrary\\.dll$"
-         )
+  Generate a list of files that match the ``<globbing-expressions>`` and
+  store it into the ``<variable>``.  Globbing expressions are similar to
+  regular expressions, but much simpler.  If ``RELATIVE`` flag is
+  specified, the results will be returned as relative paths to the given
+  path.
 
-     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.6
+    The results will be ordered lexicographically.
 
-     .. versionchanged:: 3.27
+  On Windows and macOS, globbing is case-insensitive even if the underlying
+  filesystem is case-sensitive (both filenames and globbing expressions are
+  converted to lowercase before matching).  On other platforms, globbing is
+  case-sensitive.
 
-       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.
+  .. versionadded:: 3.3
+    By default ``GLOB`` lists directories. Directories are omitted in the
+    result if ``LIST_DIRECTORIES`` is set to false.
 
-       Prior to CMake 3.27, the results were reported with lowercase DLL
-       file names, but the directory portion retained its casing.
+  .. versionadded:: 3.12
+    If the ``CONFIGURE_DEPENDS`` flag is specified, CMake will add logic
+    to the main build system check target to rerun the flagged ``GLOB``
+    commands at build time. If any of the outputs change, CMake will regenerate
+    the build system.
 
-  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.
+  .. note::
+    We do not recommend using GLOB to collect a list of source files from
+    your source tree.  If no CMakeLists.txt file changes when a source is
+    added or removed then the generated build system cannot know when to
+    ask CMake to regenerate.
+    The ``CONFIGURE_DEPENDS`` flag may not work reliably on all generators, or
+    if a new generator is added in the future that cannot support it, projects
+    using it will be stuck. Even if ``CONFIGURE_DEPENDS`` works reliably, there
+    is still a cost to perform the check on every rebuild.
 
-  3. Otherwise, if the library exists in the same directory as the depending
-     file, the dependency is resolved to that file.
+  Examples of globbing expressions include:
 
-  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.
+  ============== ======================================================
+  ``*.cxx``      match all files with extension ``cxx``
+  ``*.vt?``      match all files with extension ``vta``, ..., ``vtz``
+  ``f[3-5].txt`` match files ``f3.txt``, ``f4.txt``, ``f5.txt``
+  ============== ======================================================
 
-  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.
+  The ``GLOB_RECURSE`` mode will traverse all the subdirectories of the
+  matched directory and match the files.  Subdirectories that are symlinks
+  are only traversed if ``FOLLOW_SYMLINKS`` is given or policy
+  :policy:`CMP0009` is not set to ``NEW``.
 
-  6. Otherwise, the dependency is unresolved.
+  .. versionadded:: 3.3
+    By default ``GLOB_RECURSE`` omits directories from result list. Setting
+    ``LIST_DIRECTORIES`` to true adds directories to result list.
+    If ``FOLLOW_SYMLINKS`` is given or policy :policy:`CMP0009` is not set to
+    ``NEW`` then ``LIST_DIRECTORIES`` treats symlinks as directories.
 
-  On Apple platforms, library resolution works as follows:
+  Examples of recursive globbing include:
 
-  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.
+  ============== ======================================================
+  ``/dir/*.py``  match all python files in ``/dir`` and subdirectories
+  ============== ======================================================
 
-  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.
+.. signature::
+  file(MAKE_DIRECTORY <directories>...)
 
-  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.
+  Create the given directories and their parents as needed.
 
-  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.
+.. signature::
+  file(REMOVE <files>...)
+  file(REMOVE_RECURSE <files>...)
 
-  5. Otherwise, if the dependency is an absolute file that exists,
-     the dependency is resolved to that file.
+  Remove the given files.  The ``REMOVE_RECURSE`` mode will remove the given
+  files and directories, including non-empty directories. No error is emitted
+  if a given file does not exist.  Relative input paths are evaluated with
+  respect to the current source directory.
 
-  6. Otherwise, the dependency is unresolved.
+  .. versionchanged:: 3.15
+    Empty input paths are ignored with a warning.  Previous versions of CMake
+    interpreted empty strings as a relative path with respect to the current
+    directory and removed its contents.
 
-  This function accepts several variables that determine which tool is used for
-  dependency resolution:
+.. signature::
+  file(RENAME <oldname> <newname> [RESULT <result>] [NO_REPLACE])
 
-  .. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM
+  Move a file or directory within a filesystem from ``<oldname>`` to
+  ``<newname>``, replacing the destination atomically.
 
-    Determines which operating system and executable format the files are built
-    for. This could be one of several values:
+  The options are:
 
-    * ``linux+elf``
-    * ``windows+pe``
-    * ``macos+macho``
+    ``RESULT <result>``
+      .. versionadded:: 3.21
 
-    If this variable is not specified, it is determined automatically by system
-    introspection.
+      Set ``<result>`` variable to ``0`` on success or an error message
+      otherwise. If ``RESULT`` is not specified and the operation fails,
+      an error is emitted.
 
-  .. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL
+    ``NO_REPLACE``
+      .. versionadded:: 3.21
 
-    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`:
+      If the ``<newname>`` path already exists, do not replace it.
+      If ``RESULT <result>`` is used, the result variable will be
+      set to ``NO_REPLACE``.  Otherwise, an error is emitted.
 
-    ================================================= =============================================
-       ``CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM``       ``CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL``
-    ================================================= =============================================
-    ``linux+elf``                                     ``objdump``
-    ``windows+pe``                                    ``objdump`` or ``dumpbin``
-    ``macos+macho``                                   ``otool``
-    ================================================= =============================================
+.. signature::
+  file(COPY_FILE <oldname> <newname>
+       [RESULT <result>]
+       [ONLY_IF_DIFFERENT]
+       [INPUT_MAY_BE_RECENT])
 
-    If this variable is not specified, it is determined automatically by system
-    introspection.
+  .. versionadded:: 3.21
 
-  .. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND
+  Copy a file from ``<oldname>`` to ``<newname>``. Directories are not
+  supported. Symlinks are ignored and ``<oldfile>``'s content is read and
+  written to ``<newname>`` as a new file.
 
-    Determines the path to the tool to use for dependency resolution. This is
-    the actual path to ``objdump``, ``dumpbin``, or ``otool``.
+  The options are:
 
-    If this variable is not specified, it is determined by the value of
-    ``CMAKE_OBJDUMP`` if set, else by system introspection.
+    ``RESULT <result>``
+      Set ``<result>`` variable to ``0`` on success or an error message
+      otherwise.  If ``RESULT`` is not specified and the operation fails,
+      an error is emitted.
 
-    .. versionadded:: 3.18
-      Use ``CMAKE_OBJDUMP`` if set.
+    ``ONLY_IF_DIFFERENT``
+      If the ``<newname>`` path already exists, do not replace it if the file's
+      contents are already the same as ``<oldname>`` (this avoids updating
+      ``<newname>``'s timestamp).
 
-Writing
-^^^^^^^
+    ``INPUT_MAY_BE_RECENT``
+      .. versionadded:: 3.26
 
-.. signature::
-  file(WRITE <filename> <content>...)
-  file(APPEND <filename> <content>...)
+      Tell CMake that the input file may have been recently created.  This is
+      meaningful only on Windows, where files may be inaccessible for a short
+      time after they are created.  With this option, if permission is denied,
+      CMake will retry reading the input a few times.
 
-  Write ``<content>`` into a file called ``<filename>``.  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 ``<filename>`` that do not
-  exist will be created.
+  This sub-command has some similarities to :command:`configure_file`
+  with the ``COPYONLY`` option.  An important difference is that
+  :command:`configure_file` creates a dependency on the source file,
+  so CMake will be re-run if it changes. The ``file(COPY_FILE)``
+  sub-command does not create such a dependency.
 
-  If the file is a build input, use the :command:`configure_file` command
-  to update the file only when its content changes.
+  See also the :command:`file(COPY)` sub-command just below which provides
+  further file-copying capabilities.
 
 .. signature::
-  file(TOUCH <files>...)
-  file(TOUCH_NOCREATE <files>...)
+  file(COPY [...])
+  file(INSTALL [...])
 
-  .. versionadded:: 3.12
+  The ``COPY`` signature copies files, directories, and symlinks to a
+  destination folder.  Relative input paths are evaluated with respect
+  to the current source directory, and a relative destination is
+  evaluated with respect to the current build directory.  Copying
+  preserves input file timestamps, and optimizes out a file if it exists
+  at the destination with the same timestamp.  Copying preserves input
+  permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS``
+  are given (default is ``USE_SOURCE_PERMISSIONS``).
 
-  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.
+    file(<COPY|INSTALL> <files>... DESTINATION <dir>
+         [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS]
+         [FILE_PERMISSIONS <permissions>...]
+         [DIRECTORY_PERMISSIONS <permissions>...]
+         [FOLLOW_SYMLINK_CHAIN]
+         [FILES_MATCHING]
+         [[PATTERN <pattern> | REGEX <regex>]
+          [EXCLUDE] [PERMISSIONS <permissions>...]] [...])
 
-  With ``TOUCH`` and ``TOUCH_NOCREATE``, the contents of an existing file
-  will not be modified.
+  .. note::
 
-.. signature::
-  file(GENERATE [...])
+    For a simple file copying operation, the :command:`file(COPY_FILE)`
+    sub-command just above may be easier to use.
 
-  Generate an output file for each build configuration supported by the current
-  :manual:`CMake Generator <cmake-generators(7)>`.  Evaluate
-  :manual:`generator expressions <cmake-generator-expressions(7)>`
-  from the input content to produce the output content.
+  .. versionadded:: 3.15
+    If ``FOLLOW_SYMLINK_CHAIN`` is specified, ``COPY`` will recursively resolve
+    the symlinks at the paths given until a real file is found, and install
+    a corresponding symlink in the destination for each symlink encountered.
+    For each symlink that is installed, the resolution is stripped of the
+    directory, leaving only the filename, meaning that the new symlink points
+    to a file in the same directory as the symlink. This feature is useful on
+    some Unix systems, where libraries are installed as a chain of symlinks
+    with version numbers, with less specific versions pointing to more specific
+    versions. ``FOLLOW_SYMLINK_CHAIN`` will install all of these symlinks and
+    the library itself into the destination directory. For example, if you have
+    the following directory structure:
 
-  .. code-block:: cmake
+      * ``/opt/foo/lib/libfoo.so.1.2.3``
+      * ``/opt/foo/lib/libfoo.so.1.2 -> libfoo.so.1.2.3``
+      * ``/opt/foo/lib/libfoo.so.1 -> libfoo.so.1.2``
+      * ``/opt/foo/lib/libfoo.so -> libfoo.so.1``
 
-    file(GENERATE OUTPUT <output-file>
-         <INPUT <input-file>|CONTENT <content>>
-         [CONDITION <expression>] [TARGET <target>]
-         [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
-          FILE_PERMISSIONS <permissions>...]
-         [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
+    and you do:
 
-  The options are:
+    .. code-block:: cmake
 
-    ``CONDITION <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.
+      file(COPY /opt/foo/lib/libfoo.so DESTINATION lib FOLLOW_SYMLINK_CHAIN)
 
-    ``CONTENT <content>``
-      Use the content given explicitly as input.
+    This will install all of the symlinks and ``libfoo.so.1.2.3`` itself into
+    ``lib``.
 
-    ``INPUT <input-file>``
-      Use the content from a given file as input.
+  See the :command:`install(DIRECTORY)` command for documentation of
+  permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and
+  ``EXCLUDE`` options.  Copying directories preserves the structure
+  of their content even if options are used to select a subset of
+  files.
 
-      .. versionchanged:: 3.10
-        A relative path is treated with respect to the value of
-        :variable:`CMAKE_CURRENT_SOURCE_DIR`.  See policy :policy:`CMP0070`.
+  The ``INSTALL`` signature differs slightly from ``COPY``: it prints
+  status messages, and ``NO_SOURCE_PERMISSIONS`` is default. Installation
+  scripts generated by the :command:`install` command use this signature
+  (with some undocumented options for internal use).
 
-    ``OUTPUT <output-file>``
-      Specify the output file name to generate.  Use generator expressions
-      such as :genex:`$<CONFIG>` 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
-      ``<output-file>`` must evaluate to an unique name for each configuration.
+  .. versionchanged:: 3.22
 
-      .. 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`.
+    The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the
+    default copying behavior of :command:`file(INSTALL)`.
 
-    ``TARGET <target>``
-      .. versionadded:: 3.19
+.. signature::
+  file(SIZE <filename> <variable>)
 
-      Specify which target to use when evaluating generator expressions that
-      require a target for evaluation (e.g.
-      :genex:`$<COMPILE_FEATURES:...>`,
-      :genex:`$<TARGET_PROPERTY:prop>`).
+  .. versionadded:: 3.14
 
-    ``NO_SOURCE_PERMISSIONS``
-      .. versionadded:: 3.20
+  Determine the file size of the ``<filename>`` and put the result in
+  ``<variable>`` variable. Requires that ``<filename>`` is a valid path
+  pointing to a file and is readable.
 
-      The generated file permissions default to the standard 644 value
-      (-rw-r--r--).
+.. signature::
+  file(READ_SYMLINK <linkname> <variable>)
 
-    ``USE_SOURCE_PERMISSIONS``
-      .. versionadded:: 3.20
+  .. versionadded:: 3.14
 
-      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``.
+  Query the symlink ``<linkname>`` and stores the path it points to
+  in the result ``<variable>``.  If ``<linkname>`` does not exist
+  or is not a symlink, CMake issues a fatal error.
 
-    ``FILE_PERMISSIONS <permissions>...``
-      .. versionadded:: 3.20
+  Note that this command returns the raw symlink path and does not resolve
+  a relative path.  The following is an example of how to ensure that an
+  absolute path is obtained:
 
-      Use the specified permissions for the generated file.
+  .. code-block:: cmake
 
-    ``NEWLINE_STYLE <style>``
-      .. versionadded:: 3.20
+    set(linkname "/path/to/foo.sym")
+    file(READ_SYMLINK "${linkname}" result)
+    if(NOT IS_ABSOLUTE "${result}")
+      get_filename_component(dir "${linkname}" DIRECTORY)
+      set(result "${dir}/${result}")
+    endif()
 
-      Specify the newline style for the generated file.  Specify
-      ``UNIX`` or ``LF`` for ``\n`` newlines, or specify
-      ``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines.
+.. signature::
+  file(CREATE_LINK <original> <linkname>
+       [RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC])
 
-  Exactly one ``CONTENT`` or ``INPUT`` option must be given.  A specific
-  ``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``.
-  Generated files are modified and their timestamp updated on subsequent cmake
-  runs only if their content is changed.
+  .. versionadded:: 3.14
 
-  Note also that ``file(GENERATE)`` does not create the output file until the
-  generation phase. The output file will not yet have been written when the
-  ``file(GENERATE)`` command returns, it is written only after processing all
-  of a project's ``CMakeLists.txt`` files.
+  Create a link ``<linkname>`` that points to ``<original>``.
+  It will be a hard link by default, but providing the ``SYMBOLIC`` option
+  results in a symbolic link instead.  Hard links require that ``original``
+  exists and is a file, not a directory.  If ``<linkname>`` already exists,
+  it will be overwritten.
+
+  The ``<result>`` variable, if specified, receives the status of the
+  operation.  It is set to ``0`` upon success or an error message otherwise.
+  If ``RESULT`` is not specified and the operation fails, a fatal error is
+  emitted.
+
+  Specifying ``COPY_ON_ERROR`` enables copying the file as a fallback if
+  creating the link fails.  It can be useful for handling situations such as
+  ``<original>`` and ``<linkname>`` being on different drives or mount points,
+  which would make them unable to support a hard link.
 
 .. signature::
-  file(CONFIGURE OUTPUT <output-file>
-       CONTENT <content>
-       [ESCAPE_QUOTES] [@ONLY]
-       [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
-  :target: CONFIGURE
+  file(CHMOD <files>... <directories>...
+       [PERMISSIONS <permissions>...]
+       [FILE_PERMISSIONS <permissions>...]
+       [DIRECTORY_PERMISSIONS <permissions>...])
 
-  .. versionadded:: 3.18
+  .. versionadded:: 3.19
 
-  Generate an output file using the input given by ``CONTENT`` and substitute
-  variable values referenced as ``@VAR@`` or ``${VAR}`` contained therein. The
-  substitution rules behave the same as the :command:`configure_file` command.
-  In order to match :command:`configure_file`'s behavior, generator expressions
-  are not supported for both ``OUTPUT`` and ``CONTENT``.
+  Set the permissions for the ``<files>...`` and ``<directories>...``
+  specified. Valid permissions are  ``OWNER_READ``, ``OWNER_WRITE``,
+  ``OWNER_EXECUTE``, ``GROUP_READ``, ``GROUP_WRITE``, ``GROUP_EXECUTE``,
+  ``WORLD_READ``, ``WORLD_WRITE``, ``WORLD_EXECUTE``, ``SETUID``, ``SETGID``.
 
-  The arguments are:
+  Valid combination of keywords are:
 
-    ``OUTPUT <output-file>``
-      Specify the output file name to generate. A relative path is treated with
-      respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
-      ``<output-file>`` does not support generator expressions.
+    ``PERMISSIONS``
+      All items are changed.
 
-    ``CONTENT <content>``
-      Use the content given explicitly as input.
-      ``<content>`` does not support generator expressions.
+    ``FILE_PERMISSIONS``
+      Only files are changed.
 
-    ``ESCAPE_QUOTES``
-      Escape any substituted quotes with backslashes (C-style).
+    ``DIRECTORY_PERMISSIONS``
+      Only directories are changed.
 
-    ``@ONLY``
-      Restrict variable replacement to references of the form ``@VAR@``.
-      This is useful for configuring scripts that use ``${VAR}`` syntax.
+    ``PERMISSIONS`` and ``FILE_PERMISSIONS``
+      ``FILE_PERMISSIONS`` overrides ``PERMISSIONS`` for files.
 
-    ``NEWLINE_STYLE <style>``
-      Specify the newline style for the output file.  Specify
-      ``UNIX`` or ``LF`` for ``\n`` newlines, or specify
-      ``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines.
+    ``PERMISSIONS`` and ``DIRECTORY_PERMISSIONS``
+      ``DIRECTORY_PERMISSIONS`` overrides ``PERMISSIONS`` for directories.
 
-Filesystem
-^^^^^^^^^^
+    ``FILE_PERMISSIONS`` and ``DIRECTORY_PERMISSIONS``
+      Use ``FILE_PERMISSIONS`` for files and ``DIRECTORY_PERMISSIONS`` for
+      directories.
 
 .. signature::
-  file(GLOB <variable>
-       [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
-       <globbing-expressions>...)
-  file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS]
-       [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
-       <globbing-expressions>...)
+  file(CHMOD_RECURSE <files>... <directories>...
+       [PERMISSIONS <permissions>...]
+       [FILE_PERMISSIONS <permissions>...]
+       [DIRECTORY_PERMISSIONS <permissions>...])
 
-  Generate a list of files that match the ``<globbing-expressions>`` and
-  store it into the ``<variable>``.  Globbing expressions are similar to
-  regular expressions, but much simpler.  If ``RELATIVE`` flag is
-  specified, the results will be returned as relative paths to the given
-  path.
+  .. versionadded:: 3.19
 
-  .. versionchanged:: 3.6
-    The results will be ordered lexicographically.
+  Same as :cref:`CHMOD`, but change the permissions of files and directories
+  present in the ``<directories>...`` recursively.
 
-  On Windows and macOS, globbing is case-insensitive even if the underlying
-  filesystem is case-sensitive (both filenames and globbing expressions are
-  converted to lowercase before matching).  On other platforms, globbing is
-  case-sensitive.
 
-  .. versionadded:: 3.3
-    By default ``GLOB`` lists directories. Directories are omitted in the
-    result if ``LIST_DIRECTORIES`` is set to false.
+Path Conversion
+^^^^^^^^^^^^^^^
 
-  .. versionadded:: 3.12
-    If the ``CONFIGURE_DEPENDS`` flag is specified, CMake will add logic
-    to the main build system check target to rerun the flagged ``GLOB``
-    commands at build time. If any of the outputs change, CMake will regenerate
-    the build system.
+.. signature::
+  file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE])
 
-  .. note::
-    We do not recommend using GLOB to collect a list of source files from
-    your source tree.  If no CMakeLists.txt file changes when a source is
-    added or removed then the generated build system cannot know when to
-    ask CMake to regenerate.
-    The ``CONFIGURE_DEPENDS`` flag may not work reliably on all generators, or
-    if a new generator is added in the future that cannot support it, projects
-    using it will be stuck. Even if ``CONFIGURE_DEPENDS`` works reliably, there
-    is still a cost to perform the check on every rebuild.
+  .. versionadded:: 3.19
 
-  Examples of globbing expressions include:
+  Compute the absolute path to an existing file or directory with symlinks
+  resolved.  The options are:
 
-  ============== ======================================================
-  ``*.cxx``      match all files with extension ``cxx``
-  ``*.vt?``      match all files with extension ``vta``, ..., ``vtz``
-  ``f[3-5].txt`` match files ``f3.txt``, ``f4.txt``, ``f5.txt``
-  ============== ======================================================
+    ``BASE_DIRECTORY <dir>``
+      If the provided ``<path>`` is a relative path, it is evaluated relative
+      to the given base directory ``<dir>``. If no base directory is provided,
+      the default base directory will be :variable:`CMAKE_CURRENT_SOURCE_DIR`.
 
-  The ``GLOB_RECURSE`` mode will traverse all the subdirectories of the
-  matched directory and match the files.  Subdirectories that are symlinks
-  are only traversed if ``FOLLOW_SYMLINKS`` is given or policy
-  :policy:`CMP0009` is not set to ``NEW``.
+    ``EXPAND_TILDE``
+      .. versionadded:: 3.21
 
-  .. versionadded:: 3.3
-    By default ``GLOB_RECURSE`` omits directories from result list. Setting
-    ``LIST_DIRECTORIES`` to true adds directories to result list.
-    If ``FOLLOW_SYMLINKS`` is given or policy :policy:`CMP0009` is not set to
-    ``NEW`` then ``LIST_DIRECTORIES`` treats symlinks as directories.
+      If the ``<path>`` is ``~`` or starts with ``~/``, the ``~`` is replaced
+      by the user's home directory.  The path to the home directory is obtained
+      from environment variables.  On Windows, the ``USERPROFILE`` environment
+      variable is used, falling back to the ``HOME`` environment variable
+      if ``USERPROFILE`` is not defined.  On all other platforms, only ``HOME``
+      is used.
 
-  Examples of recursive globbing include:
+  .. versionchanged:: 3.28
 
-  ============== ======================================================
-  ``/dir/*.py``  match all python files in ``/dir`` and subdirectories
-  ============== ======================================================
+    All symlinks are resolved before collapsing ``../`` components.
+    See policy :policy:`CMP0152`.
 
 .. signature::
-  file(MAKE_DIRECTORY <directories>...)
+  file(RELATIVE_PATH <variable> <directory> <file>)
 
-  Create the given directories and their parents as needed.
+  Compute the relative path from a ``<directory>`` to a ``<file>`` and
+  store it in the ``<variable>``.
 
 .. signature::
-  file(REMOVE <files>...)
-  file(REMOVE_RECURSE <files>...)
-
-  Remove the given files.  The ``REMOVE_RECURSE`` mode will remove the given
-  files and directories, including non-empty directories. No error is emitted
-  if a given file does not exist.  Relative input paths are evaluated with
-  respect to the current source directory.
+  file(TO_CMAKE_PATH "<path>" <variable>)
+  file(TO_NATIVE_PATH "<path>" <variable>)
 
-  .. versionchanged:: 3.15
-    Empty input paths are ignored with a warning.  Previous versions of CMake
-    interpreted empty strings as a relative path with respect to the current
-    directory and removed its contents.
+  The ``TO_CMAKE_PATH`` mode converts a native ``<path>`` into a cmake-style
+  path with forward-slashes (``/``).  The input can be a single path or a
+  system search path like ``$ENV{PATH}``.  A search path will be converted
+  to a cmake-style list separated by ``;`` characters.
 
-.. signature::
-  file(RENAME <oldname> <newname> [RESULT <result>] [NO_REPLACE])
+  The ``TO_NATIVE_PATH`` mode converts a cmake-style ``<path>`` into a native
+  path with platform-specific slashes (``\`` on Windows hosts and ``/``
+  elsewhere).
 
-  Move a file or directory within a filesystem from ``<oldname>`` to
-  ``<newname>``, replacing the destination atomically.
+  Always use double quotes around the ``<path>`` to be sure it is treated
+  as a single argument to this command.
 
-  The options are:
+Transfer
+^^^^^^^^
 
-    ``RESULT <result>``
-      .. versionadded:: 3.21
+.. signature::
+  file(DOWNLOAD <url> [<file>] <options>...)
+  file(UPLOAD <file> <url> <options>...)
 
-      Set ``<result>`` variable to ``0`` on success or an error message
-      otherwise. If ``RESULT`` is not specified and the operation fails,
-      an error is emitted.
+  The ``DOWNLOAD`` subcommand downloads the given ``<url>`` to a local
+  ``<file>``.  The ``UPLOAD`` mode uploads a local ``<file>`` to a given
+  ``<url>``.
 
-    ``NO_REPLACE``
-      .. versionadded:: 3.21
+  .. versionadded:: 3.19
+    If ``<file>`` is not specified for ``file(DOWNLOAD)``, the file is not
+    saved. This can be useful if you want to know if a file can be downloaded
+    (for example, to check that it exists) without actually saving it anywhere.
 
-      If the ``<newname>`` path already exists, do not replace it.
-      If ``RESULT <result>`` is used, the result variable will be
-      set to ``NO_REPLACE``.  Otherwise, an error is emitted.
+  Options to both ``DOWNLOAD`` and ``UPLOAD`` are:
 
-.. signature::
-  file(COPY_FILE <oldname> <newname>
-       [RESULT <result>]
-       [ONLY_IF_DIFFERENT]
-       [INPUT_MAY_BE_RECENT])
+    ``INACTIVITY_TIMEOUT <seconds>``
+      Terminate the operation after a period of inactivity.
 
-  .. versionadded:: 3.21
+    ``LOG <variable>``
+      Store a human-readable log of the operation in a variable.
 
-  Copy a file from ``<oldname>`` to ``<newname>``. Directories are not
-  supported. Symlinks are ignored and ``<oldfile>``'s content is read and
-  written to ``<newname>`` as a new file.
+    ``SHOW_PROGRESS``
+      Print progress information as status messages until the operation is
+      complete.
 
-  The options are:
+    ``STATUS <variable>``
+      Store the resulting status of the operation in a variable.
+      The status is a ``;`` separated list of length 2.
+      The first element is the numeric return value for the operation,
+      and the second element is a string value for the error.
+      A ``0`` numeric error means no error in the operation.
 
-    ``RESULT <result>``
-      Set ``<result>`` variable to ``0`` on success or an error message
-      otherwise.  If ``RESULT`` is not specified and the operation fails,
-      an error is emitted.
+    ``TIMEOUT <seconds>``
+      Terminate the operation after a given total time has elapsed.
 
-    ``ONLY_IF_DIFFERENT``
-      If the ``<newname>`` path already exists, do not replace it if the file's
-      contents are already the same as ``<oldname>`` (this avoids updating
-      ``<newname>``'s timestamp).
+    ``USERPWD <username>:<password>``
+      .. versionadded:: 3.7
 
-    ``INPUT_MAY_BE_RECENT``
-      .. versionadded:: 3.26
+      Set username and password for operation.
 
-      Tell CMake that the input file may have been recently created.  This is
-      meaningful only on Windows, where files may be inaccessible for a short
-      time after they are created.  With this option, if permission is denied,
-      CMake will retry reading the input a few times.
+    ``HTTPHEADER <HTTP-header>``
+      .. versionadded:: 3.7
 
-  This sub-command has some similarities to :command:`configure_file`
-  with the ``COPYONLY`` option.  An important difference is that
-  :command:`configure_file` creates a dependency on the source file,
-  so CMake will be re-run if it changes. The ``file(COPY_FILE)``
-  sub-command does not create such a dependency.
+      HTTP header for ``DOWNLOAD`` and ``UPLOAD`` operations. ``HTTPHEADER``
+      can be repeated for multiple options:
 
-  See also the :command:`file(COPY)` sub-command just below which provides
-  further file-copying capabilities.
+      .. code-block:: cmake
 
-.. signature::
-  file(COPY [...])
-  file(INSTALL [...])
+        file(DOWNLOAD <url>
+             HTTPHEADER "Authorization: Bearer <auth-token>"
+             HTTPHEADER "UserAgent: Mozilla/5.0")
 
-  The ``COPY`` signature copies files, directories, and symlinks to a
-  destination folder.  Relative input paths are evaluated with respect
-  to the current source directory, and a relative destination is
-  evaluated with respect to the current build directory.  Copying
-  preserves input file timestamps, and optimizes out a file if it exists
-  at the destination with the same timestamp.  Copying preserves input
-  permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS``
-  are given (default is ``USE_SOURCE_PERMISSIONS``).
+    ``NETRC <level>``
+      .. versionadded:: 3.11
 
-  .. code-block:: cmake
+      Specify whether the .netrc file is to be used for operation.  If this
+      option is not specified, the value of the :variable:`CMAKE_NETRC`
+      variable will be used instead.
 
-    file(<COPY|INSTALL> <files>... DESTINATION <dir>
-         [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS]
-         [FILE_PERMISSIONS <permissions>...]
-         [DIRECTORY_PERMISSIONS <permissions>...]
-         [FOLLOW_SYMLINK_CHAIN]
-         [FILES_MATCHING]
-         [[PATTERN <pattern> | REGEX <regex>]
-          [EXCLUDE] [PERMISSIONS <permissions>...]] [...])
+      Valid levels are:
 
-  .. note::
+        ``IGNORED``
+          The .netrc file is ignored.
+          This is the default.
 
-    For a simple file copying operation, the :command:`file(COPY_FILE)`
-    sub-command just above may be easier to use.
+        ``OPTIONAL``
+          The .netrc file is optional, and information in the URL is preferred.
+          The file will be scanned to find which ever information is not
+          specified in the URL.
 
-  .. versionadded:: 3.15
-    If ``FOLLOW_SYMLINK_CHAIN`` is specified, ``COPY`` will recursively resolve
-    the symlinks at the paths given until a real file is found, and install
-    a corresponding symlink in the destination for each symlink encountered.
-    For each symlink that is installed, the resolution is stripped of the
-    directory, leaving only the filename, meaning that the new symlink points
-    to a file in the same directory as the symlink. This feature is useful on
-    some Unix systems, where libraries are installed as a chain of symlinks
-    with version numbers, with less specific versions pointing to more specific
-    versions. ``FOLLOW_SYMLINK_CHAIN`` will install all of these symlinks and
-    the library itself into the destination directory. For example, if you have
-    the following directory structure:
+        ``REQUIRED``
+          The .netrc file is required, and information in the URL is ignored.
 
-      * ``/opt/foo/lib/libfoo.so.1.2.3``
-      * ``/opt/foo/lib/libfoo.so.1.2 -> libfoo.so.1.2.3``
-      * ``/opt/foo/lib/libfoo.so.1 -> libfoo.so.1.2``
-      * ``/opt/foo/lib/libfoo.so -> libfoo.so.1``
+    ``NETRC_FILE <file>``
+      .. versionadded:: 3.11
 
-    and you do:
+      Specify an alternative .netrc file to the one in your home directory,
+      if the ``NETRC`` level is ``OPTIONAL`` or ``REQUIRED``. If this option
+      is not specified, the value of the :variable:`CMAKE_NETRC_FILE` variable
+      will be used instead.
 
-    .. code-block:: cmake
+    ``TLS_VERSION <min>``
+      .. versionadded:: 3.30
 
-      file(COPY /opt/foo/lib/libfoo.so DESTINATION lib FOLLOW_SYMLINK_CHAIN)
+      Specify minimum TLS version for ``https://`` URLs.
+      If this option is not specified, the value of the
+      :variable:`CMAKE_TLS_VERSION` variable or :envvar:`CMAKE_TLS_VERSION`
+      environment variable will be used instead.
+      See :variable:`CMAKE_TLS_VERSION` for allowed values.
 
-    This will install all of the symlinks and ``libfoo.so.1.2.3`` itself into
-    ``lib``.
+    ``TLS_VERIFY <ON|OFF>``
+      Specify whether to verify the server certificate for ``https://`` URLs.
+      The default is to *not* verify. If this option is not specified, the
+      value of the :variable:`CMAKE_TLS_VERIFY` variable will be used instead.
 
-  See the :command:`install(DIRECTORY)` command for documentation of
-  permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and
-  ``EXCLUDE`` options.  Copying directories preserves the structure
-  of their content even if options are used to select a subset of
-  files.
+      .. versionadded:: 3.18
+        Added support to ``file(UPLOAD)``.
 
-  The ``INSTALL`` signature differs slightly from ``COPY``: it prints
-  status messages, and ``NO_SOURCE_PERMISSIONS`` is default. Installation
-  scripts generated by the :command:`install` command use this signature
-  (with some undocumented options for internal use).
+    ``TLS_CAINFO <file>``
+      Specify a custom Certificate Authority file for ``https://`` URLs.
+      If this option is not specified, the value of the
+      :variable:`CMAKE_TLS_CAINFO` variable will be used instead.
 
-  .. versionchanged:: 3.22
+      .. versionadded:: 3.18
+        Added support to ``file(UPLOAD)``.
 
-    The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the
-    default copying behavior of :command:`file(INSTALL)`.
+  For ``https://`` URLs CMake must be built with OpenSSL support.  ``TLS/SSL``
+  certificates are not checked by default.  Set ``TLS_VERIFY`` to ``ON`` to
+  check certificates.
 
-.. signature::
-  file(SIZE <filename> <variable>)
+  Additional options to ``DOWNLOAD`` are:
 
-  .. versionadded:: 3.14
-
-  Determine the file size of the ``<filename>`` and put the result in
-  ``<variable>`` variable. Requires that ``<filename>`` is a valid path
-  pointing to a file and is readable.
+    ``EXPECTED_HASH <algorithm>=<value>``
+      Verify that the downloaded content hash matches the expected value, where
+      ``<algorithm>`` is one of the algorithms supported by :cref:`<HASH>`.
+      If the file already exists and matches the hash, the download is skipped.
+      If the file already exists and does not match the hash, the file is
+      downloaded again. If after download the file does not match the hash, the
+      operation fails with an error. It is an error to specify this option if
+      ``DOWNLOAD`` is not given a ``<file>``.
 
-.. signature::
-  file(READ_SYMLINK <linkname> <variable>)
+    ``EXPECTED_MD5 <value>``
+      Historical short-hand for ``EXPECTED_HASH MD5=<value>``. It is an error
+      to specify this if ``DOWNLOAD`` is not given a ``<file>``.
 
-  .. versionadded:: 3.14
+    ``RANGE_START <value>``
+      .. versionadded:: 3.24
 
-  Query the symlink ``<linkname>`` and stores the path it points to
-  in the result ``<variable>``.  If ``<linkname>`` does not exist
-  or is not a symlink, CMake issues a fatal error.
+      Offset of the start of the range in file in bytes. Could be omitted to
+      download up to the specified ``RANGE_END``.
 
-  Note that this command returns the raw symlink path and does not resolve
-  a relative path.  The following is an example of how to ensure that an
-  absolute path is obtained:
+    ``RANGE_END <value>``
+      .. versionadded:: 3.24
 
-  .. code-block:: cmake
+      Offset of the end of the range in file in bytes. Could be omitted to
+      download everything from the specified ``RANGE_START`` to the end of
+      file.
 
-    set(linkname "/path/to/foo.sym")
-    file(READ_SYMLINK "${linkname}" result)
-    if(NOT IS_ABSOLUTE "${result}")
-      get_filename_component(dir "${linkname}" DIRECTORY)
-      set(result "${dir}/${result}")
-    endif()
+Locking
+^^^^^^^
 
 .. signature::
-  file(CREATE_LINK <original> <linkname>
-       [RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC])
+  file(LOCK <path> [DIRECTORY] [RELEASE]
+       [GUARD <FUNCTION|FILE|PROCESS>]
+       [RESULT_VARIABLE <variable>]
+       [TIMEOUT <seconds>])
 
-  .. versionadded:: 3.14
+  .. versionadded:: 3.2
 
-  Create a link ``<linkname>`` that points to ``<original>``.
-  It will be a hard link by default, but providing the ``SYMBOLIC`` option
-  results in a symbolic link instead.  Hard links require that ``original``
-  exists and is a file, not a directory.  If ``<linkname>`` already exists,
-  it will be overwritten.
+  Lock a file specified by ``<path>`` if no ``DIRECTORY`` option present and
+  file ``<path>/cmake.lock`` otherwise.  The file will be locked for the scope
+  defined by the ``GUARD`` option (default value is ``PROCESS``).  The
+  ``RELEASE`` option can be used to unlock the file explicitly.  If the
+  ``TIMEOUT`` option is not specified, CMake will wait until the lock succeeds
+  or until a fatal error occurs.  If ``TIMEOUT`` is set to ``0``, locking will
+  be tried once and the result will be reported immediately.  If ``TIMEOUT``
+  is not ``0``, CMake will try to lock the file for the period specified by
+  the ``TIMEOUT <seconds>`` value.  Any errors will be interpreted as fatal if
+  there is no ``RESULT_VARIABLE`` option.  Otherwise, the result will be stored
+  in ``<variable>`` and will be ``0`` on success or an error message on
+  failure.
 
-  The ``<result>`` variable, if specified, receives the status of the
-  operation.  It is set to ``0`` upon success or an error message otherwise.
-  If ``RESULT`` is not specified and the operation fails, a fatal error is
-  emitted.
+  Note that lock is advisory; there is no guarantee that other processes will
+  respect this lock, i.e. lock synchronize two or more CMake instances sharing
+  some modifiable resources. Similar logic applies to the ``DIRECTORY`` option;
+  locking a parent directory doesn't prevent other ``LOCK`` commands from
+  locking any child directory or file.
 
-  Specifying ``COPY_ON_ERROR`` enables copying the file as a fallback if
-  creating the link fails.  It can be useful for handling situations such as
-  ``<original>`` and ``<linkname>`` being on different drives or mount points,
-  which would make them unable to support a hard link.
+  Trying to lock the same file twice is not allowed.  Any intermediate
+  directories and the file itself will be created if they not exist.  The
+  ``GUARD`` and ``TIMEOUT`` options are ignored on the ``RELEASE`` operation.
+
+Archiving
+^^^^^^^^^
 
 .. signature::
-  file(CHMOD <files>... <directories>...
-       [PERMISSIONS <permissions>...]
-       [FILE_PERMISSIONS <permissions>...]
-       [DIRECTORY_PERMISSIONS <permissions>...])
+  file(ARCHIVE_CREATE OUTPUT <archive>
+    PATHS <paths>...
+    [FORMAT <format>]
+    [COMPRESSION <compression>
+     [COMPRESSION_LEVEL <compression-level>]]
+    [MTIME <mtime>]
+    [VERBOSE])
+  :target: ARCHIVE_CREATE
+  :break: verbatim
 
-  .. versionadded:: 3.19
+  .. versionadded:: 3.18
 
-  Set the permissions for the ``<files>...`` and ``<directories>...``
-  specified. Valid permissions are  ``OWNER_READ``, ``OWNER_WRITE``,
-  ``OWNER_EXECUTE``, ``GROUP_READ``, ``GROUP_WRITE``, ``GROUP_EXECUTE``,
-  ``WORLD_READ``, ``WORLD_WRITE``, ``WORLD_EXECUTE``, ``SETUID``, ``SETGID``.
+  Creates the specified ``<archive>`` file with the files and directories
+  listed in ``<paths>``.  Note that ``<paths>`` must list actual files or
+  directories; wildcards are not supported.
 
-  Valid combination of keywords are:
+  Use the ``FORMAT`` option to specify the archive format.  Supported values
+  for ``<format>`` are ``7zip``, ``gnutar``, ``pax``, ``paxr``, ``raw`` and
+  ``zip``.  If ``FORMAT`` is not given, the default format is ``paxr``.
 
-    ``PERMISSIONS``
-      All items are changed.
+  Some archive formats allow the type of compression to be specified.
+  The ``7zip`` and ``zip`` archive formats already imply a specific type of
+  compression.  The other formats use no compression by default, but can be
+  directed to do so with the ``COMPRESSION`` option.  Valid values for
+  ``<compression>`` are ``None``, ``BZip2``, ``GZip``, ``XZ``, and ``Zstd``.
 
-    ``FILE_PERMISSIONS``
-      Only files are changed.
+  .. versionadded:: 3.19
+    The compression level can be specified with the ``COMPRESSION_LEVEL``
+    option.  The ``<compression-level>`` should be between 0-9, with the
+    default being 0.  The ``COMPRESSION`` option must be present when
+    ``COMPRESSION_LEVEL`` is given.
 
-    ``DIRECTORY_PERMISSIONS``
-      Only directories are changed.
+  .. versionadded:: 3.26
+    The ``<compression-level>`` of the ``Zstd`` algorithm can be set
+    between 0-19.
 
-    ``PERMISSIONS`` and ``FILE_PERMISSIONS``
-      ``FILE_PERMISSIONS`` overrides ``PERMISSIONS`` for files.
+  .. note::
+    With ``FORMAT`` set to ``raw``, only one file will be compressed with the
+    compression type specified by ``COMPRESSION``.
 
-    ``PERMISSIONS`` and ``DIRECTORY_PERMISSIONS``
-      ``DIRECTORY_PERMISSIONS`` overrides ``PERMISSIONS`` for directories.
+  The ``VERBOSE`` option enables verbose output for the archive operation.
 
-    ``FILE_PERMISSIONS`` and ``DIRECTORY_PERMISSIONS``
-      Use ``FILE_PERMISSIONS`` for files and ``DIRECTORY_PERMISSIONS`` for
-      directories.
+  To specify the modification time recorded in tarball entries, use
+  the ``MTIME`` option.
 
 .. signature::
-  file(CHMOD_RECURSE <files>... <directories>...
-       [PERMISSIONS <permissions>...]
-       [FILE_PERMISSIONS <permissions>...]
-       [DIRECTORY_PERMISSIONS <permissions>...])
+  file(ARCHIVE_EXTRACT
+    INPUT <archive>
+    [DESTINATION <dir>]
+    [PATTERNS <patterns>...]
+    [LIST_ONLY]
+    [VERBOSE]
+    [TOUCH])
+  :target: ARCHIVE_EXTRACT
 
-  .. versionadded:: 3.19
+  .. versionadded:: 3.18
 
-  Same as :cref:`CHMOD`, but change the permissions of files and directories
-  present in the ``<directories>...`` recursively.
+  Extracts or lists the content of the specified ``<archive>``.
 
+  The directory where the content of the archive will be extracted to can
+  be specified using the ``DESTINATION`` option.  If the directory does not
+  exist, it will be created.  If ``DESTINATION`` is not given, the current
+  binary directory will be used.
 
-Path Conversion
-^^^^^^^^^^^^^^^
+  If required, you may select which files and directories to list or extract
+  from the archive using the specified ``<patterns>``.  Wildcards are
+  supported.  If the ``PATTERNS`` option is not given, the entire archive will
+  be listed or extracted.
 
-.. signature::
-  file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE])
+  ``LIST_ONLY`` will list the files in the archive rather than extract them.
 
-  .. versionadded:: 3.19
+  .. note::
+    The working directory for this subcommand is the ``DESTINATION`` directory
+    (provided or computed) except when ``LIST_ONLY`` is specified. Therefore,
+    outside of script mode, it may be best to provide absolute paths to
+    ``INPUT`` archives as they are unlikely to be extracted where a relative
+    path works.
 
-  Compute the absolute path to an existing file or directory with symlinks
-  resolved.  The options are:
+  .. versionadded:: 3.24
+    The ``TOUCH`` option gives extracted files a current local
+    timestamp instead of extracting file timestamps from the archive.
 
-    ``BASE_DIRECTORY <dir>``
-      If the provided ``<path>`` is a relative path, it is evaluated relative
-      to the given base directory ``<dir>``. If no base directory is provided,
-      the default base directory will be :variable:`CMAKE_CURRENT_SOURCE_DIR`.
+  With ``VERBOSE``, the command will produce verbose output.
 
-    ``EXPAND_TILDE``
-      .. versionadded:: 3.21
+Handling Runtime Binaries
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
-      If the ``<path>`` is ``~`` or starts with ``~/``, the ``~`` is replaced
-      by the user's home directory.  The path to the home directory is obtained
-      from environment variables.  On Windows, the ``USERPROFILE`` environment
-      variable is used, falling back to the ``HOME`` environment variable
-      if ``USERPROFILE`` is not defined.  On all other platforms, only ``HOME``
-      is used.
+.. signature::
+  file(GET_RUNTIME_DEPENDENCIES [...])
 
-  .. versionchanged:: 3.28
+  .. versionadded:: 3.16
 
-    All symlinks are resolved before collapsing ``../`` components.
-    See policy :policy:`CMP0152`.
+  Recursively get the list of libraries depended on by the given files:
 
-.. signature::
-  file(RELATIVE_PATH <variable> <directory> <file>)
+  .. code-block:: cmake
 
-  Compute the relative path from a ``<directory>`` to a ``<file>`` and
-  store it in the ``<variable>``.
+    file(GET_RUNTIME_DEPENDENCIES
+      [RESOLVED_DEPENDENCIES_VAR <deps_var>]
+      [UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>]
+      [CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>]
+      [EXECUTABLES <executable_files>...]
+      [LIBRARIES <library_files>...]
+      [MODULES <module_files>...]
+      [DIRECTORIES <directories>...]
+      [BUNDLE_EXECUTABLE <bundle_executable_file>]
+      [PRE_INCLUDE_REGEXES <regexes>...]
+      [PRE_EXCLUDE_REGEXES <regexes>...]
+      [POST_INCLUDE_REGEXES <regexes>...]
+      [POST_EXCLUDE_REGEXES <regexes>...]
+      [POST_INCLUDE_FILES <files>...]
+      [POST_EXCLUDE_FILES <files>...]
+      )
 
-.. signature::
-  file(TO_CMAKE_PATH "<path>" <variable>)
-  file(TO_NATIVE_PATH "<path>" <variable>)
+  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:
 
-  The ``TO_CMAKE_PATH`` mode converts a native ``<path>`` into a cmake-style
-  path with forward-slashes (``/``).  The input can be a single path or a
-  system search path like ``$ENV{PATH}``.  A search path will be converted
-  to a cmake-style list separated by ``;`` characters.
+  .. code-block:: cmake
 
-  The ``TO_NATIVE_PATH`` mode converts a cmake-style ``<path>`` into a native
-  path with platform-specific slashes (``\`` on Windows hosts and ``/``
-  elsewhere).
+    install(CODE [[
+      file(GET_RUNTIME_DEPENDENCIES
+        # ...
+        )
+      ]])
 
-  Always use double quotes around the ``<path>`` to be sure it is treated
-  as a single argument to this command.
+  The arguments are as follows:
 
-Transfer
-^^^^^^^^
+    ``RESOLVED_DEPENDENCIES_VAR <deps_var>``
+      Name of the variable in which to store the list of resolved dependencies.
 
-.. signature::
-  file(DOWNLOAD <url> [<file>] <options>...)
-  file(UPLOAD <file> <url> <options>...)
+    ``UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_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.
 
-  The ``DOWNLOAD`` subcommand downloads the given ``<url>`` to a local
-  ``<file>``.  The ``UPLOAD`` mode uploads a local ``<file>`` to a given
-  ``<url>``.
+    ``CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_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 ``<conflicting_deps_prefix>_FILENAMES``. For each filename, the list
+      of paths that were found for that filename are stored in
+      ``<conflicting_deps_prefix>_<filename>``.
 
-  .. versionadded:: 3.19
-    If ``<file>`` is not specified for ``file(DOWNLOAD)``, the file is not
-    saved. This can be useful if you want to know if a file can be downloaded
-    (for example, to check that it exists) without actually saving it anywhere.
+    ``EXECUTABLES <executable_files>...``
+      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.
 
-  Options to both ``DOWNLOAD`` and ``UPLOAD`` are:
+    ``LIBRARIES <library_files>...``
+      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.
 
-    ``INACTIVITY_TIMEOUT <seconds>``
-      Terminate the operation after a period of inactivity.
+    ``MODULES <module_files>...``
+      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.
 
-    ``LOG <variable>``
-      Store a human-readable log of the operation in a variable.
+    ``DIRECTORIES <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.
 
-    ``SHOW_PROGRESS``
-      Print progress information as status messages until the operation is
-      complete.
+    ``BUNDLE_EXECUTABLE <bundle_executable_file>``
+      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.
 
-    ``STATUS <variable>``
-      Store the resulting status of the operation in a variable.
-      The status is a ``;`` separated list of length 2.
-      The first element is the numeric return value for the operation,
-      and the second element is a string value for the error.
-      A ``0`` numeric error means no error in the operation.
+  The following arguments specify filters for including or excluding libraries
+  to be resolved. See below for a full description of how they work.
 
-    ``TIMEOUT <seconds>``
-      Terminate the operation after a given total time has elapsed.
+    ``PRE_INCLUDE_REGEXES <regexes>...``
+      List of pre-include regexes through which to filter the names of
+      not-yet-resolved dependencies.
 
-    ``USERPWD <username>:<password>``
-      .. versionadded:: 3.7
+    ``PRE_EXCLUDE_REGEXES <regexes>...``
+      List of pre-exclude regexes through which to filter the names of
+      not-yet-resolved dependencies.
 
-      Set username and password for operation.
+    ``POST_INCLUDE_REGEXES <regexes>...``
+      List of post-include regexes through which to filter the names of
+      resolved dependencies.
 
-    ``HTTPHEADER <HTTP-header>``
-      .. versionadded:: 3.7
+    ``POST_EXCLUDE_REGEXES <regexes>...``
+      List of post-exclude regexes through which to filter the names of
+      resolved dependencies.
 
-      HTTP header for ``DOWNLOAD`` and ``UPLOAD`` operations. ``HTTPHEADER``
-      can be repeated for multiple options:
+    ``POST_INCLUDE_FILES <files>...``
+      .. versionadded:: 3.21
 
-      .. code-block:: cmake
+      List of post-include filenames through which to filter the names of
+      resolved dependencies. Symlinks are resolved when attempting to match
+      these filenames.
 
-        file(DOWNLOAD <url>
-             HTTPHEADER "Authorization: Bearer <auth-token>"
-             HTTPHEADER "UserAgent: Mozilla/5.0")
+    ``POST_EXCLUDE_FILES <files>...``
+      .. versionadded:: 3.21
 
-    ``NETRC <level>``
-      .. versionadded:: 3.11
+      List of post-exclude filenames through which to filter the names of
+      resolved dependencies. Symlinks are resolved when attempting to match
+      these filenames.
 
-      Specify whether the .netrc file is to be used for operation.  If this
-      option is not specified, the value of the :variable:`CMAKE_NETRC`
-      variable will be used instead.
+  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:
 
-      Valid levels are:
+  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.
 
-        ``IGNORED``
-          The .netrc file is ignored.
-          This is the default.
+  2. If the not-yet-resolved dependency matches any of the
+     ``PRE_EXCLUDE_REGEXES``, dependency resolution stops for that dependency.
 
-        ``OPTIONAL``
-          The .netrc file is optional, and information in the URL is preferred.
-          The file will be scanned to find which ever information is not
-          specified in the URL.
+  3. Otherwise, dependency resolution proceeds.
 
-        ``REQUIRED``
-          The .netrc file is required, and information in the URL is ignored.
+  4. ``file(GET_RUNTIME_DEPENDENCIES)`` searches for the dependency according
+     to the linking rules of the platform (see below).
 
-    ``NETRC_FILE <file>``
-      .. versionadded:: 3.11
+  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.
 
-      Specify an alternative .netrc file to the one in your home directory,
-      if the ``NETRC`` level is ``OPTIONAL`` or ``REQUIRED``. If this option
-      is not specified, the value of the :variable:`CMAKE_NETRC_FILE` variable
-      will be used instead.
+  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.
 
-    ``TLS_VERSION <min>``
-      .. versionadded:: 3.30
+  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.
 
-      Specify minimum TLS version for ``https://`` URLs.
-      If this option is not specified, the value of the
-      :variable:`CMAKE_TLS_VERSION` variable or :envvar:`CMAKE_TLS_VERSION`
-      environment variable will be used instead.
-      See :variable:`CMAKE_TLS_VERSION` for allowed values.
+  Different platforms have different rules for how dependencies are resolved.
+  These specifics are described here.
 
-    ``TLS_VERIFY <ON|OFF>``
-      Specify whether to verify the server certificate for ``https://`` URLs.
-      The default is to *not* verify. If this option is not specified, the
-      value of the :variable:`CMAKE_TLS_VERIFY` variable will be used instead.
+  On Linux platforms, library resolution works as follows:
 
-      .. versionadded:: 3.18
-        Added support to ``file(UPLOAD)``.
+  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).
 
-    ``TLS_CAINFO <file>``
-      Specify a custom Certificate Authority file for ``https://`` URLs.
-      If this option is not specified, the value of the
-      :variable:`CMAKE_TLS_CAINFO` variable will be used instead.
+  5. Otherwise, the dependency is unresolved.
 
-      .. versionadded:: 3.18
-        Added support to ``file(UPLOAD)``.
+  On Windows platforms, library resolution works as follows:
 
-  For ``https://`` URLs CMake must be built with OpenSSL support.  ``TLS/SSL``
-  certificates are not checked by default.  Set ``TLS_VERIFY`` to ``ON`` to
-  check certificates.
+  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:
 
-  Additional options to ``DOWNLOAD`` are:
+     .. code-block:: cmake
 
-    ``EXPECTED_HASH <algorithm>=<value>``
-      Verify that the downloaded content hash matches the expected value, where
-      ``<algorithm>`` is one of the algorithms supported by :cref:`<HASH>`.
-      If the file already exists and matches the hash, the download is skipped.
-      If the file already exists and does not match the hash, the file is
-      downloaded again. If after download the file does not match the hash, the
-      operation fails with an error. It is an error to specify this option if
-      ``DOWNLOAD`` is not given a ``<file>``.
+       file(GET_RUNTIME_DEPENDENCIES
+         # ...
+         PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$"
+         )
 
-    ``EXPECTED_MD5 <value>``
-      Historical short-hand for ``EXPECTED_HASH MD5=<value>``. It is an error
-      to specify this if ``DOWNLOAD`` is not given a ``<file>``.
+     Converting the DLL name to lowercase allows the regexes to only match
+     lowercase names, thus simplifying the regex. For example:
 
-    ``RANGE_START <value>``
-      .. versionadded:: 3.24
+     .. code-block:: cmake
 
-      Offset of the start of the range in file in bytes. Could be omitted to
-      download up to the specified ``RANGE_END``.
+       file(GET_RUNTIME_DEPENDENCIES
+         # ...
+         PRE_INCLUDE_REGEXES "^mylibrary\\.dll$"
+         )
 
-    ``RANGE_END <value>``
-      .. versionadded:: 3.24
+     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``.)
 
-      Offset of the end of the range in file in bytes. Could be omitted to
-      download everything from the specified ``RANGE_START`` to the end of
-      file.
+     .. versionchanged:: 3.27
 
-Locking
-^^^^^^^
+       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.
 
-.. signature::
-  file(LOCK <path> [DIRECTORY] [RELEASE]
-       [GUARD <FUNCTION|FILE|PROCESS>]
-       [RESULT_VARIABLE <variable>]
-       [TIMEOUT <seconds>])
+       Prior to CMake 3.27, the results were reported with lowercase DLL
+       file names, but the directory portion retained its casing.
 
-  .. versionadded:: 3.2
+  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.
 
-  Lock a file specified by ``<path>`` if no ``DIRECTORY`` option present and
-  file ``<path>/cmake.lock`` otherwise.  The file will be locked for the scope
-  defined by the ``GUARD`` option (default value is ``PROCESS``).  The
-  ``RELEASE`` option can be used to unlock the file explicitly.  If the
-  ``TIMEOUT`` option is not specified, CMake will wait until the lock succeeds
-  or until a fatal error occurs.  If ``TIMEOUT`` is set to ``0``, locking will
-  be tried once and the result will be reported immediately.  If ``TIMEOUT``
-  is not ``0``, CMake will try to lock the file for the period specified by
-  the ``TIMEOUT <seconds>`` value.  Any errors will be interpreted as fatal if
-  there is no ``RESULT_VARIABLE`` option.  Otherwise, the result will be stored
-  in ``<variable>`` and will be ``0`` on success or an error message on
-  failure.
+  3. Otherwise, if the library exists in the same directory as the depending
+     file, the dependency is resolved to that file.
 
-  Note that lock is advisory; there is no guarantee that other processes will
-  respect this lock, i.e. lock synchronize two or more CMake instances sharing
-  some modifiable resources. Similar logic applies to the ``DIRECTORY`` option;
-  locking a parent directory doesn't prevent other ``LOCK`` commands from
-  locking any child directory or 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.
 
-  Trying to lock the same file twice is not allowed.  Any intermediate
-  directories and the file itself will be created if they not exist.  The
-  ``GUARD`` and ``TIMEOUT`` options are ignored on the ``RELEASE`` operation.
+  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.
 
-Archiving
-^^^^^^^^^
+  6. Otherwise, the dependency is unresolved.
 
-.. signature::
-  file(ARCHIVE_CREATE OUTPUT <archive>
-    PATHS <paths>...
-    [FORMAT <format>]
-    [COMPRESSION <compression>
-     [COMPRESSION_LEVEL <compression-level>]]
-    [MTIME <mtime>]
-    [VERBOSE])
-  :target: ARCHIVE_CREATE
-  :break: verbatim
+  On Apple platforms, library resolution works as follows:
 
-  .. versionadded:: 3.18
+  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.
 
-  Creates the specified ``<archive>`` file with the files and directories
-  listed in ``<paths>``.  Note that ``<paths>`` must list actual files or
-  directories; wildcards are not supported.
+  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.
 
-  Use the ``FORMAT`` option to specify the archive format.  Supported values
-  for ``<format>`` are ``7zip``, ``gnutar``, ``pax``, ``paxr``, ``raw`` and
-  ``zip``.  If ``FORMAT`` is not given, the default format is ``paxr``.
+  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.
 
-  Some archive formats allow the type of compression to be specified.
-  The ``7zip`` and ``zip`` archive formats already imply a specific type of
-  compression.  The other formats use no compression by default, but can be
-  directed to do so with the ``COMPRESSION`` option.  Valid values for
-  ``<compression>`` are ``None``, ``BZip2``, ``GZip``, ``XZ``, and ``Zstd``.
+  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.
 
-  .. versionadded:: 3.19
-    The compression level can be specified with the ``COMPRESSION_LEVEL``
-    option.  The ``<compression-level>`` should be between 0-9, with the
-    default being 0.  The ``COMPRESSION`` option must be present when
-    ``COMPRESSION_LEVEL`` is given.
+  5. Otherwise, if the dependency is an absolute file that exists,
+     the dependency is resolved to that file.
 
-  .. versionadded:: 3.26
-    The ``<compression-level>`` of the ``Zstd`` algorithm can be set
-    between 0-19.
+  6. Otherwise, the dependency is unresolved.
 
-  .. note::
-    With ``FORMAT`` set to ``raw``, only one file will be compressed with the
-    compression type specified by ``COMPRESSION``.
+  This function accepts several variables that determine which tool is used for
+  dependency resolution:
 
-  The ``VERBOSE`` option enables verbose output for the archive operation.
+  .. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM
 
-  To specify the modification time recorded in tarball entries, use
-  the ``MTIME`` option.
+    Determines which operating system and executable format the files are built
+    for. This could be one of several values:
 
-.. signature::
-  file(ARCHIVE_EXTRACT
-    INPUT <archive>
-    [DESTINATION <dir>]
-    [PATTERNS <patterns>...]
-    [LIST_ONLY]
-    [VERBOSE]
-    [TOUCH])
-  :target: ARCHIVE_EXTRACT
+    * ``linux+elf``
+    * ``windows+pe``
+    * ``macos+macho``
 
-  .. versionadded:: 3.18
+    If this variable is not specified, it is determined automatically by system
+    introspection.
 
-  Extracts or lists the content of the specified ``<archive>``.
+  .. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL
 
-  The directory where the content of the archive will be extracted to can
-  be specified using the ``DESTINATION`` option.  If the directory does not
-  exist, it will be created.  If ``DESTINATION`` is not given, the current
-  binary directory will be used.
+    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`:
 
-  If required, you may select which files and directories to list or extract
-  from the archive using the specified ``<patterns>``.  Wildcards are
-  supported.  If the ``PATTERNS`` option is not given, the entire archive will
-  be listed or extracted.
+    ================================================= =============================================
+       ``CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM``       ``CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL``
+    ================================================= =============================================
+    ``linux+elf``                                     ``objdump``
+    ``windows+pe``                                    ``objdump`` or ``dumpbin``
+    ``macos+macho``                                   ``otool``
+    ================================================= =============================================
 
-  ``LIST_ONLY`` will list the files in the archive rather than extract them.
+    If this variable is not specified, it is determined automatically by system
+    introspection.
 
-  .. note::
-    The working directory for this subcommand is the ``DESTINATION`` directory
-    (provided or computed) except when ``LIST_ONLY`` is specified. Therefore,
-    outside of script mode, it may be best to provide absolute paths to
-    ``INPUT`` archives as they are unlikely to be extracted where a relative
-    path works.
+  .. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND
 
-  .. versionadded:: 3.24
-    The ``TOUCH`` option gives extracted files a current local
-    timestamp instead of extracting file timestamps from the archive.
+    Determines the path to the tool to use for dependency resolution. This is
+    the actual path to ``objdump``, ``dumpbin``, or ``otool``.
 
-  With ``VERBOSE``, the command will produce verbose output.
+    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.
-- 
cgit v0.12