mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-06 05:40:54 -06:00
Code Issues Packages Projects Releases Wiki Activity

file: Add GET_RUNTIME_DEPENDENCIES mode

Browse Source 
Co-Authored-by: Bryon Bean <bryon.bean@kitware.com>
This commit is contained in:
Kyle Edwards
2019-03-14 11:58:34 -04:00
parent f36719111d
commit 1f9ef25130
88 changed files with 3684 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

268
Help/command/file.rst
View File

@@ -13,6 +13,7 @@ Synopsis
file(`STRINGS`_ <filename> <out-var> [...])
file(`\<HASH\> <HASH_>`_ <filename> <out-var>)
file(`TIMESTAMP`_ <filename> <out-var> [...])
file(`GET_RUNTIME_DEPENDENCIES`_ [...])
`Writing`_
file({`WRITE`_ | `APPEND`_} <filename> <content>...)
@@ -130,6 +131,273 @@ timestamp variable will be set to the empty string ("").
See the :command:`string(TIMESTAMP)` command for documentation of
the ``<format>`` and ``UTC`` options.
.. _GET_RUNTIME_DEPENDENCIES:
.. code-block:: cmake
file(GET_RUNTIME_DEPENDENCIES
[RESOLVED_DEPENDENCIES_VAR <deps_var>]
[UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>]
[CONFLICTING_DEPENDENICES_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>...]]
)
Recursively get the list of libraries depended on by the given files.
Please note that this sub-command is not intended to be used in project mode.
Instead, use it in an :command:`install(CODE)` or :command:`install(SCRIPT)`
block. 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 ``STATIC`` libraries, ``MODULE`` s, or ``SHARED`` libraries 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`` s, 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_EXECTUBLE <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.
These arguments can be used to blacklist unwanted system libraries when
resolving the dependencies, or to whitelist 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``, 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``, 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`` or ``POST_EXCLUDE_REGEXES``, the full path is added
to the resolved dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)``
recursively resolves that library's own dependencies.
Different platforms have different rules for how dependencies are resolved.
These specifics are described here.
On Linux platforms, library resolution works as follows:
1. If the depending file does not have any ``RUNPATH`` entries, and the library
exists in one of the depending file's ``RPATH`` entries, or its parents', in
that order, the dependency is resolved to that file.
2. Otherwise, if the depending file has any ``RUNPATH`` entries, and the
library exists in one of those entries, the dependency is resolved to that
file.
3. Otherwise, if the library exists in one of the directories listed by
``ldconfig``, the dependency is resolved to that file.
4. Otherwise, if the library exists in one of the ``DIRECTORIES`` entries, the
dependency is resolved to that file. In this case, a warning is issued,
because finding a file in one of the ``DIRECTORIES`` means that the
depending file is not complete (it does not list all the directories from
which it pulls dependencies.)
5. Otherwise, the dependency is unresolved.
On Windows platforms, library resolution works as follows:
1. The dependent DLL name is converted to lowercase. Windows DLL names are
case-insensitive, and some linkers mangle the case of the DLL dependency
names. However, this makes it more difficult for ``PRE_INCLUDE_REGEXES``,
``PRE_EXCLUDE_REGEXES``, ``POST_INCLUDE_REGEXES``, and
``POST_EXCLUDE_REGEXES`` to properly filter DLL names - every regex would
have to check for both uppercase and lowercase letters. For example:
.. code-block:: cmake
file(GET_RUNTIME_DEPENDENCIES
# ...
PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$"
)
Converting the DLL name to lowercase allows the regexes to only match
lowercase names, thus simplifying the regex. For example:
.. code-block:: cmake
file(GET_RUNTIME_DEPENDENCIES
# ...
PRE_INCLUDE_REGEXES "^mylibrary\\.dll$"
)
This regex will match ``mylibrary.dll`` regardless of how it is cased,
either on disk or in the depending file. (For example, it will match
``mylibrary.dll``, ``MyLibrary.dll``, and ``MYLIBRARY.DLL``.)
Please note that the directory portion of any resolved DLLs retains its
casing and is not converted to lowercase. Only the filename portion is
converted.
2. (**Not yet implemented**) If the depending file is a Windows Store app, and
the dependency is listed as a dependency in the application's package
manifest, the dependency is resolved to that file.
3. Otherwise, if the library exists in the same directory as the depending
file, the dependency is resolved to that file.
4. Otherwise, if the library exists in either the operating system's
``system32`` directory or the ``Windows`` directory, in that order, the
dependency is resolved to that file.
5. Otherwise, if the library exists in one of the directories specified by
``DIRECTORIES``, in the order they are listed, the dependency is resolved to
that file. (In this case, a warning is not issued, because searching other
directories is a normal part of Windows library resolution.)
6. Otherwise, the dependency is unresolved.
On Apple platforms, library resolution works as follows:
1. If the dependency starts with ``@executable_path/``, and an ``EXECUTABLES``
argument is in the process of being resolved, and replacing
``@executable_path/`` with the directory of the executable yields an
existing file, the dependency is resolved to that file.
2. Otherwise, if the dependency starts with ``@executable_path/``, and there is
a ``BUNDLE_EXECUTABLE`` argument, and replacing ``@executable_path/`` with
the directory of the bundle executable yields an existing file, the
dependency is resolved to that file.
3. Otherwise, if the dependency starts with ``@loader_path/``, and replacing
``@loader_path/`` with the directory of the depending file yields an
existing file, the dependency is resolved to that file.
4. Otherwise, if the dependency starts with ``@rpath/``, and replacing
``@rpath/`` with one of the ``RPATH`` entries of the depending file yields
an existing file, the dependency is resolved to that file. (Note that
``RPATH`` entries that start with ``@executable_path/`` or ``@loader_path/``
also have these items replaced with the appropriate path.)
5. Otherwise, if the dependency is an absolute file that exists, the dependency
is resolved to that file.
6. Otherwise, the dependency is unresolved.
This function accepts several variables that determine which tool is used for
dependency resolution:
.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM
Determines which operating system and executable format the files are built
for. This could be one of several values:
* ``linux+elf``
* ``windows+pe``
* ``macos+macho``
If this variable is not specified, it is determined automatically by system
introspection.
.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL
Determines the tool to use for dependency resolution. It could be one of
several values, depending on the value of
:variable:`CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`:
================================================= =============================================
``CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`` ``CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL``
================================================= =============================================
``linux+elf`` ``objdump``
``windows+pe`` ``dumpbin``
``windows+pe`` ``objdump``
``macos+macho`` ``otool``
================================================= =============================================
If this variable is not specified, it is determined automatically by system
introspection.
.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND
Determines the path to the tool to use for dependency resolution. This is the
actual path to ``objdump``, ``dumpbin``, or ``otool``.
If this variable is not specified, it is determined automatically by system
introspection.
Writing
^^^^^^^