Kitware/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2025-10-14 02:08:27 +08:00
Code Issues Projects Releases Wiki Activity

GetPrerequisites: Sync documentation

Browse Source 
* GetPrerequisites:
  - Added intro code block showing how to include this module.
  - Renamed "functions" to "commands".
  - Moved command descriptions above their signatures.
  - Added initial example of migrating the `gp_append_unique()` command.

* BundleUtilities:
  - Replaced obsolete gp_append_unique(): Instead of using the
    deprecated `gp_append_unique()`, these usages can be replaced with
    `if()` and `list(APPEND)` commands directly.
This commit is contained in:
Peter Kokot
2025-08-07 21:42:38 +02:00
parent 2e3dde3727
commit 374eb128c9
2 changed files with 94 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
Modules/BundleUtilities.cmake
View File

@@ -733,7 +733,9 @@ function(get_item_rpaths item rpaths_var)
string(REGEX REPLACE "rpath " "" load_cmds_ov "${load_cmds_ov}")
if(load_cmds_ov)
foreach(rpath ${load_cmds_ov})
gp_append_unique(${rpaths_var} "${rpath}")
if(NOT rpath IN_LIST ${rpaths_var})
list(APPEND ${rpaths_var} "${rpath}")
endif()
endforeach()
endif()
endif()
@@ -744,7 +746,9 @@ function(get_item_rpaths item rpaths_var)
foreach(rpath ${rpath_var} ${runpath_var})
# Substitute $ORIGIN with the exepath and add to the found rpaths
string(REPLACE "$ORIGIN" "${item_dir}" rpath "${rpath}")
gp_append_unique(${rpaths_var} "${rpath}")
if(NOT rpath IN_LIST ${rpaths_var})
list(APPEND ${rpaths_var} "${rpath}")
endif()
endforeach()
endif()
@@ -787,7 +791,9 @@ function(set_bundle_key_values keys_var context item exepath dirs copyflag)
get_item_key("${item}" key)
list(LENGTH ${keys_var} length_before)
gp_append_unique(${keys_var} "${key}")
if(NOT key IN_LIST ${keys_var})
list(APPEND ${keys_var} "${key}")
endif()
list(LENGTH ${keys_var} length_after)
if(NOT length_before EQUAL length_after)

122
Modules/GetPrerequisites.cmake
View File

@@ -9,12 +9,19 @@ GetPrerequisites
Use :command:`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
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.
It determines dependencies using the following platform-specific tools:
Load this module in CMake with:
.. code-block:: cmake
include(GetPrerequisites)
This module determines dependencies using the following platform-specific
tools:
* ``dumpbin`` (Windows)
* ``objdump`` (MinGW on Windows)
@@ -25,7 +32,10 @@ It determines dependencies using the following platform-specific tools:
The tool specified by the :variable:`CMAKE_OBJDUMP` variable will be used, if
set.
The following functions are provided by this module:
Commands
^^^^^^^^
This module provides the following commands:
* :command:`get_prerequisites`
* :command:`list_prerequisites`
@@ -40,20 +50,18 @@ The following functions are provided by this module:
(projects can override it with ``gp_resolved_file_type_override()``)
* :command:`gp_file_type`
Functions
^^^^^^^^^
.. command:: get_prerequisites
Gets the list of shared library files required by specified target:
.. code-block:: cmake
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 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:
@@ -80,16 +88,16 @@ Functions
.. versionadded:: 3.14
The variable ``GET_PREREQUISITES_VERBOSE`` can be set to true before calling
this function to enable verbose output.
this command to enable verbose output.
.. command:: list_prerequisites
Prints a message listing the prerequisites of the specified target:
.. code-block:: cmake
list_prerequisites(<target> [<recurse> [<exclude-system> [<verbose>]]])
Prints a message listing the prerequisites of ``<target>``.
The arguments are:
``<target>``
@@ -107,15 +115,15 @@ Functions
.. command:: list_prerequisites_by_glob
Prints the prerequisites of shared library and executable files matching a
globbing pattern:
.. code-block:: cmake
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``
@@ -131,44 +139,56 @@ Functions
.. command:: gp_append_unique
Appends the value to the list only if it is not already in the list:
.. code-block:: cmake
gp_append_unique(<list-var> <value>)
Appends ``<value>`` to the list variable ``<list-var>`` only if the value is
not already in the list.
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.
.. command:: is_file_executable
Checks if given file is a binary executable:
.. code-block:: cmake
is_file_executable(<file> <result-var>)
Sets ``<result-var>`` to 1 if ``<file>`` is a binary executable; otherwise
sets it to 0.
This command sets the ``<result-var>`` to 1 if ``<file>`` is a binary
executable; otherwise it sets it to 0.
.. command:: gp_item_default_embedded_path
Determines the reference path for the specified item:
.. code-block:: cmake
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>``.
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 function by defining a custom
``gp_item_default_embedded_path_override()`` function.
Projects can override this command by defining a custom
``gp_item_default_embedded_path_override()`` command.
.. command:: gp_resolve_item
Resolves a given item into an existing full path file and stores it to a
variable:
.. code-block:: cmake
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>``
@@ -187,18 +207,21 @@ Functions
``<rpaths>``
See the argument description in :command:`get_prerequisites`.
Projects can override this function by defining a custom
``gp_resolve_item_override()`` function.
Projects can override this command by defining a custom
``gp_resolve_item_override()`` command.
.. command:: gp_resolved_file_type
Determines the type of a given file:
.. code-block:: cmake
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.
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.
@@ -213,17 +236,20 @@ Functions
* ``embedded``
* ``other``
Projects can override this function by defining a custom
``gp_resolved_file_type_override()`` function.
Projects can override this command by defining a custom
``gp_resolved_file_type_override()`` command.
.. command:: gp_file_type
Determines the type of a given file:
.. code-block:: cmake
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.
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:
@@ -235,6 +261,9 @@ Functions
Examples
^^^^^^^^
Example: Basic Usage
""""""""""""""""""""
Printing all dependencies of a shared library, including system libraries, with
verbose output:
@@ -242,6 +271,25 @@ verbose output:
include(GetPrerequisites)
list_prerequisites("path/to/libfoo.dylib" 1 0 1)
Example: Upgrading Code
"""""""""""""""""""""""
For example:
.. code-block:: cmake
include(GetPrerequisites)
# ...
gp_append_unique(keys "${key}")
the ``gp_append_unique()`` can be in new code replaced with:
.. code-block:: cmake
if(NOT key IN_LIST keys)
list(APPEND keys "${key}")
endif()
#]=======================================================================]
function(gp_append_unique list_var value)