mirror of
https://github.com/Kitware/CMake.git
synced 2026-01-06 05:40:54 -06:00
BundleUtilities: Update documentation
* Updated warnings at the top to a note * The provided functions are described as titled items and have code blocks added * Added missing documentation for the `get_item_rpaths()` function * Added `IGNORE_ITEM` option to relevant signatures
This commit is contained in:
Peter Kokot
@@ -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(<app> <libs> <dirs> [IGNORE_ITEM <file>...])
|
||||
|
||||
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 ``<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.
|
||||
|
||||
.. 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 ``<libs>`` 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(<app> <libs> <dirs>)
|
||||
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 ``<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.
|
||||
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 ``<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"``).
|
||||
|
||||
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(<src> <dst> <libs> <dirs>)
|
||||
|
||||
.. code-block:: cmake
|
||||
Makes a copy of the bundle ``<src>`` at location ``<dst>`` and then fixes up
|
||||
the new copied bundle in-place at ``<dst>``.
|
||||
|
||||
copy_and_fixup_bundle(<src> <dst> <libs> <dirs>)
|
||||
.. command:: verify_app
|
||||
|
||||
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
|
||||
|
||||
.. code-block:: cmake
|
||||
verify_app(<app> [IGNORE_ITEM <file>...])
|
||||
|
||||
verify_app(<app>)
|
||||
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.
|
||||
|
||||
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.
|
||||
.. 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(<bundle> <result_var>)
|
||||
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.
|
||||
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(<exe> <dotapp_dir_var>)
|
||||
.. 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(<exe> <dotapp_dir_var>)
|
||||
|
||||
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(<app> <bundle_var> <executable_var> <valid_var>)
|
||||
.. 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 ``<bundle_var>`` and the path to its main executable in
|
||||
``<executable_var>``.
|
||||
.. code-block:: cmake
|
||||
|
||||
.. code-block:: cmake
|
||||
get_bundle_and_executable(<app> <bundle_var> <executable_var> <valid_var>)
|
||||
|
||||
get_bundle_all_executables(<bundle> <exes_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>``.
|
||||
|
||||
Scans ``<bundle>`` bundle recursively for all ``<exes_var>`` executable
|
||||
files and accumulates them into a variable.
|
||||
.. command:: get_bundle_all_executables
|
||||
|
||||
.. code-block:: cmake
|
||||
.. code-block:: cmake
|
||||
|
||||
get_item_key(<item> <key_var>)
|
||||
get_bundle_all_executables(<bundle> <exes_var>)
|
||||
|
||||
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 ``_``
|
||||
Scans ``<bundle>`` bundle recursively for all ``<exes_var>`` 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(<keys_var>)
|
||||
get_item_key(<item> <key_var>)
|
||||
|
||||
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.
|
||||
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 ``_``
|
||||
|
||||
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(<keys_var> <context> <item> <exepath> <dirs>
|
||||
<copyflag> [<rpaths>])
|
||||
.. code-block:: cmake
|
||||
|
||||
Add ``<keys_var>`` key to the list (if necessary) for the given item.
|
||||
If added, also set all the variables associated with that key.
|
||||
get_item_rpaths(<item> <rpaths_var>)
|
||||
|
||||
.. code-block:: cmake
|
||||
Get RPATHS of the ``<item>`` file name and store them to the variable with
|
||||
provided name ``<rpaths_var>``.
|
||||
|
||||
get_bundle_keys(<app> <libs> <dirs> <keys_var>)
|
||||
.. command:: clear_bundle_keys
|
||||
|
||||
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.
|
||||
.. 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(<keys_var>)
|
||||
|
||||
.. code-block:: cmake
|
||||
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.
|
||||
|
||||
copy_resolved_item_into_bundle(<resolved_item> <resolved_embedded_item>)
|
||||
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 ``<resolved_item>`` is "the same as" the
|
||||
``<resolved_embedded_item>``.
|
||||
.. command:: set_bundle_key_values
|
||||
|
||||
.. code-block:: cmake
|
||||
.. code-block:: cmake
|
||||
|
||||
copy_resolved_framework_into_bundle(<resolved_item> <resolved_embedded_item>)
|
||||
set_bundle_key_values(<keys_var> <context> <item> <exepath> <dirs>
|
||||
<copyflag> [<rpaths>])
|
||||
|
||||
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>``.
|
||||
Add ``<keys_var>`` 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(<resolved_embedded_item> <exepath> <dirs>)
|
||||
get_bundle_keys(<app> <libs> <dirs> <keys_var> [IGNORE_ITEM <file>...])
|
||||
|
||||
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.)
|
||||
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.
|
||||
|
||||
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
|
||||
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(<resolved_item> <resolved_embedded_item>)
|
||||
|
||||
.. code-block:: cmake
|
||||
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>``.
|
||||
|
||||
verify_bundle_prerequisites(<bundle> <result_var> <info_var>)
|
||||
.. 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(<resolved_item> <resolved_embedded_item>)
|
||||
|
||||
.. code-block:: cmake
|
||||
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>``.
|
||||
|
||||
verify_bundle_symlinks(<bundle> <result_var> <info_var>)
|
||||
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>`` 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(<resolved_embedded_item> <exepath> <dirs>)
|
||||
|
||||
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.)
|
||||
|
||||
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
|
||||
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(<bundle> <result_var> <info_var>
|
||||
[IGNORE_ITEM <file>...])
|
||||
|
||||
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(<bundle> <result_var> <info_var>)
|
||||
|
||||
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.
|
||||
#]=======================================================================]
|
||||
|
||||
function(_warn_cmp0080)
|
||||
|
||||
Reference in New Issue
Block a user