| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
| "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| |
| |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
| |
| <title>BundleUtilities — CMake 3.8.2 Documentation</title> |
| |
| |
| <link rel="stylesheet" href="../_static/cmake.css" type="text/css" /> |
| <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> |
| |
| <script type="text/javascript"> |
| var DOCUMENTATION_OPTIONS = { |
| URL_ROOT: '../', |
| VERSION: '3.8.2', |
| COLLAPSE_INDEX: false, |
| FILE_SUFFIX: '.html', |
| HAS_SOURCE: true, |
| SOURCELINK_SUFFIX: '.txt' |
| }; |
| </script> |
| <script type="text/javascript" src="../_static/jquery.js"></script> |
| <script type="text/javascript" src="../_static/underscore.js"></script> |
| <script type="text/javascript" src="../_static/doctools.js"></script> |
| <link rel="shortcut icon" href="../_static/cmake-favicon.ico"/> |
| <link rel="index" title="Index" href="../genindex.html" /> |
| <link rel="search" title="Search" href="../search.html" /> |
| <link rel="next" title="CheckCCompilerFlag" href="CheckCCompilerFlag.html" /> |
| <link rel="prev" title="AndroidTestUtilities" href="AndroidTestUtilities.html" /> |
| </head> |
| <body role="document"> |
| <div class="related" role="navigation" aria-label="related navigation"> |
| <h3>Navigation</h3> |
| <ul> |
| <li class="right" style="margin-right: 10px"> |
| <a href="../genindex.html" title="General Index" |
| accesskey="I">index</a></li> |
| <li class="right" > |
| <a href="CheckCCompilerFlag.html" title="CheckCCompilerFlag" |
| accesskey="N">next</a> |</li> |
| <li class="right" > |
| <a href="AndroidTestUtilities.html" title="AndroidTestUtilities" |
| accesskey="P">previous</a> |</li> |
| <li> |
| <img src="../_static/cmake-logo-16.png" alt="" |
| style="vertical-align: middle; margin-top: -2px" /> |
| </li> |
| <li> |
| <a href="https://cmake.org/">CMake</a> » |
| </li> |
| <li> |
| <a href="../index.html">3.8.2 Documentation</a> » |
| </li> |
| |
| <li class="nav-item nav-item-1"><a href="../manual/cmake-modules.7.html" accesskey="U">cmake-modules(7)</a> »</li> |
| </ul> |
| </div> |
| |
| <div class="document"> |
| <div class="documentwrapper"> |
| <div class="bodywrapper"> |
| <div class="body" role="main"> |
| |
| <div class="section" id="bundleutilities"> |
| <span id="module:BundleUtilities"></span><h1>BundleUtilities<a class="headerlink" href="#bundleutilities" title="Permalink to this headline">ΒΆ</a></h1> |
| <p>Functions to help assemble a standalone bundle application.</p> |
| <p>A collection of CMake utility functions useful for dealing with .app |
| bundles on the Mac and bundle-like directories on any OS.</p> |
| <p>The following functions are provided by this module:</p> |
| <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">fixup_bundle</span> |
| <span class="n">copy_and_fixup_bundle</span> |
| <span class="n">verify_app</span> |
| <span class="n">get_bundle_main_executable</span> |
| <span class="n">get_dotapp_dir</span> |
| <span class="n">get_bundle_and_executable</span> |
| <span class="n">get_bundle_all_executables</span> |
| <span class="n">get_item_key</span> |
| <span class="n">get_item_rpaths</span> |
| <span class="n">clear_bundle_keys</span> |
| <span class="n">set_bundle_key_values</span> |
| <span class="n">get_bundle_keys</span> |
| <span class="n">copy_resolved_item_into_bundle</span> |
| <span class="n">copy_resolved_framework_into_bundle</span> |
| <span class="n">fixup_bundle_item</span> |
| <span class="n">verify_bundle_prerequisites</span> |
| <span class="n">verify_bundle_symlinks</span> |
| </pre></div> |
| </div> |
| <p>Requires CMake 2.6 or greater because it uses function, break and |
| PARENT_SCOPE. Also depends on GetPrerequisites.cmake.</p> |
| <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">FIXUP_BUNDLE</span><span class="p">(</span><span class="o"><</span><span class="n">app</span><span class="o">></span> <span class="o"><</span><span class="n">libs</span><span class="o">></span> <span class="o"><</span><span class="n">dirs</span><span class="o">></span><span class="p">)</span> |
| </pre></div> |
| </div> |
| <p>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.</p> |
| <p>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)</p> |
| <p>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.</p> |
| <p>Then clear all the keys and call verify_app on the final bundle to |
| ensure that it is truly standalone.</p> |
| <p>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”)</p> |
| <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">COPY_AND_FIXUP_BUNDLE</span><span class="p">(</span><span class="o"><</span><span class="n">src</span><span class="o">></span> <span class="o"><</span><span class="n">dst</span><span class="o">></span> <span class="o"><</span><span class="n">libs</span><span class="o">></span> <span class="o"><</span><span class="n">dirs</span><span class="o">></span><span class="p">)</span> |
| </pre></div> |
| </div> |
| <p>Makes a copy of the bundle <src> at location <dst> and then fixes up |
| the new copied bundle in-place at <dst>...</p> |
| <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">VERIFY_APP</span><span class="p">(</span><span class="o"><</span><span class="n">app</span><span class="o">></span><span class="p">)</span> |
| </pre></div> |
| </div> |
| <p>Verifies that an application <app> appears valid based on running |
| analysis tools on it. Calls “message(FATAL_ERROR” if the application |
| is not verified.</p> |
| <p>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”)</p> |
| <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">GET_BUNDLE_MAIN_EXECUTABLE</span><span class="p">(</span><span class="o"><</span><span class="n">bundle</span><span class="o">></span> <span class="o"><</span><span class="n">result_var</span><span class="o">></span><span class="p">)</span> |
| </pre></div> |
| </div> |
| <p>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.</p> |
| <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">GET_DOTAPP_DIR</span><span class="p">(</span><span class="o"><</span><span class="n">exe</span><span class="o">></span> <span class="o"><</span><span class="n">dotapp_dir_var</span><span class="o">></span><span class="p">)</span> |
| </pre></div> |
| </div> |
| <p>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.</p> |
| <p>The returned directory may or may not exist.</p> |
| <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">GET_BUNDLE_AND_EXECUTABLE</span><span class="p">(</span><span class="o"><</span><span class="n">app</span><span class="o">></span> <span class="o"><</span><span class="n">bundle_var</span><span class="o">></span> <span class="o"><</span><span class="n">executable_var</span><span class="o">></span> <span class="o"><</span><span class="n">valid_var</span><span class="o">></span><span class="p">)</span> |
| </pre></div> |
| </div> |
| <p>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></p> |
| <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">GET_BUNDLE_ALL_EXECUTABLES</span><span class="p">(</span><span class="o"><</span><span class="n">bundle</span><span class="o">></span> <span class="o"><</span><span class="n">exes_var</span><span class="o">></span><span class="p">)</span> |
| </pre></div> |
| </div> |
| <p>Scans the given bundle recursively for all executable files and |
| accumulates them into a variable.</p> |
| <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">GET_ITEM_KEY</span><span class="p">(</span><span class="o"><</span><span class="n">item</span><span class="o">></span> <span class="o"><</span><span class="n">key_var</span><span class="o">></span><span class="p">)</span> |
| </pre></div> |
| </div> |
| <p>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 “_”</p> |
| <p>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.</p> |
| <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">CLEAR_BUNDLE_KEYS</span><span class="p">(</span><span class="o"><</span><span class="n">keys_var</span><span class="o">></span><span class="p">)</span> |
| </pre></div> |
| </div> |
| <p>Loop over the list of keys, clearing all the variables associated with |
| each key. After the loop, clear the list of keys itself.</p> |
| <p>Caller of get_bundle_keys should call clear_bundle_keys when done with |
| list of keys.</p> |
| <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">SET_BUNDLE_KEY_VALUES</span><span class="p">(</span><span class="o"><</span><span class="n">keys_var</span><span class="o">></span> <span class="o"><</span><span class="n">context</span><span class="o">></span> <span class="o"><</span><span class="n">item</span><span class="o">></span> <span class="o"><</span><span class="n">exepath</span><span class="o">></span> <span class="o"><</span><span class="n">dirs</span><span class="o">></span> |
| <span class="o"><</span><span class="n">copyflag</span><span class="o">></span> <span class="p">[</span><span class="o"><</span><span class="n">rpaths</span><span class="o">></span><span class="p">])</span> |
| </pre></div> |
| </div> |
| <p>Add a key to the list (if necessary) for the given item. If added, |
| also set all the variables associated with that key.</p> |
| <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">GET_BUNDLE_KEYS</span><span class="p">(</span><span class="o"><</span><span class="n">app</span><span class="o">></span> <span class="o"><</span><span class="n">libs</span><span class="o">></span> <span class="o"><</span><span class="n">dirs</span><span class="o">></span> <span class="o"><</span><span class="n">keys_var</span><span class="o">></span><span class="p">)</span> |
| </pre></div> |
| </div> |
| <p>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.</p> |
| <p>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”)</p> |
| <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">COPY_RESOLVED_ITEM_INTO_BUNDLE</span><span class="p">(</span><span class="o"><</span><span class="n">resolved_item</span><span class="o">></span> <span class="o"><</span><span class="n">resolved_embedded_item</span><span class="o">></span><span class="p">)</span> |
| </pre></div> |
| </div> |
| <p>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.</p> |
| <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">COPY_RESOLVED_FRAMEWORK_INTO_BUNDLE</span><span class="p">(</span><span class="o"><</span><span class="n">resolved_item</span><span class="o">></span> <span class="o"><</span><span class="n">resolved_embedded_item</span><span class="o">></span><span class="p">)</span> |
| </pre></div> |
| </div> |
| <p>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.</p> |
| <p>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.</p> |
| <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">FIXUP_BUNDLE_ITEM</span><span class="p">(</span><span class="o"><</span><span class="n">resolved_embedded_item</span><span class="o">></span> <span class="o"><</span><span class="n">exepath</span><span class="o">></span> <span class="o"><</span><span class="n">dirs</span><span class="o">></span><span class="p">)</span> |
| </pre></div> |
| </div> |
| <p>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.)</p> |
| <p>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)</p> |
| <p>Also, change the id of the item being fixed up to its own |
| _EMBEDDED_ITEM value.</p> |
| <p>Accumulate changes in a local variable and make <em>one</em> call to |
| install_name_tool at the end of the function with all the changes at |
| once.</p> |
| <p>If the BU_CHMOD_BUNDLE_ITEMS variable is set then bundle items will be |
| marked writable before install_name_tool tries to change them.</p> |
| <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">VERIFY_BUNDLE_PREREQUISITES</span><span class="p">(</span><span class="o"><</span><span class="n">bundle</span><span class="o">></span> <span class="o"><</span><span class="n">result_var</span><span class="o">></span> <span class="o"><</span><span class="n">info_var</span><span class="o">></span><span class="p">)</span> |
| </pre></div> |
| </div> |
| <p>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.</p> |
| <p>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”)</p> |
| <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">VERIFY_BUNDLE_SYMLINKS</span><span class="p">(</span><span class="o"><</span><span class="n">bundle</span><span class="o">></span> <span class="o"><</span><span class="n">result_var</span><span class="o">></span> <span class="o"><</span><span class="n">info_var</span><span class="o">></span><span class="p">)</span> |
| </pre></div> |
| </div> |
| <p>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.</p> |
| </div> |
| |
| |
| </div> |
| </div> |
| </div> |
| <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> |
| <div class="sphinxsidebarwrapper"> |
| <h4>Previous topic</h4> |
| <p class="topless"><a href="AndroidTestUtilities.html" |
| title="previous chapter">AndroidTestUtilities</a></p> |
| <h4>Next topic</h4> |
| <p class="topless"><a href="CheckCCompilerFlag.html" |
| title="next chapter">CheckCCompilerFlag</a></p> |
| <div role="note" aria-label="source link"> |
| <h3>This Page</h3> |
| <ul class="this-page-menu"> |
| <li><a href="../_sources/module/BundleUtilities.rst.txt" |
| rel="nofollow">Show Source</a></li> |
| </ul> |
| </div> |
| <div id="searchbox" style="display: none" role="search"> |
| <h3>Quick search</h3> |
| <form class="search" action="../search.html" method="get"> |
| <div><input type="text" name="q" /></div> |
| <div><input type="submit" value="Go" /></div> |
| <input type="hidden" name="check_keywords" value="yes" /> |
| <input type="hidden" name="area" value="default" /> |
| </form> |
| </div> |
| <script type="text/javascript">$('#searchbox').show(0);</script> |
| </div> |
| </div> |
| <div class="clearer"></div> |
| </div> |
| <div class="related" role="navigation" aria-label="related navigation"> |
| <h3>Navigation</h3> |
| <ul> |
| <li class="right" style="margin-right: 10px"> |
| <a href="../genindex.html" title="General Index" |
| >index</a></li> |
| <li class="right" > |
| <a href="CheckCCompilerFlag.html" title="CheckCCompilerFlag" |
| >next</a> |</li> |
| <li class="right" > |
| <a href="AndroidTestUtilities.html" title="AndroidTestUtilities" |
| >previous</a> |</li> |
| <li> |
| <img src="../_static/cmake-logo-16.png" alt="" |
| style="vertical-align: middle; margin-top: -2px" /> |
| </li> |
| <li> |
| <a href="https://cmake.org/">CMake</a> » |
| </li> |
| <li> |
| <a href="../index.html">3.8.2 Documentation</a> » |
| </li> |
| |
| <li class="nav-item nav-item-1"><a href="../manual/cmake-modules.7.html" >cmake-modules(7)</a> »</li> |
| </ul> |
| </div> |
| <div class="footer" role="contentinfo"> |
| © Copyright 2000-2017 Kitware, Inc. and Contributors. |
| Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.2. |
| </div> |
| </body> |
| </html> |
