From 374eb128c9bfa990b1aee1f33fb51e3bc0fb7890 Mon Sep 17 00:00:00 2001 From: Peter Kokot Date: Thu, 7 Aug 2025 21:42:38 +0200 Subject: [PATCH] GetPrerequisites: Sync documentation * 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. --- Modules/BundleUtilities.cmake | 12 +++- Modules/GetPrerequisites.cmake | 122 +++++++++++++++++++++++---------- 2 files changed, 94 insertions(+), 40 deletions(-) diff --git a/Modules/BundleUtilities.cmake b/Modules/BundleUtilities.cmake index 4df5bb9f95..0c7fedec5f 100644 --- a/Modules/BundleUtilities.cmake +++ b/Modules/BundleUtilities.cmake @@ -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) diff --git a/Modules/GetPrerequisites.cmake b/Modules/GetPrerequisites.cmake index f1f5db7b7b..952e66c0d1 100644 --- a/Modules/GetPrerequisites.cmake +++ b/Modules/GetPrerequisites.cmake @@ -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( []) - Gets the list of shared library files required by ````. The list - in the variable named ```` should be empty on first - entry to this function. On exit, ```` will contain the - list of required shared library files. + The list in the variable named ```` should be empty on + first entry to this command. On exit, ```` 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( [ [ []]]) - Prints a message listing the prerequisites of ````. - The arguments are: ```` @@ -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( [...]) - 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( ) - Appends ```` to the list variable ```` only if the value is - not already in the list. + The arguments are: + + ```` + The value to be appended to the list. + ```` + 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( ) - Sets ```` to 1 if ```` is a binary executable; otherwise - sets it to 0. + This command sets the ```` to 1 if ```` 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( ) - Determines the reference path for ```` when it is embedded inside a - bundle and stores it to a variable ````. + This command determines the reference path for ```` when it is + embedded inside a bundle and stores it to a variable + ````. - 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( []) - Resolves a given ```` into an existing full path file and stores it to a - ```` variable. - The arguments are: ```` @@ -187,18 +207,21 @@ Functions ```` 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( []) - Determines the type of ```` with respect to ````. The - resulting type of prerequisite is stored in the ```` variable. + This command determines the type of ```` with respect to the + ````. The resulting type of prerequisite is stored in the + ```` variable. Use ```` and ```` if necessary to resolve non-absolute ```` 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( ) - Determines the type of ```` with respect to ````. The - resulting type of prerequisite is stored in the ```` variable. + This command determines the type of ```` with respect to the + ````. The resulting type of prerequisite is stored in the + ```` variable. The ```` 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)