GetPrerequisites: Update documentation
This updates the module documentation to ease the upgrade path to file(GET_RUNTIME_DEPENDENCIES) and syncs formatting as used in other documentation pages. Lowercase style is used for functions, some missing arguments added to signatures, and examples section added.
This commit is contained in:
Peter Kokot
parent
212b380718
commit
d6e1d220a0
@ -9,170 +9,239 @@ GetPrerequisites
|
|||||||
|
|
||||||
Use :command:`file(GET_RUNTIME_DEPENDENCIES)` instead.
|
Use :command:`file(GET_RUNTIME_DEPENDENCIES)` instead.
|
||||||
|
|
||||||
Functions to analyze and list executable file prerequisites.
|
This module provides functions to analyze and list the dependencies
|
||||||
|
(prerequisites) of executable or shared library files. These functions list the
|
||||||
|
shared libraries (``.dll``, ``.dylib``, or ``.so`` files) required by an
|
||||||
|
executable or shared library.
|
||||||
|
|
||||||
This module provides functions to list the .dll, .dylib or .so files
|
It determines dependencies using the following platform-specific tools:
|
||||||
that an executable or shared library file depends on. (Its
|
|
||||||
prerequisites.)
|
|
||||||
|
|
||||||
It uses various tools to obtain the list of required shared library
|
* ``dumpbin`` (Windows)
|
||||||
files:
|
* ``objdump`` (MinGW on Windows)
|
||||||
|
* ``ldd`` (Linux/Unix)
|
||||||
::
|
* ``otool`` (Apple operating systems)
|
||||||
|
|
||||||
dumpbin (Windows)
|
|
||||||
objdump (MinGW on Windows)
|
|
||||||
ldd (Linux/Unix)
|
|
||||||
otool (Mac OSX)
|
|
||||||
|
|
||||||
.. versionchanged:: 3.16
|
.. versionchanged:: 3.16
|
||||||
The tool specified by the :variable:`CMAKE_OBJDUMP` variable
|
The tool specified by the :variable:`CMAKE_OBJDUMP` variable will be used, if
|
||||||
will be used, if set.
|
set.
|
||||||
|
|
||||||
The following functions are provided by this module:
|
The following functions are provided by this module:
|
||||||
|
|
||||||
::
|
* :command:`get_prerequisites`
|
||||||
|
* :command:`list_prerequisites`
|
||||||
|
* :command:`list_prerequisites_by_glob`
|
||||||
|
* :command:`gp_append_unique`
|
||||||
|
* :command:`is_file_executable`
|
||||||
|
* :command:`gp_item_default_embedded_path`
|
||||||
|
(projects can override it with ``gp_item_default_embedded_path_override()``)
|
||||||
|
* :command:`gp_resolve_item`
|
||||||
|
(projects can override it with ``gp_resolve_item_override()``)
|
||||||
|
* :command:`gp_resolved_file_type`
|
||||||
|
(projects can override it with ``gp_resolved_file_type_override()``)
|
||||||
|
* :command:`gp_file_type`
|
||||||
|
|
||||||
get_prerequisites
|
Functions
|
||||||
list_prerequisites
|
^^^^^^^^^
|
||||||
list_prerequisites_by_glob
|
|
||||||
gp_append_unique
|
.. command:: get_prerequisites
|
||||||
is_file_executable
|
|
||||||
gp_item_default_embedded_path
|
|
||||||
(projects can override with gp_item_default_embedded_path_override)
|
|
||||||
gp_resolve_item
|
|
||||||
(projects can override with gp_resolve_item_override)
|
|
||||||
gp_resolved_file_type
|
|
||||||
(projects can override with gp_resolved_file_type_override)
|
|
||||||
gp_file_type
|
|
||||||
|
|
||||||
.. code-block:: cmake
|
.. code-block:: cmake
|
||||||
|
|
||||||
GET_PREREQUISITES(<target> <prerequisites_var> <exclude_system> <recurse>
|
get_prerequisites(<target> <prerequisites-var> <exclude-system> <recurse>
|
||||||
<exepath> <dirs> [<rpaths>])
|
<exepath> <dirs> [<rpaths>])
|
||||||
|
|
||||||
Get the list of shared library files required by <target>. The list
|
Gets the list of shared library files required by ``<target>``. The list
|
||||||
in the variable named <prerequisites_var> should be empty on first
|
in the variable named ``<prerequisites-var>`` should be empty on first
|
||||||
entry to this function. On exit, <prerequisites_var> will contain the
|
entry to this function. On exit, ``<prerequisites-var>`` will contain the
|
||||||
list of required shared library files.
|
list of required shared library files.
|
||||||
|
|
||||||
<target> is the full path to an executable file. <prerequisites_var>
|
The arguments are:
|
||||||
is the name of a CMake variable to contain the results.
|
|
||||||
<exclude_system> must be 0 or 1 indicating whether to include or
|
``<target>``
|
||||||
exclude "system" prerequisites. If <recurse> is set to 1 all
|
The full path to an executable or shared library file.
|
||||||
prerequisites will be found recursively, if set to 0 only direct
|
``<prerequisites-var>``
|
||||||
prerequisites are listed. <exepath> is the path to the top level
|
The name of a CMake variable to contain the results.
|
||||||
executable used for @executable_path replacement on the Mac. <dirs> is
|
``<exclude-system>``
|
||||||
a list of paths where libraries might be found: these paths are
|
If set to 1 system prerequisites will be excluded, if set to 0 they will be
|
||||||
searched first when a target without any path info is given. Then
|
included.
|
||||||
standard system locations are also searched: PATH, Framework
|
``<recurse>``
|
||||||
locations, /usr/lib...
|
If set to 1 all prerequisites will be found recursively, if set to 0 only
|
||||||
|
direct prerequisites are listed.
|
||||||
|
``<exepath>``
|
||||||
|
The path to the top level executable used for ``@executable_path``
|
||||||
|
replacement on Apple operating systems.
|
||||||
|
``<dirs>``
|
||||||
|
A list of paths where libraries might be found: these paths are searched
|
||||||
|
first when a target without any path info is given. Then standard system
|
||||||
|
locations are also searched: PATH, Framework locations, /usr/lib...
|
||||||
|
``<rpaths>``
|
||||||
|
Optional run-time search paths for an executable file or library to help
|
||||||
|
find files.
|
||||||
|
|
||||||
.. versionadded:: 3.14
|
.. versionadded:: 3.14
|
||||||
The variable GET_PREREQUISITES_VERBOSE can be set to true to enable verbose
|
The variable ``GET_PREREQUISITES_VERBOSE`` can be set to true before calling
|
||||||
output.
|
this function to enable verbose output.
|
||||||
|
|
||||||
|
.. command:: list_prerequisites
|
||||||
|
|
||||||
.. code-block:: cmake
|
.. code-block:: cmake
|
||||||
|
|
||||||
LIST_PREREQUISITES(<target> [<recurse> [<exclude_system> [<verbose>]]])
|
list_prerequisites(<target> [<recurse> [<exclude-system> [<verbose>]]])
|
||||||
|
|
||||||
Print a message listing the prerequisites of <target>.
|
Prints a message listing the prerequisites of ``<target>``.
|
||||||
|
|
||||||
<target> is the name of a shared library or executable target or the
|
The arguments are:
|
||||||
full path to a shared library or executable file. If <recurse> is set
|
|
||||||
to 1 all prerequisites will be found recursively, if set to 0 only
|
``<target>``
|
||||||
direct prerequisites are listed. <exclude_system> must be 0 or 1
|
The name of a shared library or executable target or the full path to a
|
||||||
indicating whether to include or exclude "system" prerequisites. With
|
shared library or executable file.
|
||||||
<verbose> set to 0 only the full path names of the prerequisites are
|
``<recurse>``
|
||||||
printed, set to 1 extra information will be displayed.
|
If set to 1 all prerequisites will be found recursively, if set to 0 only
|
||||||
|
direct prerequisites are listed.
|
||||||
|
``<exclude-system>``
|
||||||
|
If set to 1 system prerequisites will be excluded, if set to 0 they will be
|
||||||
|
included.
|
||||||
|
``<verbose>``
|
||||||
|
If set to 0 only the full path names of the prerequisites are printed. If
|
||||||
|
set to 1 extra information will be displayed.
|
||||||
|
|
||||||
|
.. command:: list_prerequisites_by_glob
|
||||||
|
|
||||||
.. code-block:: cmake
|
.. code-block:: cmake
|
||||||
|
|
||||||
LIST_PREREQUISITES_BY_GLOB(<glob_arg> <glob_exp>)
|
list_prerequisites_by_glob(<GLOB|GLOB_RECURSE>
|
||||||
|
<glob-exp>
|
||||||
|
[<optional-args>...])
|
||||||
|
|
||||||
Print the prerequisites of shared library and executable files
|
Prints the prerequisites of shared library and executable files matching a
|
||||||
matching a globbing pattern. <glob_arg> is GLOB or GLOB_RECURSE and
|
globbing pattern.
|
||||||
<glob_exp> is a globbing expression used with "file(GLOB" or
|
|
||||||
"file(GLOB_RECURSE" to retrieve a list of matching files. If a
|
The arguments are:
|
||||||
|
|
||||||
|
``GLOB`` or ``GLOB_RECURSE``
|
||||||
|
The globbing mode, whether to traverse only the match or also its
|
||||||
|
subdirectories recursively.
|
||||||
|
``<glob-exp>``
|
||||||
|
A globbing expression used with :command:`file(GLOB)` or
|
||||||
|
:command:`file(GLOB_RECURSE)` to retrieve a list of matching files. If a
|
||||||
matching file is executable, its prerequisites are listed.
|
matching file is executable, its prerequisites are listed.
|
||||||
|
``<optional-args>...``
|
||||||
Any additional (optional) arguments provided are passed along as the
|
Any additional (optional) arguments provided are passed along as the
|
||||||
optional arguments to the list_prerequisites calls.
|
optional arguments to the ``list_prerequisite()`` calls.
|
||||||
|
|
||||||
|
.. command:: gp_append_unique
|
||||||
|
|
||||||
.. code-block:: cmake
|
.. code-block:: cmake
|
||||||
|
|
||||||
GP_APPEND_UNIQUE(<list_var> <value>)
|
gp_append_unique(<list-var> <value>)
|
||||||
|
|
||||||
Append <value> to the list variable <list_var> only if the value is
|
Appends ``<value>`` to the list variable ``<list-var>`` only if the value is
|
||||||
not already in the list.
|
not already in the list.
|
||||||
|
|
||||||
.. code-block:: cmake
|
.. command:: is_file_executable
|
||||||
|
|
||||||
IS_FILE_EXECUTABLE(<file> <result_var>)
|
|
||||||
|
|
||||||
Return 1 in <result_var> if <file> is a binary executable, 0
|
|
||||||
otherwise.
|
|
||||||
|
|
||||||
.. code-block:: cmake
|
.. code-block:: cmake
|
||||||
|
|
||||||
GP_ITEM_DEFAULT_EMBEDDED_PATH(<item> <default_embedded_path_var>)
|
is_file_executable(<file> <result-var>)
|
||||||
|
|
||||||
Return the path that others should refer to the item by when the item
|
Sets ``<result-var>`` to 1 if ``<file>`` is a binary executable; otherwise
|
||||||
is embedded inside a bundle.
|
sets it to 0.
|
||||||
|
|
||||||
Override on a per-project basis by providing a project-specific
|
.. command:: gp_item_default_embedded_path
|
||||||
gp_item_default_embedded_path_override function.
|
|
||||||
|
|
||||||
.. code-block:: cmake
|
.. code-block:: cmake
|
||||||
|
|
||||||
GP_RESOLVE_ITEM(<context> <item> <exepath> <dirs> <resolved_item_var>
|
gp_item_default_embedded_path(<item> <default-embedded-path-var>)
|
||||||
|
|
||||||
|
Determines the reference path for ``<item>`` when it is embedded inside a
|
||||||
|
bundle and stores it to a variable ``<default-embedded-path-var>``.
|
||||||
|
|
||||||
|
Projects can override this function by defining a custom
|
||||||
|
``gp_item_default_embedded_path_override()`` function.
|
||||||
|
|
||||||
|
.. command:: gp_resolve_item
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
gp_resolve_item(<context> <item> <exepath> <dirs> <resolved-item-var>
|
||||||
[<rpaths>])
|
[<rpaths>])
|
||||||
|
|
||||||
Resolve an item into an existing full path file.
|
Resolves a given ``<item>`` into an existing full path file and stores it to a
|
||||||
|
``<resolved-item-var>`` variable.
|
||||||
|
|
||||||
Override on a per-project basis by providing a project-specific
|
The arguments are:
|
||||||
gp_resolve_item_override function.
|
|
||||||
|
``<context>``
|
||||||
|
The path to the top level loading path used for ``@loader_path`` replacement
|
||||||
|
on Apple operating systems. When resolving item, ``@loader_path``
|
||||||
|
references will be resolved relative to the directory of the given context
|
||||||
|
value (presumably another library).
|
||||||
|
``<item>``
|
||||||
|
The item to resolve.
|
||||||
|
``<exepath>``
|
||||||
|
See the argument description in :command:`get_prerequisites`.
|
||||||
|
``<dirs>``
|
||||||
|
See the argument description in :command:`get_prerequisites`.
|
||||||
|
``<resolved-item-var>``
|
||||||
|
The result variable where the resolved item is stored into.
|
||||||
|
``<rpaths>``
|
||||||
|
See the argument description in :command:`get_prerequisites`.
|
||||||
|
|
||||||
|
Projects can override this function by defining a custom
|
||||||
|
``gp_resolve_item_override()`` function.
|
||||||
|
|
||||||
|
.. command:: gp_resolved_file_type
|
||||||
|
|
||||||
.. code-block:: cmake
|
.. code-block:: cmake
|
||||||
|
|
||||||
GP_RESOLVED_FILE_TYPE(<original_file> <file> <exepath> <dirs> <type_var>
|
gp_resolved_file_type(<original-file> <file> <exepath> <dirs> <type-var>
|
||||||
[<rpaths>])
|
[<rpaths>])
|
||||||
|
|
||||||
Return the type of <file> with respect to <original_file>. String
|
Determines the type of ``<file>`` with respect to ``<original-file>``. The
|
||||||
describing type of prerequisite is returned in variable named
|
resulting type of prerequisite is stored in the ``<type-var>`` variable.
|
||||||
<type_var>.
|
|
||||||
|
|
||||||
Use <exepath> and <dirs> if necessary to resolve non-absolute <file>
|
Use ``<exepath>`` and ``<dirs>`` if necessary to resolve non-absolute
|
||||||
values -- but only for non-embedded items.
|
``<file>`` values -- but only for non-embedded items.
|
||||||
|
|
||||||
Possible types are:
|
``<rpaths>``
|
||||||
|
See the argument description in :command:`get_prerequisites`.
|
||||||
|
|
||||||
::
|
The ``<type-var>`` variable will be set to one of the following values:
|
||||||
|
|
||||||
system
|
* ``system``
|
||||||
local
|
* ``local``
|
||||||
embedded
|
* ``embedded``
|
||||||
other
|
* ``other``
|
||||||
|
|
||||||
Override on a per-project basis by providing a project-specific
|
Projects can override this function by defining a custom
|
||||||
gp_resolved_file_type_override function.
|
``gp_resolved_file_type_override()`` function.
|
||||||
|
|
||||||
|
.. command:: gp_file_type
|
||||||
|
|
||||||
.. code-block:: cmake
|
.. code-block:: cmake
|
||||||
|
|
||||||
GP_FILE_TYPE(<original_file> <file> <type_var>)
|
gp_file_type(<original-file> <file> <type-var>)
|
||||||
|
|
||||||
Return the type of <file> with respect to <original_file>. String
|
Determines the type of ``<file>`` with respect to ``<original-file>``. The
|
||||||
describing type of prerequisite is returned in variable named
|
resulting type of prerequisite is stored in the ``<type-var>`` variable.
|
||||||
<type_var>.
|
|
||||||
|
|
||||||
Possible types are:
|
The ``<type-var>`` variable will be set to one of the following values:
|
||||||
|
|
||||||
::
|
* ``system``
|
||||||
|
* ``local``
|
||||||
|
* ``embedded``
|
||||||
|
* ``other``
|
||||||
|
|
||||||
system
|
Examples
|
||||||
local
|
^^^^^^^^
|
||||||
embedded
|
|
||||||
other
|
Printing all dependencies of a shared library, including system libraries, with
|
||||||
|
verbose output:
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
include(GetPrerequisites)
|
||||||
|
list_prerequisites("path/to/libfoo.dylib" 1 0 1)
|
||||||
#]=======================================================================]
|
#]=======================================================================]
|
||||||
|
|
||||||
function(gp_append_unique list_var value)
|
function(gp_append_unique list_var value)
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user