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.
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 @@
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 @@
file(`ARCHIVE_CREATE`_ OUTPUT <archive> PATHS <paths>... [...])
file(`ARCHIVE_EXTRACT`_ INPUT <archive> [...])
+ `Handling Runtime Binaries`_
+ file(`GET_RUNTIME_DEPENDENCIES`_ [...])
+
+
Reading
^^^^^^^
@@ -157,323 +160,6 @@
See the :command:`string(TIMESTAMP)` command for documentation of
the ``<format>`` and ``UTC`` options.
-.. signature::
- file(GET_RUNTIME_DEPENDENCIES [...])
-
- .. versionadded:: 3.16
-
- Recursively get the list of libraries depended on by the given files:
-
- .. code-block:: cmake
-
- 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>...]
- )
-
- Please note that this sub-command is not intended to be used in project mode.
- It is intended for use at install time, either from code generated by the
- :command:`install(RUNTIME_DEPENDENCY_SET)` command, or from code provided by
- the project via :command:`install(CODE)` or :command:`install(SCRIPT)`.
- For example:
-
- .. code-block:: cmake
-
- install(CODE [[
- file(GET_RUNTIME_DEPENDENCIES
- # ...
- )
- ]])
-
- The arguments are as follows:
-
- ``RESOLVED_DEPENDENCIES_VAR <deps_var>``
- Name of the variable in which to store the list of resolved dependencies.
-
- ``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.
-
- ``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>``.
-
- ``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.
-
- ``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.
-
- ``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.
-
- ``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.
-
- ``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.
-
- The following arguments specify filters for including or excluding libraries
- to be resolved. See below for a full description of how they work.
-
- ``PRE_INCLUDE_REGEXES <regexes>...``
- List of pre-include regexes through which to filter the names of
- not-yet-resolved dependencies.
-
- ``PRE_EXCLUDE_REGEXES <regexes>...``
- List of pre-exclude regexes through which to filter the names of
- not-yet-resolved dependencies.
-
- ``POST_INCLUDE_REGEXES <regexes>...``
- List of post-include regexes through which to filter the names of
- resolved dependencies.
-
- ``POST_EXCLUDE_REGEXES <regexes>...``
- List of post-exclude regexes through which to filter the names of
- resolved dependencies.
-
- ``POST_INCLUDE_FILES <files>...``
- .. versionadded:: 3.21
-
- List of post-include filenames through which to filter the names of
- resolved dependencies. Symlinks are resolved when attempting to match
- these filenames.
-
- ``POST_EXCLUDE_FILES <files>...``
- .. versionadded:: 3.21
-
- List of post-exclude filenames through which to filter the names of
- resolved dependencies. Symlinks are resolved when attempting to match
- these filenames.
-
- These arguments can be used to exclude unwanted system libraries when
- resolving the dependencies, or to include libraries from a specific
- directory. The filtering works as follows:
-
- 1. If the not-yet-resolved dependency matches any of the
- ``PRE_INCLUDE_REGEXES``, steps 2 and 3 are skipped, and the dependency
- resolution proceeds to step 4.
-
- 2. If the not-yet-resolved dependency matches any of the
- ``PRE_EXCLUDE_REGEXES``, dependency resolution stops for that dependency.
-
- 3. Otherwise, dependency resolution proceeds.
-
- 4. ``file(GET_RUNTIME_DEPENDENCIES)`` searches for the dependency according
- to the linking rules of the platform (see below).
-
- 5. If the dependency is found, and its full path matches one of the
- ``POST_INCLUDE_REGEXES`` or ``POST_INCLUDE_FILES``, the full path is added
- to the resolved dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)``
- recursively resolves that library's own dependencies. Otherwise, resolution
- proceeds to step 6.
-
- 6. If the dependency is found, but its full path matches one of the
- ``POST_EXCLUDE_REGEXES`` or ``POST_EXCLUDE_FILES``, it is not added to the
- resolved dependencies, and dependency resolution stops for that dependency.
-
- 7. If the dependency is found, and its full path does not match either
- ``POST_INCLUDE_REGEXES``, ``POST_INCLUDE_FILES``, ``POST_EXCLUDE_REGEXES``,
- or ``POST_EXCLUDE_FILES``, the full path is added to the resolved
- dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` recursively resolves
- that library's own dependencies.
-
- Different platforms have different rules for how dependencies are resolved.
- These specifics are described here.
-
- On Linux platforms, library resolution works as follows:
-
- 1. If the depending file does not have any ``RUNPATH`` entries, and the
- library exists in one of the depending file's ``RPATH`` entries, or its
- parents', in that order, the dependency is resolved to that file.
- 2. Otherwise, if the depending file has any ``RUNPATH`` entries, and the
- library exists in one of those entries, the dependency is resolved to that
- file.
- 3. Otherwise, if the library exists in one of the directories listed by
- ``ldconfig``, the dependency is resolved to that file.
- 4. Otherwise, if the library exists in one of the ``DIRECTORIES`` entries,
- the dependency is resolved to that file. In this case, a warning is
- issued, because finding a file in one of the ``DIRECTORIES`` means that
- the depending file is not complete (it does not list all the directories
- from which it pulls dependencies).
-
- 5. Otherwise, the dependency is unresolved.
-
- On Windows platforms, library resolution works as follows:
-
- 1. 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:
-
- .. code-block:: cmake
-
- file(GET_RUNTIME_DEPENDENCIES
- # ...
- PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$"
- )
-
- Converting the DLL name to lowercase allows the regexes to only match
- lowercase names, thus simplifying the regex. For example:
-
- .. code-block:: cmake
-
- file(GET_RUNTIME_DEPENDENCIES
- # ...
- PRE_INCLUDE_REGEXES "^mylibrary\\.dll$"
- )
-
- This regex will match ``mylibrary.dll`` regardless of how it is cased,
- either on disk or in the depending file. (For example, it will match
- ``mylibrary.dll``, ``MyLibrary.dll``, and ``MYLIBRARY.DLL``.)
-
- .. versionchanged:: 3.27
-
- 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.
-
- Prior to CMake 3.27, the results were reported with lowercase DLL
- file names, but the directory portion retained its casing.
-
- 2. (**Not yet implemented**) If the depending file is a Windows Store app,
- and the dependency is listed as a dependency in the application's package
- manifest, the dependency is resolved to that file.
-
- 3. Otherwise, if the library exists in the same directory as the depending
- file, the dependency is resolved to that file.
-
- 4. Otherwise, if the library exists in either the operating system's
- ``system32`` directory or the ``Windows`` directory, in that order, the
- dependency is resolved to that file.
-
- 5. Otherwise, if the library exists in one of the directories specified by
- ``DIRECTORIES``, in the order they are listed, the dependency is resolved
- to that file. In this case, a warning is not issued, because searching
- other directories is a normal part of Windows library resolution.
-
- 6. Otherwise, the dependency is unresolved.
-
- On Apple platforms, library resolution works as follows:
-
- 1. If the dependency starts with ``@executable_path/``, and an
- ``EXECUTABLES`` argument is in the process of being resolved, and
- replacing ``@executable_path/`` with the directory of the executable
- yields an existing file, the dependency is resolved to that file.
-
- 2. Otherwise, if the dependency starts with ``@executable_path/``, and there
- is a ``BUNDLE_EXECUTABLE`` argument, and replacing ``@executable_path/``
- with the directory of the bundle executable yields an existing file, the
- dependency is resolved to that file.
-
- 3. Otherwise, if the dependency starts with ``@loader_path/``, and replacing
- ``@loader_path/`` with the directory of the depending file yields an
- existing file, the dependency is resolved to that file.
-
- 4. Otherwise, if the dependency starts with ``@rpath/``, and replacing
- ``@rpath/`` with one of the ``RPATH`` entries of the depending file
- yields an existing file, the dependency is resolved to that file.
- Note that ``RPATH`` entries that start with ``@executable_path/`` or
- ``@loader_path/`` also have these items replaced with the appropriate
- path.
-
- 5. Otherwise, if the dependency is an absolute file that exists,
- the dependency is resolved to that file.
-
- 6. Otherwise, the dependency is unresolved.
-
- This function accepts several variables that determine which tool is used for
- dependency resolution:
-
- .. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM
-
- Determines which operating system and executable format the files are built
- for. This could be one of several values:
-
- * ``linux+elf``
- * ``windows+pe``
- * ``macos+macho``
-
- If this variable is not specified, it is determined automatically by system
- introspection.
-
- .. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL
-
- Determines the tool to use for dependency resolution. It could be one of
- several values, depending on the value of
- :variable:`CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`:
-
- ================================================= =============================================
- ``CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`` ``CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL``
- ================================================= =============================================
- ``linux+elf`` ``objdump``
- ``windows+pe`` ``objdump`` or ``dumpbin``
- ``macos+macho`` ``otool``
- ================================================= =============================================
-
- If this variable is not specified, it is determined automatically by system
- introspection.
-
- .. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND
-
- Determines the path to the tool to use for dependency resolution. This is
- the actual path to ``objdump``, ``dumpbin``, or ``otool``.
-
- If this variable is not specified, it is determined by the value of
- ``CMAKE_OBJDUMP`` if set, else by system introspection.
-
- .. versionadded:: 3.18
- Use ``CMAKE_OBJDUMP`` if set.
-
Writing
^^^^^^^
@@ -1275,3 +961,323 @@
timestamp instead of extracting file timestamps from the archive.
With ``VERBOSE``, the command will produce verbose output.
+
+Handling Runtime Binaries
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. signature::
+ file(GET_RUNTIME_DEPENDENCIES [...])
+
+ .. versionadded:: 3.16
+
+ Recursively get the list of libraries depended on by the given files:
+
+ .. code-block:: cmake
+
+ 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>...]
+ )
+
+ Please note that this sub-command is not intended to be used in project mode.
+ It is intended for use at install time, either from code generated by the
+ :command:`install(RUNTIME_DEPENDENCY_SET)` command, or from code provided by
+ the project via :command:`install(CODE)` or :command:`install(SCRIPT)`.
+ For example:
+
+ .. code-block:: cmake
+
+ install(CODE [[
+ file(GET_RUNTIME_DEPENDENCIES
+ # ...
+ )
+ ]])
+
+ The arguments are as follows:
+
+ ``RESOLVED_DEPENDENCIES_VAR <deps_var>``
+ Name of the variable in which to store the list of resolved dependencies.
+
+ ``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.
+
+ ``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>``.
+
+ ``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.
+
+ ``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.
+
+ ``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.
+
+ ``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.
+
+ ``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.
+
+ The following arguments specify filters for including or excluding libraries
+ to be resolved. See below for a full description of how they work.
+
+ ``PRE_INCLUDE_REGEXES <regexes>...``
+ List of pre-include regexes through which to filter the names of
+ not-yet-resolved dependencies.
+
+ ``PRE_EXCLUDE_REGEXES <regexes>...``
+ List of pre-exclude regexes through which to filter the names of
+ not-yet-resolved dependencies.
+
+ ``POST_INCLUDE_REGEXES <regexes>...``
+ List of post-include regexes through which to filter the names of
+ resolved dependencies.
+
+ ``POST_EXCLUDE_REGEXES <regexes>...``
+ List of post-exclude regexes through which to filter the names of
+ resolved dependencies.
+
+ ``POST_INCLUDE_FILES <files>...``
+ .. versionadded:: 3.21
+
+ List of post-include filenames through which to filter the names of
+ resolved dependencies. Symlinks are resolved when attempting to match
+ these filenames.
+
+ ``POST_EXCLUDE_FILES <files>...``
+ .. versionadded:: 3.21
+
+ List of post-exclude filenames through which to filter the names of
+ resolved dependencies. Symlinks are resolved when attempting to match
+ these filenames.
+
+ These arguments can be used to exclude unwanted system libraries when
+ resolving the dependencies, or to include libraries from a specific
+ directory. The filtering works as follows:
+
+ 1. If the not-yet-resolved dependency matches any of the
+ ``PRE_INCLUDE_REGEXES``, steps 2 and 3 are skipped, and the dependency
+ resolution proceeds to step 4.
+
+ 2. If the not-yet-resolved dependency matches any of the
+ ``PRE_EXCLUDE_REGEXES``, dependency resolution stops for that dependency.
+
+ 3. Otherwise, dependency resolution proceeds.
+
+ 4. ``file(GET_RUNTIME_DEPENDENCIES)`` searches for the dependency according
+ to the linking rules of the platform (see below).
+
+ 5. If the dependency is found, and its full path matches one of the
+ ``POST_INCLUDE_REGEXES`` or ``POST_INCLUDE_FILES``, the full path is added
+ to the resolved dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)``
+ recursively resolves that library's own dependencies. Otherwise, resolution
+ proceeds to step 6.
+
+ 6. If the dependency is found, but its full path matches one of the
+ ``POST_EXCLUDE_REGEXES`` or ``POST_EXCLUDE_FILES``, it is not added to the
+ resolved dependencies, and dependency resolution stops for that dependency.
+
+ 7. If the dependency is found, and its full path does not match either
+ ``POST_INCLUDE_REGEXES``, ``POST_INCLUDE_FILES``, ``POST_EXCLUDE_REGEXES``,
+ or ``POST_EXCLUDE_FILES``, the full path is added to the resolved
+ dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` recursively resolves
+ that library's own dependencies.
+
+ Different platforms have different rules for how dependencies are resolved.
+ These specifics are described here.
+
+ On Linux platforms, library resolution works as follows:
+
+ 1. If the depending file does not have any ``RUNPATH`` entries, and the
+ library exists in one of the depending file's ``RPATH`` entries, or its
+ parents', in that order, the dependency is resolved to that file.
+ 2. Otherwise, if the depending file has any ``RUNPATH`` entries, and the
+ library exists in one of those entries, the dependency is resolved to that
+ file.
+ 3. Otherwise, if the library exists in one of the directories listed by
+ ``ldconfig``, the dependency is resolved to that file.
+ 4. Otherwise, if the library exists in one of the ``DIRECTORIES`` entries,
+ the dependency is resolved to that file. In this case, a warning is
+ issued, because finding a file in one of the ``DIRECTORIES`` means that
+ the depending file is not complete (it does not list all the directories
+ from which it pulls dependencies).
+
+ 5. Otherwise, the dependency is unresolved.
+
+ On Windows platforms, library resolution works as follows:
+
+ 1. 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:
+
+ .. code-block:: cmake
+
+ file(GET_RUNTIME_DEPENDENCIES
+ # ...
+ PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$"
+ )
+
+ Converting the DLL name to lowercase allows the regexes to only match
+ lowercase names, thus simplifying the regex. For example:
+
+ .. code-block:: cmake
+
+ file(GET_RUNTIME_DEPENDENCIES
+ # ...
+ PRE_INCLUDE_REGEXES "^mylibrary\\.dll$"
+ )
+
+ This regex will match ``mylibrary.dll`` regardless of how it is cased,
+ either on disk or in the depending file. (For example, it will match
+ ``mylibrary.dll``, ``MyLibrary.dll``, and ``MYLIBRARY.DLL``.)
+
+ .. versionchanged:: 3.27
+
+ 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.
+
+ Prior to CMake 3.27, the results were reported with lowercase DLL
+ file names, but the directory portion retained its casing.
+
+ 2. (**Not yet implemented**) If the depending file is a Windows Store app,
+ and the dependency is listed as a dependency in the application's package
+ manifest, the dependency is resolved to that file.
+
+ 3. Otherwise, if the library exists in the same directory as the depending
+ file, the dependency is resolved to that file.
+
+ 4. Otherwise, if the library exists in either the operating system's
+ ``system32`` directory or the ``Windows`` directory, in that order, the
+ dependency is resolved to that file.
+
+ 5. Otherwise, if the library exists in one of the directories specified by
+ ``DIRECTORIES``, in the order they are listed, the dependency is resolved
+ to that file. In this case, a warning is not issued, because searching
+ other directories is a normal part of Windows library resolution.
+
+ 6. Otherwise, the dependency is unresolved.
+
+ On Apple platforms, library resolution works as follows:
+
+ 1. If the dependency starts with ``@executable_path/``, and an
+ ``EXECUTABLES`` argument is in the process of being resolved, and
+ replacing ``@executable_path/`` with the directory of the executable
+ yields an existing file, the dependency is resolved to that file.
+
+ 2. Otherwise, if the dependency starts with ``@executable_path/``, and there
+ is a ``BUNDLE_EXECUTABLE`` argument, and replacing ``@executable_path/``
+ with the directory of the bundle executable yields an existing file, the
+ dependency is resolved to that file.
+
+ 3. Otherwise, if the dependency starts with ``@loader_path/``, and replacing
+ ``@loader_path/`` with the directory of the depending file yields an
+ existing file, the dependency is resolved to that file.
+
+ 4. Otherwise, if the dependency starts with ``@rpath/``, and replacing
+ ``@rpath/`` with one of the ``RPATH`` entries of the depending file
+ yields an existing file, the dependency is resolved to that file.
+ Note that ``RPATH`` entries that start with ``@executable_path/`` or
+ ``@loader_path/`` also have these items replaced with the appropriate
+ path.
+
+ 5. Otherwise, if the dependency is an absolute file that exists,
+ the dependency is resolved to that file.
+
+ 6. Otherwise, the dependency is unresolved.
+
+ This function accepts several variables that determine which tool is used for
+ dependency resolution:
+
+ .. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM
+
+ Determines which operating system and executable format the files are built
+ for. This could be one of several values:
+
+ * ``linux+elf``
+ * ``windows+pe``
+ * ``macos+macho``
+
+ If this variable is not specified, it is determined automatically by system
+ introspection.
+
+ .. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL
+
+ Determines the tool to use for dependency resolution. It could be one of
+ several values, depending on the value of
+ :variable:`CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`:
+
+ ================================================= =============================================
+ ``CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`` ``CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL``
+ ================================================= =============================================
+ ``linux+elf`` ``objdump``
+ ``windows+pe`` ``objdump`` or ``dumpbin``
+ ``macos+macho`` ``otool``
+ ================================================= =============================================
+
+ If this variable is not specified, it is determined automatically by system
+ introspection.
+
+ .. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND
+
+ Determines the path to the tool to use for dependency resolution. This is
+ the actual path to ``objdump``, ``dumpbin``, or ``otool``.
+
+ If this variable is not specified, it is determined by the value of
+ ``CMAKE_OBJDUMP`` if set, else by system introspection.
+
+ .. versionadded:: 3.18
+ Use ``CMAKE_OBJDUMP`` if set.
