Help: Convert BundleUtilities help to block-style comment

1 files changed, 218 insertions, 217 deletions

diff --git a/Modules/BundleUtilities.cmake b/Modules/BundleUtilities.cmake
index 4727f03..f271521 100644
--- a/Modules/BundleUtilities.cmake
+++ b/Modules/BundleUtilities.cmake
@@ -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: