GetPrerequisites

Deprecated since version 3.16: Use file(GET_RUNTIME_DEPENDENCIES) instead.

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.

It determines dependencies using the following platform-specific tools:

  • dumpbin (Windows)

  • objdump (MinGW on Windows)

  • ldd (Linux/Unix)

  • otool (Apple operating systems)

Changed in version 3.16: The tool specified by the CMAKE_OBJDUMP variable will be used, if set.

The following functions are provided by this module:

Functions

get_prerequisites
get_prerequisites(<target> <prerequisites-var> <exclude-system> <recurse>
                  <exepath> <dirs> [<rpaths>])

Gets the list of shared library files required by <target>. The list in the variable named <prerequisites-var> should be empty on first entry to this function. On exit, <prerequisites-var> will contain the list of required shared library files.

The arguments are:

<target>

The full path to an executable or shared library file.

<prerequisites-var>

The name of a CMake variable to contain the results.

<exclude-system>

If set to 1 system prerequisites will be excluded, if set to 0 they will be included.

<recurse>

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.

Added in version 3.14: The variable GET_PREREQUISITES_VERBOSE can be set to true before calling this function to enable verbose output.

list_prerequisites
list_prerequisites(<target> [<recurse> [<exclude-system> [<verbose>]]])

Prints a message listing the prerequisites of <target>.

The arguments are:

<target>

The name of a shared library or executable target or the full path to a shared library or executable file.

<recurse>

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.

list_prerequisites_by_glob
list_prerequisites_by_glob(<GLOB|GLOB_RECURSE>
                           <glob-exp>
                           [<optional-args>...])

Prints the prerequisites of shared library and executable files matching a globbing pattern.

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 file(GLOB) or file(GLOB_RECURSE) to retrieve a list of matching files. If a matching file is executable, its prerequisites are listed.

<optional-args>...

Any additional (optional) arguments provided are passed along as the optional arguments to the list_prerequisite() calls.

gp_append_unique
gp_append_unique(<list-var> <value>)

Appends <value> to the list variable <list-var> only if the value is not already in the list.

is_file_executable
is_file_executable(<file> <result-var>)

Sets <result-var> to 1 if <file> is a binary executable; otherwise sets it to 0.

gp_item_default_embedded_path
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.

gp_resolve_item
gp_resolve_item(<context> <item> <exepath> <dirs> <resolved-item-var>
                [<rpaths>])

Resolves a given <item> into an existing full path file and stores it to a <resolved-item-var> variable.

The arguments are:

<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 get_prerequisites().

<dirs>

See the argument description in get_prerequisites().

<resolved-item-var>

The result variable where the resolved item is stored into.

<rpaths>

See the argument description in get_prerequisites().

Projects can override this function by defining a custom gp_resolve_item_override() function.

gp_resolved_file_type
gp_resolved_file_type(<original-file> <file> <exepath> <dirs> <type-var>
                      [<rpaths>])

Determines the type of <file> with respect to <original-file>. The resulting type of prerequisite is stored in the <type-var> variable.

Use <exepath> and <dirs> if necessary to resolve non-absolute <file> values -- but only for non-embedded items.

<rpaths>

See the argument description in get_prerequisites().

The <type-var> variable will be set to one of the following values:

  • system

  • local

  • embedded

  • other

Projects can override this function by defining a custom gp_resolved_file_type_override() function.

gp_file_type
gp_file_type(<original-file> <file> <type-var>)

Determines the type of <file> with respect to <original-file>. The resulting type of prerequisite is stored in the <type-var> variable.

The <type-var> variable will be set to one of the following values:

  • system

  • local

  • embedded

  • other

Examples

Printing all dependencies of a shared library, including system libraries, with verbose output:

include(GetPrerequisites)
list_prerequisites("path/to/libfoo.dylib" 1 0 1)