mirror of
https://github.com/reactos/CMake.git
synced 2025-03-06 19:08:43 +00:00
Help: Convert BundleUtilities help to block-style comment
This commit is contained in:
Kyle Edwards
parent
a9df54ec31
commit
3925407e76
@ -1,223 +1,224 @@
|
||||
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
|
||||
# file Copyright.txt or https://cmake.org/licensing for details.
|
||||
|
||||
#.rst:
|
||||
# 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.
|
||||
#
|
||||
# The following functions are provided by this module:
|
||||
#
|
||||
# ::
|
||||
#
|
||||
# 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
|
||||
#
|
||||
# Requires CMake 2.6 or greater because it uses function, break and
|
||||
# PARENT_SCOPE. Also depends on GetPrerequisites.cmake.
|
||||
#
|
||||
# ::
|
||||
#
|
||||
# FIXUP_BUNDLE(<app> <libs> <dirs>)
|
||||
#
|
||||
# Fix up a 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)
|
||||
#
|
||||
# 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
|
||||
# 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")
|
||||
#
|
||||
# ::
|
||||
#
|
||||
# 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(<app>)
|
||||
#
|
||||
# Verifies that an application <app> appears valid based on running
|
||||
# analysis tools on it. Calls "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")
|
||||
#
|
||||
# ::
|
||||
#
|
||||
# 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(<exe> <dotapp_dir_var>)
|
||||
#
|
||||
# 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.
|
||||
#
|
||||
# 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>
|
||||
#
|
||||
# ::
|
||||
#
|
||||
# GET_BUNDLE_ALL_EXECUTABLES(<bundle> <exes_var>)
|
||||
#
|
||||
# Scans the given bundle recursively for all executable files and
|
||||
# accumulates them into a variable.
|
||||
#
|
||||
# ::
|
||||
#
|
||||
# GET_ITEM_KEY(<item> <key_var>)
|
||||
#
|
||||
# Given a file (item) name, generate a 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.
|
||||
#
|
||||
# ::
|
||||
#
|
||||
# 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.
|
||||
#
|
||||
# Caller of get_bundle_keys should call clear_bundle_keys when done with
|
||||
# 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.
|
||||
#
|
||||
# ::
|
||||
#
|
||||
# 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
|
||||
# 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.
|
||||
#
|
||||
# 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(<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(<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_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.
|
||||
#
|
||||
# ::
|
||||
#
|
||||
# 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.
|
||||
#
|
||||
# ::
|
||||
#
|
||||
# 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,
|
||||
# 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")
|
||||
#
|
||||
# ::
|
||||
#
|
||||
# VERIFY_BUNDLE_SYMLINKS(<bundle> <result_var> <info_var>)
|
||||
#
|
||||
# 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.
|
||||
#[=======================================================================[.rst:
|
||||
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.
|
||||
|
||||
The following functions are provided by this module:
|
||||
|
||||
::
|
||||
|
||||
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
|
||||
|
||||
Requires CMake 2.6 or greater because it uses function, break and
|
||||
PARENT_SCOPE. Also depends on GetPrerequisites.cmake.
|
||||
|
||||
::
|
||||
|
||||
FIXUP_BUNDLE(<app> <libs> <dirs>)
|
||||
|
||||
Fix up a 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)
|
||||
|
||||
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
|
||||
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")
|
||||
|
||||
::
|
||||
|
||||
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(<app>)
|
||||
|
||||
Verifies that an application <app> appears valid based on running
|
||||
analysis tools on it. Calls "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")
|
||||
|
||||
::
|
||||
|
||||
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(<exe> <dotapp_dir_var>)
|
||||
|
||||
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.
|
||||
|
||||
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>
|
||||
|
||||
::
|
||||
|
||||
GET_BUNDLE_ALL_EXECUTABLES(<bundle> <exes_var>)
|
||||
|
||||
Scans the given bundle recursively for all executable files and
|
||||
accumulates them into a variable.
|
||||
|
||||
::
|
||||
|
||||
GET_ITEM_KEY(<item> <key_var>)
|
||||
|
||||
Given a file (item) name, generate a 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.
|
||||
|
||||
::
|
||||
|
||||
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.
|
||||
|
||||
Caller of get_bundle_keys should call clear_bundle_keys when done with
|
||||
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.
|
||||
|
||||
::
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
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(<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(<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_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.
|
||||
|
||||
::
|
||||
|
||||
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.
|
||||
|
||||
::
|
||||
|
||||
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,
|
||||
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")
|
||||
|
||||
::
|
||||
|
||||
VERIFY_BUNDLE_SYMLINKS(<bundle> <result_var> <info_var>)
|
||||
|
||||
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.
|
||||
#]=======================================================================]
|
||||
|
||||
# The functions defined in this file depend on the get_prerequisites function
|
||||
# (and possibly others) found in:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user