diff --git a/Modules/BundleUtilities.cmake b/Modules/BundleUtilities.cmake index df5248714d..7401d9c9b5 100644 --- a/Modules/BundleUtilities.cmake +++ b/Modules/BundleUtilities.cmake @@ -10,226 +10,250 @@ Functions to help assemble a standalone bundle application. A collection of CMake utility functions useful for dealing with ``.app`` bundles on the Mac and bundle-like directories on any OS. +.. note:: + + Do not use these functions at configure time (from ``CMakeLists.txt``). + Instead, invoke them from an :command:`install(CODE)` or + :command:`install(SCRIPT)`. + +Functions +^^^^^^^^^ + The following functions are provided by this module: -.. code-block:: cmake +.. command:: fixup_bundle - fixup_bundle - copy_and_fixup_bundle - verify_app - get_bundle_main_executable - get_dotapp_dir - get_bundle_and_executable - get_bundle_all_executables - get_item_key - get_item_rpaths - clear_bundle_keys - set_bundle_key_values - get_bundle_keys - copy_resolved_item_into_bundle - copy_resolved_framework_into_bundle - fixup_bundle_item - verify_bundle_prerequisites - verify_bundle_symlinks + .. code-block:: cmake -Requires CMake 2.6 or greater because it uses function, break and -``PARENT_SCOPE``. Also depends on ``GetPrerequisites.cmake``. + fixup_bundle( [IGNORE_ITEM ...]) -DO NOT USE THESE FUNCTIONS AT CONFIGURE TIME (from ``CMakeLists.txt``)! -Instead, invoke them from an :command:`install(CODE)` or -:command:`install(SCRIPT)` rule. + Fix up ```` 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. -.. code-block:: cmake + 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 ```` parameter is a list of libraries that must be fixed up, but + that cannot be determined by ``otool`` output analysis (i.e. ``plugins``). - fixup_bundle( ) + 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. -Fix up ```` 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. + Then clear all the keys and call ``verify_app`` on the final bundle to + ensure that it is truly standalone. -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 ```` parameter is a list of libraries that must be fixed up, but -that cannot be determined by ``otool`` output analysis (i.e. ``plugins``). + .. versionadded:: 3.6 + 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"``). -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. +.. command:: copy_and_fixup_bundle -Then clear all the keys and call ``verify_app`` on the final bundle to -ensure that it is truly standalone. + .. code-block:: cmake -.. versionadded:: 3.6 - 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"``). + copy_and_fixup_bundle( ) -.. code-block:: cmake + Makes a copy of the bundle ```` at location ```` and then fixes up + the new copied bundle in-place at ````. - copy_and_fixup_bundle( ) +.. command:: verify_app -Makes a copy of the bundle ```` at location ```` and then fixes up -the new copied bundle in-place at ````. + .. code-block:: cmake -.. code-block:: cmake + verify_app( [IGNORE_ITEM ...]) - verify_app() + Verifies that an application ```` appears valid based on running + analysis tools on it. Calls :command:`message(FATAL_ERROR)` if the + application is not verified. -Verifies that an application ```` appears valid based on running -analysis tools on it. Calls :command:`message(FATAL_ERROR)` if the application -is not verified. + .. versionadded:: 3.6 + 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"``) -.. versionadded:: 3.6 - 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"``) +.. command:: get_bundle_main_executable -.. code-block:: cmake + .. code-block:: cmake - get_bundle_main_executable( ) + get_bundle_main_executable( ) -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. + 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. -.. code-block:: cmake +.. command:: get_dotapp_dir - get_dotapp_dir( ) + .. code-block:: cmake -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. + get_dotapp_dir( ) -The returned directory may or may not exist. + 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. -.. code-block:: cmake + The returned directory may or may not exist. - get_bundle_and_executable( ) +.. command:: get_bundle_and_executable -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 ```` and the path to its main executable in -````. + .. code-block:: cmake -.. code-block:: cmake + get_bundle_and_executable( ) - get_bundle_all_executables( ) + 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 ```` and the path to its main executable in + ````. -Scans ```` bundle recursively for all ```` executable -files and accumulates them into a variable. +.. command:: get_bundle_all_executables -.. code-block:: cmake + .. code-block:: cmake - get_item_key( ) + get_bundle_all_executables( ) -Given ```` file name, generate ```` 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 ``_`` + Scans ```` bundle recursively for all ```` executable + files and accumulates them into a variable. -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. +.. command:: get_item_key -.. code-block:: cmake + .. code-block:: cmake - clear_bundle_keys() + get_item_key( ) -Loop over the ```` list of keys, clearing all the variables -associated with each key. After the loop, clear the list of keys itself. + Given ```` file name, generate ```` 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 ``_`` -Caller of ``get_bundle_keys`` should call ``clear_bundle_keys`` when done with -list of keys. + 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. -.. code-block:: cmake +.. command:: get_item_rpaths - set_bundle_key_values( - []) + .. code-block:: cmake -Add ```` key to the list (if necessary) for the given item. -If added, also set all the variables associated with that key. + get_item_rpaths( ) -.. code-block:: cmake + Get RPATHS of the ```` file name and store them to the variable with + provided name ````. - get_bundle_keys( ) +.. command:: clear_bundle_keys -Loop over all the executable and library files within ```` bundle (and -given as extra ````) 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. + .. code-block:: cmake -.. versionadded:: 3.6 - 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"``) + clear_bundle_keys() -.. code-block:: cmake + Loop over the ```` list of keys, clearing all the variables + associated with each key. After the loop, clear the list of keys itself. - copy_resolved_item_into_bundle( ) + Caller of ``get_bundle_keys`` should call ``clear_bundle_keys`` when done with + list of keys. -Copy a resolved item into the bundle if necessary. -Copy is not necessary, if the ```` is "the same as" the -````. +.. command:: set_bundle_key_values -.. code-block:: cmake + .. code-block:: cmake - copy_resolved_framework_into_bundle( ) + set_bundle_key_values( + []) -Copy a resolved framework into the bundle if necessary. -Copy is not necessary, if the ```` is "the same as" the -````. + Add ```` key to the list (if necessary) for the given item. + If added, also set all the variables associated with that key. -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. +.. command:: get_bundle_keys -.. code-block:: cmake + .. code-block:: cmake - fixup_bundle_item( ) + get_bundle_keys( [IGNORE_ITEM ...]) -Get the direct/non-system prerequisites of the ````. -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.) + Loop over all the executable and library files within ```` bundle (and + given as extra ````) 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. -This function requires that the ```` 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 -libraries that must be fixed up, but that cannot be determined by -otool output analysis. (i.e., ``plugins``) + .. versionadded:: 3.6 + 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"``) -Also, change the id of the item being fixed up to its own -``_EMBEDDED_ITEM`` value. +.. command:: copy_resolved_item_into_bundle -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 -once. + .. code-block:: cmake -If the ``BU_CHMOD_BUNDLE_ITEMS`` variable is set then bundle items will be -marked writable before ``install_name_tool`` tries to change them. + copy_resolved_item_into_bundle( ) -.. code-block:: cmake + Copy a resolved item into the bundle if necessary. + Copy is not necessary, if the ```` is "the same as" the + ````. - verify_bundle_prerequisites( ) +.. command:: copy_resolved_framework_into_bundle -Verifies that the sum of all prerequisites of all files inside the -bundle are contained within the bundle or are ``system`` libraries, -presumed to exist everywhere. + .. code-block:: cmake -.. versionadded:: 3.6 - 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"``) + copy_resolved_framework_into_bundle( ) -.. code-block:: cmake + Copy a resolved framework into the bundle if necessary. + Copy is not necessary, if the ```` is "the same as" the + ````. - verify_bundle_symlinks( ) + 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. -Verifies that any symlinks found in the ```` 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. +.. command:: fixup_bundle_item + + .. code-block:: cmake + + fixup_bundle_item( ) + + Get the direct/non-system prerequisites of the ````. + 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.) + + This function requires that the ```` 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 + libraries that must be fixed up, but that cannot be determined by + otool output analysis. (i.e., ``plugins``) + + Also, change the id of the item being fixed up to its own + ``_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 + 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. + +.. command:: verify_bundle_prerequisites + + .. code-block:: cmake + + verify_bundle_prerequisites( + [IGNORE_ITEM ...]) + + Verifies that the sum of all prerequisites of all files inside the + bundle are contained within the bundle or are ``system`` libraries, + presumed to exist everywhere. + + .. versionadded:: 3.6 + 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"``) + +.. command:: verify_bundle_symlinks + + .. code-block:: cmake + + verify_bundle_symlinks( ) + + Verifies that any symlinks found in the ```` 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. #]=======================================================================] function(_warn_cmp0080)