BundleUtilities¶
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 install(CODE) or
install(SCRIPT).
Functions¶
The following functions are provided by this module:
- fixup_bundle¶
fixup_bundle(<app> <libs> <dirs> [IGNORE_ITEM <file>...])
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_bundleas the libs parameter, you should install them or copy them into the bundle before callingfixup_bundle. The<libs>parameter is a list of libraries that must be fixed up, but that cannot be determined byotooloutput 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_appon the final bundle to ensure that it is truly standalone.Added in version 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¶
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>.
- verify_app¶
verify_app(<app> [IGNORE_ITEM <file>...])
Verifies that an application
<app>appears valid based on running analysis tools on it. Callsmessage(FATAL_ERROR)if the application is not verified.Added in version 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")
- get_bundle_main_executable¶
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.
- get_dotapp_dir¶
get_dotapp_dir(<exe> <dotapp_dir_var>)
Returns the nearest parent dir whose name ends with
.appgiven the full path to an executable. If there is no such parent dir, then simply return the dir containing the executable.The returned directory may or may not exist.
- get_bundle_and_executable¶
get_bundle_and_executable(<app> <bundle_var> <executable_var> <valid_var>)
Takes either a
.appdirectory name or the name of an executable nested inside a.appdirectory and returns the path to the.appdirectory in<bundle_var>and the path to its main executable in<executable_var>.
- get_bundle_all_executables¶
get_bundle_all_executables(<bundle> <exes_var>)
Scans
<bundle>bundle recursively for all<exes_var>executable files and accumulates them into a variable.
- get_item_key¶
get_item_key(<item> <key_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_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.
- get_item_rpaths¶
get_item_rpaths(<item> <rpaths_var>)
Get RPATHS of the
<item>file name and store them to the variable with provided name<rpaths_var>.
- clear_bundle_keys¶
clear_bundle_keys(<keys_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.Caller of
get_bundle_keysshould callclear_bundle_keyswhen done with list of keys.
- set_bundle_key_values¶
set_bundle_key_values(<keys_var> <context> <item> <exepath> <dirs> <copyflag> [<rpaths>])
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_bundle_keys¶
get_bundle_keys(<app> <libs> <dirs> <keys_var> [IGNORE_ITEM <file>...])
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 appropriateinstall_name_toolfixups.Added in version 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_item_into_bundle¶
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_resolved_framework_into_bundle¶
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>.By default,
BU_COPY_FULL_FRAMEWORK_CONTENTSis not set. If you want full frameworks embedded in your bundles, setBU_COPY_FULL_FRAMEWORK_CONTENTStoONbefore calling fixup_bundle. By default,COPY_RESOLVED_FRAMEWORK_INTO_BUNDLEcopies the framework dylib itself plus the frameworkResourcesdirectory.
- fixup_bundle_item¶
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_ITEMkeyed variable for that prerequisite. (Most likely changing to an@executable_pathstyle reference.)This function requires that the
<resolved_embedded_item>beinsidethe bundle already. In other words, if you pass plugins tofixup_bundleas the libs parameter, you should install them or copy them into the bundle before callingfixup_bundle. Thelibsparameter 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_ITEMvalue.Accumulate changes in a local variable and make one call to
install_name_toolat the end of the function with all the changes at once.If the
BU_CHMOD_BUNDLE_ITEMSvariable is set then bundle items will be marked writable beforeinstall_name_tooltries to change them.
- verify_bundle_prerequisites¶
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
systemlibraries, presumed to exist everywhere.Added in version 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")
- verify_bundle_symlinks¶
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.