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.
This commit is contained in:
Joachim Wuttke (h)
parent
30fd6df0b1
commit
d2d2ffe1c1
@ -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,323 +160,6 @@ Reading
|
||||
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 @@ Archiving
|
||||
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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user