GetPrerequisites

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

This module provides commands to analyze and list the dependencies (prerequisites) of executable or shared library files. These commands list the shared libraries (.dll, .dylib, or .so files) required by an executable or shared library.

Load this module in CMake with:

include(GetPrerequisites)

This module 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.

Commands

This module provides the following commands:

get_prerequisites

Gets the list of shared library files required by specified target:

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

The list in the variable named <prerequisites-var> should be empty on first entry to this command. 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 command to enable verbose output.

list_prerequisites

Prints a message listing the prerequisites of the specified target:

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

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

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

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

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

Appends the value to the list only if it is not already in the list:

gp_append_unique(<list-var> <value>)

The arguments are:

<value>

The value to be appended to the list.

<list-var>

The list variable name that will have the value appended only if it is not already in the list.

is_file_executable

Checks if given file is a binary executable:

is_file_executable(<file> <result-var>)

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

gp_item_default_embedded_path

Determines the reference path for the specified item:

gp_item_default_embedded_path(<item> <default-embedded-path-var>)

This command 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 command by defining a custom gp_item_default_embedded_path_override() command.

gp_resolve_item

Resolves a given item into an existing full path file and stores it to a variable:

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

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 command by defining a custom gp_resolve_item_override() command.

gp_resolved_file_type

Determines the type of a given file:

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

This command determines the type of <file> with respect to the <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 command by defining a custom gp_resolved_file_type_override() command.

gp_file_type

Determines the type of a given file:

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

This command determines the type of <file> with respect to the <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

Example: Basic Usage

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

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

Example: Upgrading Code

For example:

include(GetPrerequisites)
# ...
gp_append_unique(keys "${key}")

the gp_append_unique() can be in new code replaced with:

if(NOT key IN_LIST keys)
  list(APPEND keys "${key}")
endif()