|
|
|
|
@ -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_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>...]]
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
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 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.
|
|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
^^^^^^^
|
|
|
|
|
|
|
|
|
|
@ -235,6 +503,11 @@ regular expressions, but much simpler. If ``RELATIVE`` flag is
|
|
|
|
|
specified, the results will be returned as relative paths to the given
|
|
|
|
|
path. The results will be ordered lexicographically.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
|
Felix Geyer
5 years ago