# 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()`

- `list_prerequisites()`

- `list_prerequisites_by_glob()`

- `gp_append_unique()`

- `is_file_executable()`

- `gp_item_default_embedded_path()` (projects can override it with `gp_item_default_embedded_path_override()`)

- `gp_resolve_item()` (projects can override it with `gp_resolve_item_override()`)

- `gp_resolved_file_type()` (projects can override it with `gp_resolved_file_type_override()`)

- `gp_file_type()`

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