diff options
Diffstat (limited to 'Modules/BundleUtilities.cmake')
| -rw-r--r-- | Modules/BundleUtilities.cmake | 126 |
1 files changed, 65 insertions, 61 deletions
diff --git a/Modules/BundleUtilities.cmake b/Modules/BundleUtilities.cmake index 8c7646e4d..f94fc5cff 100644 --- a/Modules/BundleUtilities.cmake +++ b/Modules/BundleUtilities.cmake @@ -7,7 +7,7 @@ BundleUtilities Functions to help assemble a standalone bundle application. -A collection of CMake utility functions useful for dealing with .app +A collection of CMake utility functions useful for dealing with ``.app`` bundles on the Mac and bundle-like directories on any OS. The following functions are provided by this module: @@ -33,7 +33,7 @@ The following functions are provided by this module: verify_bundle_symlinks Requires CMake 2.6 or greater because it uses function, break and -PARENT_SCOPE. Also depends on GetPrerequisites.cmake. +``PARENT_SCOPE``. Also depends on ``GetPrerequisites.cmake``. DO NOT USE THESE FUNCTIONS AT CONFIGURE TIME (from ``CMakeLists.txt``)! Instead, invoke them from an :command:`install(CODE)` or @@ -43,55 +43,57 @@ Instead, invoke them from an :command:`install(CODE)` or fixup_bundle(<app> <libs> <dirs>) -Fix up a bundle in-place and make it standalone, such that it can be +Fix up ``<app>`` bundle in-place and make it standalone, such that it can be drag-n-drop copied to another machine and run on that machine as long as all of the system libraries are compatible. -If you pass plugins to fixup_bundle as the libs parameter, you should -install them or copy them into the bundle before calling fixup_bundle. -The "libs" parameter is a list of libraries that must be fixed up, but -that cannot be determined by otool output analysis. (i.e., plugins) +If you pass plugins to ``fixup_bundle`` as the libs parameter, you should +install them or copy them into the bundle before calling ``fixup_bundle``. +The ``<libs>`` parameter is a list of libraries that must be fixed up, but +that cannot be determined by ``otool`` output analysis (i.e. ``plugins``). Gather all the keys for all the executables and libraries in a bundle, and then, for each key, copy each prerequisite into the bundle. Then fix each one up according to its own list of prerequisites. -Then clear all the keys and call verify_app on the final bundle to +Then clear all the keys and call ``verify_app`` on the final bundle to ensure that it is truly standalone. -As an optional parameter (IGNORE_ITEM) a list of file names can be passed, -which are then ignored (e.g. IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe") +As an optional parameter (``IGNORE_ITEM``) a list of file names can be passed, +which are then ignored +(e.g. ``IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe"``). .. code-block:: cmake copy_and_fixup_bundle(<src> <dst> <libs> <dirs>) -Makes a copy of the bundle <src> at location <dst> and then fixes up -the new copied bundle in-place at <dst>... +Makes a copy of the bundle ``<src>`` at location ``<dst>`` and then fixes up +the new copied bundle in-place at ``<dst>``. .. code-block:: cmake verify_app(<app>) -Verifies that an application <app> appears valid based on running -analysis tools on it. Calls "message(FATAL_ERROR" if the application +Verifies that an application ``<app>`` appears valid based on running +analysis tools on it. Calls :command:`message(FATAL_ERROR)` if the application is not verified. -As an optional parameter (IGNORE_ITEM) a list of file names can be passed, -which are then ignored (e.g. IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe") +As an optional parameter (``IGNORE_ITEM``) a list of file names can be passed, +which are then ignored +(e.g. ``IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe"``) .. code-block:: cmake get_bundle_main_executable(<bundle> <result_var>) The result will be the full path name of the bundle's main executable -file or an "error:" prefixed string if it could not be determined. +file or an ``error:`` prefixed string if it could not be determined. .. code-block:: cmake get_dotapp_dir(<exe> <dotapp_dir_var>) -Returns the nearest parent dir whose name ends with ".app" given the +Returns the nearest parent dir whose name ends with ``.app`` given the full path to an executable. If there is no such parent dir, then simply return the dir containing the executable. @@ -101,26 +103,26 @@ The returned directory may or may not exist. get_bundle_and_executable(<app> <bundle_var> <executable_var> <valid_var>) -Takes either a ".app" directory name or the name of an executable -nested inside a ".app" directory and returns the path to the ".app" -directory in <bundle_var> and the path to its main executable in -<executable_var> +Takes either a ``.app`` directory name or the name of an executable +nested inside a ``.app`` directory and returns the path to the ``.app`` +directory in ``<bundle_var>`` and the path to its main executable in +``<executable_var>``. .. code-block:: cmake get_bundle_all_executables(<bundle> <exes_var>) -Scans the given bundle recursively for all executable files and -accumulates them into a variable. +Scans ``<bundle>`` bundle recursively for all ``<exes_var>`` executable +files and accumulates them into a variable. .. code-block:: cmake get_item_key(<item> <key_var>) -Given a file (item) name, generate a key that should be unique +Given ``<item>`` file name, generate ``<key_var>`` key that should be unique considering the set of libraries that need copying or fixing up to make a bundle standalone. This is essentially the file name including -extension with "." replaced by "_" +extension with ``.`` replaced by ``_`` This key is used as a prefix for CMake variables so that we can associate a set of variables with a given item based on its key. @@ -129,10 +131,10 @@ associate a set of variables with a given item based on its key. clear_bundle_keys(<keys_var>) -Loop over the list of keys, clearing all the variables associated with -each key. After the loop, clear the list of keys itself. +Loop over the ``<keys_var>`` list of keys, clearing all the variables +associated with each key. After the loop, clear the list of keys itself. -Caller of get_bundle_keys should call clear_bundle_keys when done with +Caller of ``get_bundle_keys`` should call ``clear_bundle_keys`` when done with list of keys. .. code-block:: cmake @@ -140,86 +142,88 @@ list of keys. set_bundle_key_values(<keys_var> <context> <item> <exepath> <dirs> <copyflag> [<rpaths>]) -Add a key to the list (if necessary) for the given item. If added, -also set all the variables associated with that key. +Add ``<keys_var>`` key to the list (if necessary) for the given item. +If added, also set all the variables associated with that key. .. code-block:: cmake get_bundle_keys(<app> <libs> <dirs> <keys_var>) -Loop over all the executable and library files within the bundle (and -given as extra <libs>) and accumulate a list of keys representing +Loop over all the executable and library files within ``<app>`` bundle (and +given as extra ``<libs>``) and accumulate a list of keys representing them. Set values associated with each key such that we can loop over all of them and copy prerequisite libs into the bundle and then do -appropriate install_name_tool fixups. +appropriate ``install_name_tool`` fixups. -As an optional parameter (IGNORE_ITEM) a list of file names can be passed, -which are then ignored (e.g. IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe") +As an optional parameter (``IGNORE_ITEM``) a list of file names can be passed, +which are then ignored +(e.g. ``IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe"``) .. code-block:: cmake copy_resolved_item_into_bundle(<resolved_item> <resolved_embedded_item>) -Copy a resolved item into the bundle if necessary. Copy is not -necessary if the resolved_item is "the same as" the -resolved_embedded_item. +Copy a resolved item into the bundle if necessary. +Copy is not necessary, if the ``<resolved_item>`` is "the same as" the +``<resolved_embedded_item>``. .. code-block:: cmake copy_resolved_framework_into_bundle(<resolved_item> <resolved_embedded_item>) -Copy a resolved framework into the bundle if necessary. Copy is not -necessary if the resolved_item is "the same as" the -resolved_embedded_item. +Copy a resolved framework into the bundle if necessary. +Copy is not necessary, if the ``<resolved_item>`` is "the same as" the +``<resolved_embedded_item>``. -By default, BU_COPY_FULL_FRAMEWORK_CONTENTS is not set. If you want +By default, ``BU_COPY_FULL_FRAMEWORK_CONTENTS`` is not set. If you want full frameworks embedded in your bundles, set -BU_COPY_FULL_FRAMEWORK_CONTENTS to ON before calling fixup_bundle. By -default, COPY_RESOLVED_FRAMEWORK_INTO_BUNDLE copies the framework -dylib itself plus the framework Resources directory. +``BU_COPY_FULL_FRAMEWORK_CONTENTS`` to ``ON`` before calling fixup_bundle. By +default, ``COPY_RESOLVED_FRAMEWORK_INTO_BUNDLE`` copies the framework +dylib itself plus the framework ``Resources`` directory. .. code-block:: cmake fixup_bundle_item(<resolved_embedded_item> <exepath> <dirs>) -Get the direct/non-system prerequisites of the resolved embedded item. +Get the direct/non-system prerequisites of the ``<resolved_embedded_item>``. For each prerequisite, change the way it is referenced to the value of -the _EMBEDDED_ITEM keyed variable for that prerequisite. (Most likely -changing to an "@executable_path" style reference.) +the ``_EMBEDDED_ITEM`` keyed variable for that prerequisite. (Most likely +changing to an ``@executable_path`` style reference.) -This function requires that the resolved_embedded_item be "inside" the -bundle already. In other words, if you pass plugins to fixup_bundle +This function requires that the ``<resolved_embedded_item>`` be ``inside`` +the bundle already. In other words, if you pass plugins to ``fixup_bundle`` as the libs parameter, you should install them or copy them into the -bundle before calling fixup_bundle. The "libs" parameter is a list of +bundle before calling ``fixup_bundle``. The ``libs`` parameter is a list of libraries that must be fixed up, but that cannot be determined by -otool output analysis. (i.e., plugins) +otool output analysis. (i.e., ``plugins``) Also, change the id of the item being fixed up to its own -_EMBEDDED_ITEM value. +``_EMBEDDED_ITEM`` value. Accumulate changes in a local variable and make *one* call to -install_name_tool at the end of the function with all the changes at +``install_name_tool`` at the end of the function with all the changes at once. -If the BU_CHMOD_BUNDLE_ITEMS variable is set then bundle items will be -marked writable before install_name_tool tries to change them. +If the ``BU_CHMOD_BUNDLE_ITEMS`` variable is set then bundle items will be +marked writable before ``install_name_tool`` tries to change them. .. code-block:: cmake verify_bundle_prerequisites(<bundle> <result_var> <info_var>) Verifies that the sum of all prerequisites of all files inside the -bundle are contained within the bundle or are "system" libraries, +bundle are contained within the bundle or are ``system`` libraries, presumed to exist everywhere. -As an optional parameter (IGNORE_ITEM) a list of file names can be passed, -which are then ignored (e.g. IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe") +As an optional parameter (``IGNORE_ITEM``) a list of file names can be passed, +which are then ignored +(e.g. ``IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe"``) .. code-block:: cmake verify_bundle_symlinks(<bundle> <result_var> <info_var>) -Verifies that any symlinks found in the bundle point to other files +Verifies that any symlinks found in the ``<bundle>`` bundle point to other files that are already also in the bundle... Anything that points to an external file causes this function to fail the verification. #]=======================================================================] |