| 1 | <?xml version="1.0" encoding="utf-8" ?> |
|---|
| 2 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
|---|
| 3 | <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
|---|
| 4 | <head> |
|---|
| 5 | <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
|---|
| 6 | <meta name="generator" content="Docutils 0.3.10: http://docutils.sourceforge.net/" /> |
|---|
| 7 | <title>PyInstaller Manual</title> |
|---|
| 8 | <meta name="author" content="William Caban (based on Gordon McMillan's manual)" /> |
|---|
| 9 | <meta name="copyright" content="This document has been placed in the public domain." /> |
|---|
| 10 | <link rel="stylesheet" href="stylesheets/default.css" type="text/css" /> |
|---|
| 11 | </head> |
|---|
| 12 | <body> |
|---|
| 13 | <div class="document" id="pyinstaller-manual"> |
|---|
| 14 | <h1 class="title">PyInstaller Manual</h1> |
|---|
| 15 | <table class="docinfo" frame="void" rules="none"> |
|---|
| 16 | <col class="docinfo-name" /> |
|---|
| 17 | <col class="docinfo-content" /> |
|---|
| 18 | <tbody valign="top"> |
|---|
| 19 | <tr><th class="docinfo-name">Author:</th> |
|---|
| 20 | <td>William Caban (based on Gordon McMillan's manual)</td></tr> |
|---|
| 21 | <tr><th class="docinfo-name">Contact:</th> |
|---|
| 22 | <td><a class="first last reference" href="mailto:william@hpcf.upr.edu">william@hpcf.upr.edu</a></td></tr> |
|---|
| 23 | <tr><th class="docinfo-name">Revision:</th> |
|---|
| 24 | <td>257</td></tr> |
|---|
| 25 | <tr class="field"><th class="docinfo-name">Source URL:</th><td class="field-body">svn://pyinstaller/trunk/doc/source/Manual.rst</td> |
|---|
| 26 | </tr> |
|---|
| 27 | <tr><th class="docinfo-name">Copyright:</th> |
|---|
| 28 | <td>This document has been placed in the public domain.</td></tr> |
|---|
| 29 | </tbody> |
|---|
| 30 | </table> |
|---|
| 31 | <div class="contents topic"> |
|---|
| 32 | <p class="topic-title first"><a id="contents" name="contents">Contents</a></p> |
|---|
| 33 | <ul class="simple"> |
|---|
| 34 | <li><a class="reference" href="#getting-started" id="id2" name="id2">Getting Started</a><ul> |
|---|
| 35 | <li><a class="reference" href="#installing-pyinstaller" id="id3" name="id3">Installing PyInstaller</a></li> |
|---|
| 36 | <li><a class="reference" href="#building-the-runtime-executables" id="id4" name="id4">Building the runtime executables</a></li> |
|---|
| 37 | <li><a class="reference" href="#configuring-your-pyinstaller-setup" id="id5" name="id5">Configuring your PyInstaller setup</a></li> |
|---|
| 38 | <li><a class="reference" href="#create-a-spec-file-for-your-project" id="id6" name="id6">Create a spec file for your project</a></li> |
|---|
| 39 | <li><a class="reference" href="#build-your-project" id="id7" name="id7">Build your project</a></li> |
|---|
| 40 | <li><a class="reference" href="#windows-com-server-support" id="id8" name="id8">Windows COM Server support</a></li> |
|---|
| 41 | <li><a class="reference" href="#building-optimized" id="id9" name="id9">Building Optimized</a></li> |
|---|
| 42 | <li><a class="reference" href="#a-note-on-using-upx" id="id10" name="id10">A Note on using UPX</a></li> |
|---|
| 43 | <li><a class="reference" href="#a-note-on-onefile" id="id11" name="id11">A Note on <tt class="docutils literal"><span class="pre">--onefile</span></tt></a></li> |
|---|
| 44 | <li><a class="reference" href="#a-note-on-egg-files-and-setuptools" id="id12" name="id12">A Note on .egg files and setuptools</a></li> |
|---|
| 45 | </ul> |
|---|
| 46 | </li> |
|---|
| 47 | <li><a class="reference" href="#pyinstaller-utilities" id="id13" name="id13">PyInstaller Utilities</a><ul> |
|---|
| 48 | <li><a class="reference" href="#archiveviewer" id="id14" name="id14">ArchiveViewer</a></li> |
|---|
| 49 | <li><a class="reference" href="#bindepend" id="id15" name="id15">bindepend</a></li> |
|---|
| 50 | <li><a class="reference" href="#grabversion-windows" id="id16" name="id16">GrabVersion (Windows)</a></li> |
|---|
| 51 | <li><a class="reference" href="#analyzing-dependencies" id="id17" name="id17">Analyzing Dependencies</a></li> |
|---|
| 52 | </ul> |
|---|
| 53 | </li> |
|---|
| 54 | <li><a class="reference" href="#spec-files" id="id18" name="id18">Spec Files</a><ul> |
|---|
| 55 | <li><a class="reference" href="#introduction" id="id19" name="id19">Introduction</a></li> |
|---|
| 56 | <li><a class="reference" href="#toc-class-table-of-contents" id="id20" name="id20">TOC Class (Table of Contents)</a></li> |
|---|
| 57 | <li><a class="reference" href="#target-subclasses" id="id21" name="id21">Target Subclasses</a><ul> |
|---|
| 58 | <li><a class="reference" href="#analysis" id="id22" name="id22">Analysis</a></li> |
|---|
| 59 | <li><a class="reference" href="#pyz" id="id23" name="id23">PYZ</a></li> |
|---|
| 60 | <li><a class="reference" href="#pkg" id="id24" name="id24">PKG</a></li> |
|---|
| 61 | <li><a class="reference" href="#exe" id="id25" name="id25">EXE</a></li> |
|---|
| 62 | <li><a class="reference" href="#dll" id="id26" name="id26">DLL</a></li> |
|---|
| 63 | <li><a class="reference" href="#collect" id="id27" name="id27">COLLECT</a></li> |
|---|
| 64 | <li><a class="reference" href="#tree" id="id28" name="id28">Tree</a></li> |
|---|
| 65 | </ul> |
|---|
| 66 | </li> |
|---|
| 67 | </ul> |
|---|
| 68 | </li> |
|---|
| 69 | <li><a class="reference" href="#when-things-go-wrong" id="id29" name="id29">When Things Go Wrong</a><ul> |
|---|
| 70 | <li><a class="reference" href="#finding-out-what-went-wrong" id="id30" name="id30">Finding out What Went Wrong</a><ul> |
|---|
| 71 | <li><a class="reference" href="#buildtime-warnings" id="id31" name="id31">Buildtime Warnings</a></li> |
|---|
| 72 | <li><a class="reference" href="#getting-debug-messages" id="id32" name="id32">Getting Debug Messages</a></li> |
|---|
| 73 | <li><a class="reference" href="#getting-python-s-verbose-imports" id="id33" name="id33">Getting Python's Verbose Imports</a></li> |
|---|
| 74 | </ul> |
|---|
| 75 | </li> |
|---|
| 76 | <li><a class="reference" href="#helping-installer-find-modules" id="id34" name="id34">Helping Installer Find Modules</a><ul> |
|---|
| 77 | <li><a class="reference" href="#extending-the-path" id="id35" name="id35">Extending the Path</a></li> |
|---|
| 78 | <li><a class="reference" href="#listing-hidden-imports" id="id36" name="id36">Listing Hidden Imports</a></li> |
|---|
| 79 | <li><a class="reference" href="#extending-a-package-s-path" id="id37" name="id37">Extending a Package's <tt class="docutils literal"><span class="pre">__path__</span></tt></a></li> |
|---|
| 80 | <li><a class="reference" href="#changing-runtime-behavior" id="id38" name="id38">Changing Runtime Behavior</a></li> |
|---|
| 81 | <li><a class="reference" href="#adapting-to-being-frozen" id="id39" name="id39">Adapting to being "frozen"</a></li> |
|---|
| 82 | <li><a class="reference" href="#accessing-data-files" id="id40" name="id40">Accessing Data Files</a></li> |
|---|
| 83 | </ul> |
|---|
| 84 | </li> |
|---|
| 85 | </ul> |
|---|
| 86 | </li> |
|---|
| 87 | <li><a class="reference" href="#miscellaneous" id="id41" name="id41">Miscellaneous</a><ul> |
|---|
| 88 | <li><a class="reference" href="#pmw-python-mega-widgets" id="id42" name="id42">Pmw -- Python Mega Widgets</a></li> |
|---|
| 89 | <li><a class="reference" href="#win9xpopen" id="id43" name="id43">Win9xpopen</a></li> |
|---|
| 90 | <li><a class="reference" href="#self-extracting-executables" id="id44" name="id44">Self-extracting executables</a><ul> |
|---|
| 91 | <li><a class="reference" href="#one-pass-execution" id="id45" name="id45">One Pass Execution</a></li> |
|---|
| 92 | <li><a class="reference" href="#two-pass-execution" id="id46" name="id46">Two Pass Execution</a></li> |
|---|
| 93 | </ul> |
|---|
| 94 | </li> |
|---|
| 95 | </ul> |
|---|
| 96 | </li> |
|---|
| 97 | <li><a class="reference" href="#pyinstaller-archives" id="id47" name="id47">PyInstaller Archives</a><ul> |
|---|
| 98 | <li><a class="reference" href="#archives-introduction" id="id48" name="id48">Archives Introduction</a></li> |
|---|
| 99 | <li><a class="reference" href="#zlibarchive" id="id49" name="id49"><tt class="docutils literal"><span class="pre">ZlibArchive</span></tt></a></li> |
|---|
| 100 | <li><a class="reference" href="#carchive" id="id50" name="id50"><tt class="docutils literal"><span class="pre">CArchive</span></tt></a></li> |
|---|
| 101 | </ul> |
|---|
| 102 | </li> |
|---|
| 103 | <li><a class="reference" href="#license" id="id51" name="id51">License</a></li> |
|---|
| 104 | <li><a class="reference" href="#appendix" id="id52" name="id52">Appendix</a><ul> |
|---|
| 105 | <li><a class="reference" href="#mf-py-a-modulefinder-replacement" id="id53" name="id53"><tt class="docutils literal"><span class="pre">mf.py</span></tt>: A Modulefinder Replacement</a><ul> |
|---|
| 106 | <li><a class="reference" href="#importtracker" id="id54" name="id54">ImportTracker</a></li> |
|---|
| 107 | <li><a class="reference" href="#analyze-one" id="id55" name="id55"><tt class="docutils literal"><span class="pre">analyze_one()</span></tt></a></li> |
|---|
| 108 | <li><a class="reference" href="#module-classes" id="id56" name="id56">Module Classes</a></li> |
|---|
| 109 | <li><a class="reference" href="#code-scanning" id="id57" name="id57">code scanning</a></li> |
|---|
| 110 | <li><a class="reference" href="#hooks" id="id58" name="id58">Hooks</a></li> |
|---|
| 111 | <li><a class="reference" href="#warnings" id="id59" name="id59">Warnings</a></li> |
|---|
| 112 | <li><a class="reference" href="#cross-reference" id="id60" name="id60">Cross Reference</a></li> |
|---|
| 113 | <li><a class="reference" href="#usage" id="id61" name="id61">Usage</a></li> |
|---|
| 114 | </ul> |
|---|
| 115 | </li> |
|---|
| 116 | <li><a class="reference" href="#iu-py-an-imputil-replacement" id="id62" name="id62"><tt class="docutils literal"><span class="pre">iu.py</span></tt>: An <em>imputil</em> Replacement</a><ul> |
|---|
| 117 | <li><a class="reference" href="#importmanager" id="id63" name="id63"><tt class="docutils literal"><span class="pre">ImportManager</span></tt></a></li> |
|---|
| 118 | <li><a class="reference" href="#importdirector" id="id64" name="id64"><tt class="docutils literal"><span class="pre">ImportDirector</span></tt></a></li> |
|---|
| 119 | <li><a class="reference" href="#pathimportdirector" id="id65" name="id65"><tt class="docutils literal"><span class="pre">PathImportDirector</span></tt></a></li> |
|---|
| 120 | <li><a class="reference" href="#owner" id="id66" name="id66"><tt class="docutils literal"><span class="pre">Owner</span></tt></a></li> |
|---|
| 121 | <li><a class="reference" href="#packages" id="id67" name="id67">Packages</a></li> |
|---|
| 122 | <li><a class="reference" href="#possibilities" id="id68" name="id68">Possibilities</a></li> |
|---|
| 123 | <li><a class="reference" href="#compatibility" id="id69" name="id69">Compatibility</a></li> |
|---|
| 124 | <li><a class="reference" href="#performance" id="id70" name="id70">Performance</a></li> |
|---|
| 125 | <li><a class="reference" href="#limitations" id="id71" name="id71">Limitations</a></li> |
|---|
| 126 | <li><a class="reference" href="#id1" id="id72" name="id72">Usage</a></li> |
|---|
| 127 | </ul> |
|---|
| 128 | </li> |
|---|
| 129 | </ul> |
|---|
| 130 | </li> |
|---|
| 131 | </ul> |
|---|
| 132 | </div> |
|---|
| 133 | <div class="section"> |
|---|
| 134 | <h1><a class="toc-backref" href="#id2" id="getting-started" name="getting-started">Getting Started</a></h1> |
|---|
| 135 | <div class="section"> |
|---|
| 136 | <h2><a class="toc-backref" href="#id3" id="installing-pyinstaller" name="installing-pyinstaller">Installing PyInstaller</a></h2> |
|---|
| 137 | <p>First, unpack the archive on you path of choice. Installer is <strong>not</strong> a Python |
|---|
| 138 | package, so it doesn't need to go in site-packages, or have a .pth file. For |
|---|
| 139 | the purpose of this documentation we will assume /your/path/to/pyinstaller/. You will be |
|---|
| 140 | using a couple of scripts in the /your/path/to/pyinstaller/ directory, and these will find |
|---|
| 141 | everything they need from their own location. For convenience, keep the paths |
|---|
| 142 | to these scripts short (don't install in a deeply nested subdirectory).</p> |
|---|
| 143 | <p>PyInstaller is dependant to the version of python you configure it for. In |
|---|
| 144 | other words, you will need a separate copy of PyInstaller for each Python |
|---|
| 145 | version you wish to work with <em>or</em> you'll need to rerun <tt class="docutils literal"><span class="pre">Configure.py</span></tt> every |
|---|
| 146 | time you switch the Python version).</p> |
|---|
| 147 | <p><a class="reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 148 | </div> |
|---|
| 149 | <div class="section"> |
|---|
| 150 | <h2><a class="toc-backref" href="#id4" id="building-the-runtime-executables" name="building-the-runtime-executables">Building the runtime executables</a></h2> |
|---|
| 151 | <p><em>Note:</em> Windows users can skip this step, because all of Python is contained in |
|---|
| 152 | pythonXX.dll, and PyInstaller will use your pythonXX.dll.</p> |
|---|
| 153 | <p>On Linux the first thing to do is build the runtime executables.</p> |
|---|
| 154 | <p>Change to the /your/path/to/pyinstaller/ <tt class="docutils literal"><span class="pre">source/linux</span></tt> subdirectory. Run <tt class="docutils literal"><span class="pre">Make.py</span> |
|---|
| 155 | <span class="pre">[-n|-e]</span></tt> and then make. This will produce <tt class="docutils literal"><span class="pre">support/loader/run</span></tt> and |
|---|
| 156 | <tt class="docutils literal"><span class="pre">support/loader/run_d</span></tt>, which are the bootloaders.</p> |
|---|
| 157 | <div class="sidebar"> |
|---|
| 158 | <p class="first sidebar-title">Bootloader</p> |
|---|
| 159 | <p class="last">The bootloader (also known as <em>stub</em> in literature) is the small program |
|---|
| 160 | which starts up your packaged program. Usually, the archive containing the |
|---|
| 161 | bytecoded modules of your program is simply attended to it. See |
|---|
| 162 | <a class="reference" href="#self-extracting-executables">Self-extracting executables</a> for more details on the process.</p> |
|---|
| 163 | </div> |
|---|
| 164 | <p><em>Note:</em> If you have multiple versions of Python, the Python you use to run |
|---|
| 165 | <tt class="docutils literal"><span class="pre">Make.py</span></tt> is the one whose configuration is used.</p> |
|---|
| 166 | <p>The <tt class="docutils literal"><span class="pre">-n</span></tt> and <tt class="docutils literal"><span class="pre">-e</span></tt> options set a non-elf or elf flag in your <tt class="docutils literal"><span class="pre">config.dat</span></tt>. |
|---|
| 167 | As of v1.0, the executable will try both strategies, and this flag |
|---|
| 168 | just sets how you want your executables built. In the elf strategy, the archive |
|---|
| 169 | is concatenated to the executable. In the non-elf strategy, the executable |
|---|
| 170 | expects an archive with the same name as itself in the executable's directory. |
|---|
| 171 | Note that the executable chases down symbolic links before determining it's name |
|---|
| 172 | and directory, so putting the archive in the same directory as the symbolic link |
|---|
| 173 | will not work.</p> |
|---|
| 174 | <p>Windows distributions come with several executables in the <tt class="docutils literal"><span class="pre">support/loader</span></tt> |
|---|
| 175 | directory: <tt class="docutils literal"><span class="pre">run_*.exe</span></tt> (bootloader for regular programs), and |
|---|
| 176 | <tt class="docutils literal"><span class="pre">inprocsrvr_*.dll</span></tt> (bootloader for in-process COM servers). To rebuild this, |
|---|
| 177 | you need to install <a class="reference" href="http://www.scons.org">Scons</a>, and then just run <tt class="docutils literal"><span class="pre">scons</span></tt> from the /your/path/to/pyinstaller/ |
|---|
| 178 | directory.</p> |
|---|
| 179 | <p><a class="reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 180 | </div> |
|---|
| 181 | <div class="section"> |
|---|
| 182 | <h2><a class="toc-backref" href="#id5" id="configuring-your-pyinstaller-setup" name="configuring-your-pyinstaller-setup">Configuring your PyInstaller setup</a></h2> |
|---|
| 183 | <p>In the /your/path/to/pyinstaller/ directory, run <tt class="docutils literal"><span class="pre">Configure.py</span></tt>. This saves some |
|---|
| 184 | information into <tt class="docutils literal"><span class="pre">config.dat</span></tt> that would otherwise be recomputed every time. |
|---|
| 185 | It can be rerun at any time if your configuration changes. It must be run before |
|---|
| 186 | trying to build anything.</p> |
|---|
| 187 | <p><a class="reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 188 | </div> |
|---|
| 189 | <div class="section"> |
|---|
| 190 | <h2><a class="toc-backref" href="#id6" id="create-a-spec-file-for-your-project" name="create-a-spec-file-for-your-project">Create a spec file for your project</a></h2> |
|---|
| 191 | <p>[For Windows COM server support, see section <a class="reference" href="#windows-com-server-support">Windows COM Server Support</a>]</p> |
|---|
| 192 | <p>The root directory has a script Makespec.py for this purpose:</p> |
|---|
| 193 | <pre class="literal-block"> |
|---|
| 194 | python Makespec.py [opts] <scriptname> [<scriptname> ...] |
|---|
| 195 | </pre> |
|---|
| 196 | <p>Where allowed OPTIONS are:</p> |
|---|
| 197 | <table class="docutils option-list" frame="void" rules="none"> |
|---|
| 198 | <col class="option" /> |
|---|
| 199 | <col class="description" /> |
|---|
| 200 | <tbody valign="top"> |
|---|
| 201 | <tr><td class="option-group"> |
|---|
| 202 | <kbd><span class="option">-F</span>, <span class="option">--onefile</span></kbd></td> |
|---|
| 203 | <td>produce a single file deployment (see below).</td></tr> |
|---|
| 204 | <tr><td class="option-group"> |
|---|
| 205 | <kbd><span class="option">-D</span>, <span class="option">--onedir</span></kbd></td> |
|---|
| 206 | <td>produce a single directory deployment (default).</td></tr> |
|---|
| 207 | <tr><td class="option-group"> |
|---|
| 208 | <kbd><span class="option">-K</span>, <span class="option">--tk</span></kbd></td> |
|---|
| 209 | <td>include TCL/TK in the deployment.</td></tr> |
|---|
| 210 | <tr><td class="option-group"> |
|---|
| 211 | <kbd><span class="option">-a</span>, <span class="option">--ascii</span></kbd></td> |
|---|
| 212 | <td>do not include encodings. The default (on Python versions with unicode |
|---|
| 213 | support) is now to include all encodings.</td></tr> |
|---|
| 214 | <tr><td class="option-group"> |
|---|
| 215 | <kbd><span class="option">-d</span>, <span class="option">--debug</span></kbd></td> |
|---|
| 216 | <td>use debug (verbose) versions of the executables.</td></tr> |
|---|
| 217 | <tr><td class="option-group" colspan="2"> |
|---|
| 218 | <kbd><span class="option">-w</span>, <span class="option">--windowed</span>, <span class="option">--noconsole</span></kbd></td> |
|---|
| 219 | </tr> |
|---|
| 220 | <tr><td> </td><td>Use the Windows subsystem executable, which does not open |
|---|
| 221 | the console when the program is launched. <strong>(Windows only)</strong></td></tr> |
|---|
| 222 | <tr><td class="option-group" colspan="2"> |
|---|
| 223 | <kbd><span class="option">-c</span>, <span class="option">--nowindowed</span>, <span class="option">--console</span></kbd></td> |
|---|
| 224 | </tr> |
|---|
| 225 | <tr><td> </td><td>Use the console subsystem executable. This is the default. <strong>(Windows only)</strong></td></tr> |
|---|
| 226 | <tr><td class="option-group"> |
|---|
| 227 | <kbd><span class="option">-s</span>, <span class="option">--strip</span></kbd></td> |
|---|
| 228 | <td>the executable and all shared libraries will be run through strip. Note |
|---|
| 229 | that cygwin's strip tends to render normal Win32 dlls unusable.</td></tr> |
|---|
| 230 | <tr><td class="option-group"> |
|---|
| 231 | <kbd><span class="option">-X</span>, <span class="option">--upx</span></kbd></td> |
|---|
| 232 | <td>if you have UPX installed (detected by Configure), this will use it to |
|---|
| 233 | compress your executable (and, on Windows, your dlls). See note below.</td></tr> |
|---|
| 234 | <tr><td class="option-group" colspan="2"> |
|---|
| 235 | <kbd><span class="option">-o <var>DIR</var></span>, <span class="option">--out=<var>DIR</var></span></kbd></td> |
|---|
| 236 | </tr> |
|---|
| 237 | <tr><td> </td><td>create the spec file in <em>directory</em>. If not specified, and the current |
|---|
| 238 | directory is Installer's root directory, an output subdirectory will be |
|---|
| 239 | created. Otherwise the current directory is used.</td></tr> |
|---|
| 240 | <tr><td class="option-group" colspan="2"> |
|---|
| 241 | <kbd><span class="option">-p <var>DIR</var></span>, <span class="option">--paths=<var>DIR</var></span></kbd></td> |
|---|
| 242 | </tr> |
|---|
| 243 | <tr><td> </td><td>set base path for import (like using PYTHONPATH). Multiple directories are |
|---|
| 244 | allowed, separating them with the path separator (';' under Windows, ':' |
|---|
| 245 | under Linux), or using this option multiple times.</td></tr> |
|---|
| 246 | <tr><td class="option-group" colspan="2"> |
|---|
| 247 | <kbd><span class="option">--icon=<var><FILE.ICO></var></span></kbd></td> |
|---|
| 248 | </tr> |
|---|
| 249 | <tr><td> </td><td>add <em>file.ico</em> to the executable's resources. <strong>(Windows only)</strong></td></tr> |
|---|
| 250 | <tr><td class="option-group" colspan="2"> |
|---|
| 251 | <kbd><span class="option">--icon=<var><FILE.EXE,N></var></span></kbd></td> |
|---|
| 252 | </tr> |
|---|
| 253 | <tr><td> </td><td>add the <em>n</em>-th incon in <em>file.exe</em> to the executable's resources. <strong>(Windows |
|---|
| 254 | only)</strong></td></tr> |
|---|
| 255 | <tr><td class="option-group" colspan="2"> |
|---|
| 256 | <kbd><span class="option">-v <var>FILE</var></span>, <span class="option">--version=<var>FILE</var></span></kbd></td> |
|---|
| 257 | </tr> |
|---|
| 258 | <tr><td> </td><td>add verfile as a version resource to the executable. <strong>(Windows only)</strong></td></tr> |
|---|
| 259 | <tr><td class="option-group" colspan="2"> |
|---|
| 260 | <kbd><span class="option">-n <var>NAME</var></span>, <span class="option">--name=<var>NAME</var></span></kbd></td> |
|---|
| 261 | </tr> |
|---|
| 262 | <tr><td> </td><td>optional <em>name</em> to assign to the project (from which the spec file name is |
|---|
| 263 | generated). If omitted, the basename of the (first) script is used.</td></tr> |
|---|
| 264 | </tbody> |
|---|
| 265 | </table> |
|---|
| 266 | <p>[For building with optimization on (like <tt class="docutils literal"><span class="pre">Python</span> <span class="pre">-O</span></tt>), see section |
|---|
| 267 | <a class="reference" href="#building-optimized">Building Optimized</a>]</p> |
|---|
| 268 | <p>For simple projects, the generated spec file will probably be sufficient. For |
|---|
| 269 | more complex projects, it should be regarded as a template. The spec file is |
|---|
| 270 | actually Python code, and modifying it should be ease. See <a class="reference" href="#spec-files">Spec Files</a> for |
|---|
| 271 | details.</p> |
|---|
| 272 | <p><a class="reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 273 | </div> |
|---|
| 274 | <div class="section"> |
|---|
| 275 | <h2><a class="toc-backref" href="#id7" id="build-your-project" name="build-your-project">Build your project</a></h2> |
|---|
| 276 | <pre class="literal-block"> |
|---|
| 277 | python Build.py specfile |
|---|
| 278 | </pre> |
|---|
| 279 | <p>A <tt class="docutils literal"><span class="pre">buildproject</span></tt> subdirectory will be created in the specfile's directory. This |
|---|
| 280 | is a private workspace so that <tt class="docutils literal"><span class="pre">Build.py</span></tt> can act like a makefile. Any named |
|---|
| 281 | targets will appear in the specfile's directory. For <tt class="docutils literal"><span class="pre">--onedir</span></tt> |
|---|
| 282 | configurations, it will create also <tt class="docutils literal"><span class="pre">distproject</span></tt>, which is the directory you're |
|---|
| 283 | interested in. For a <tt class="docutils literal"><span class="pre">--onefile</span></tt>, the executable will be in the specfile's |
|---|
| 284 | directory.</p> |
|---|
| 285 | <p>In most cases, this will be all you have to do. If not, see <a class="reference" href="#when-things-go-wrong">When things go |
|---|
| 286 | wrong</a> and be sure to read the introduction to <a class="reference" href="#spec-files">Spec Files</a>.</p> |
|---|
| 287 | <p><a class="reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 288 | </div> |
|---|
| 289 | <div class="section"> |
|---|
| 290 | <h2><a class="toc-backref" href="#id8" id="windows-com-server-support" name="windows-com-server-support">Windows COM Server support</a></h2> |
|---|
| 291 | <p>For Windows COM support execute:</p> |
|---|
| 292 | <pre class="literal-block"> |
|---|
| 293 | python MakeCOMServer.py [OPTION] script... |
|---|
| 294 | </pre> |
|---|
| 295 | <p>This will generate a new script <tt class="docutils literal"><span class="pre">drivescript.py</span></tt> and a spec file for the script.</p> |
|---|
| 296 | <p>These options are allowed:</p> |
|---|
| 297 | <table class="docutils option-list" frame="void" rules="none"> |
|---|
| 298 | <col class="option" /> |
|---|
| 299 | <col class="description" /> |
|---|
| 300 | <tbody valign="top"> |
|---|
| 301 | <tr><td class="option-group"> |
|---|
| 302 | <kbd><span class="option">--debug</span></kbd></td> |
|---|
| 303 | <td>Use the verbose version of the executable.</td></tr> |
|---|
| 304 | <tr><td class="option-group"> |
|---|
| 305 | <kbd><span class="option">--verbose</span></kbd></td> |
|---|
| 306 | <td>Register the COM server(s) with the quiet flag off.</td></tr> |
|---|
| 307 | <tr><td class="option-group"> |
|---|
| 308 | <kbd><span class="option">--ascii</span></kbd></td> |
|---|
| 309 | <td>do not include encodings (this is passed through to Makespec).</td></tr> |
|---|
| 310 | <tr><td class="option-group"> |
|---|
| 311 | <kbd><span class="option">--out <var><dir></var></span></kbd></td> |
|---|
| 312 | <td>Generate the driver script and spec file in dir.</td></tr> |
|---|
| 313 | </tbody> |
|---|
| 314 | </table> |
|---|
| 315 | <p>Now <a class="reference" href="#build-your-project">Build your project</a> on the generated spec file.</p> |
|---|
| 316 | <p>If you have the win32dbg package installed, you can use it with the generated |
|---|
| 317 | COM server. In the driver script, set <tt class="docutils literal"><span class="pre">debug=1</span></tt> in the registration line.</p> |
|---|
| 318 | <p><strong>Warnings</strong>: the inprocess COM server support will not work when the client |
|---|
| 319 | process already has Python loaded. It would be rather tricky to |
|---|
| 320 | non-obtrusively hook into an already running Python, but the show-stopper is |
|---|
| 321 | that the Python/C API won't let us find out which interpreter instance I should |
|---|
| 322 | hook into. (If this is important to you, you might experiment with using |
|---|
| 323 | apartment threading, which seems the best possibility to get this to work). To |
|---|
| 324 | use a "frozen" COM server from a Python process, you'll have to load it as an |
|---|
| 325 | exe:</p> |
|---|
| 326 | <pre class="literal-block"> |
|---|
| 327 | o = win32com.client.Dispatch(progid, |
|---|
| 328 | clsctx=pythoncom.CLSCTX_LOCAL_SERVER) |
|---|
| 329 | </pre> |
|---|
| 330 | <p>MakeCOMServer also assumes that your top level code (registration etc.) is |
|---|
| 331 | "normal". If it's not, you will have to edit the generated script.</p> |
|---|
| 332 | <p><a class="reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 333 | </div> |
|---|
| 334 | <div class="section"> |
|---|
| 335 | <h2><a class="toc-backref" href="#id9" id="building-optimized" name="building-optimized">Building Optimized</a></h2> |
|---|
| 336 | <p>There are two facets to running optimized: gathering <tt class="docutils literal"><span class="pre">.pyo</span></tt>'s, and setting the |
|---|
| 337 | <tt class="docutils literal"><span class="pre">Py_OptimizeFlag</span></tt>. Installer will gather <tt class="docutils literal"><span class="pre">.pyo</span></tt>'s if it is run optimized:</p> |
|---|
| 338 | <pre class="literal-block"> |
|---|
| 339 | python -O Build.py ... |
|---|
| 340 | </pre> |
|---|
| 341 | <p>The <tt class="docutils literal"><span class="pre">Py_OptimizeFlag</span></tt> will be set if you use a <tt class="docutils literal"><span class="pre">('O','','OPTION')</span></tt> in one of |
|---|
| 342 | the <tt class="docutils literal"><span class="pre">TOCs</span></tt> building the <tt class="docutils literal"><span class="pre">EXE</span></tt>:</p> |
|---|
| 343 | <pre class="literal-block"> |
|---|
| 344 | exe = EXE(pyz, |
|---|
| 345 | a.scripts + [('O','','OPTION')], |
|---|
| 346 | ... |
|---|
| 347 | </pre> |
|---|
| 348 | <p>See <a class="reference" href="#spec-files">Spec Files</a> for details.</p> |
|---|
| 349 | <p><a class="reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 350 | </div> |
|---|
| 351 | <div class="section"> |
|---|
| 352 | <h2><a class="toc-backref" href="#id10" id="a-note-on-using-upx" name="a-note-on-using-upx">A Note on using UPX</a></h2> |
|---|
| 353 | <p>On both Windows and Linux, UPX can give truly startling compression - the days |
|---|
| 354 | of fitting something useful on a diskette are not gone forever! Installer has |
|---|
| 355 | been tested with many UPX versions without problems. Just get it and install it |
|---|
| 356 | on your PATH, then rerun configure.</p> |
|---|
| 357 | <p>For Windows, there is a problem of compatibility between UPX and executables |
|---|
| 358 | generated by Microsoft Visual Studio .NET 2003 (or the equivalent free |
|---|
| 359 | toolkit available for download). This is especially worrisome for users of |
|---|
| 360 | Python 2.4+, where most extensions (and Python itself) are compiled with that |
|---|
| 361 | compiler. This issue has been fixed in later beta versions of UPX, so you |
|---|
| 362 | will need at least UPX 1.92 beta. <a class="reference" href="#configuring-your-pyinstaller-setup">Configure.py</a> will check this for you |
|---|
| 363 | and complain if you have an older version of UPX and you are using Python 2.4.</p> |
|---|
| 364 | <div class="sidebar"> |
|---|
| 365 | <p class="first sidebar-title">UPX and Unix</p> |
|---|
| 366 | <p class="last">Under UNIX, old versions of UPX were not able to expand and execute the |
|---|
| 367 | executable in memory, and they were extracting it into a temporary file |
|---|
| 368 | in the filesystem, before spawning it. This is no longer valid under Linux, |
|---|
| 369 | but the information in this paragraph still needs to be updated.</p> |
|---|
| 370 | </div> |
|---|
| 371 | <p>For Linux, a bit more discussion is in order. First, UPX is only useful on |
|---|
| 372 | executables, not shared libs. Installer accounts for that, but to get the full |
|---|
| 373 | benefit, you might rebuild Python with more things statically linked.</p> |
|---|
| 374 | <p>More importantly, when <tt class="docutils literal"><span class="pre">run</span></tt> finds that its <tt class="docutils literal"><span class="pre">sys.argv[0]</span></tt> does not contain a path, |
|---|
| 375 | it will use <tt class="docutils literal"><span class="pre">/proc/pid/exe</span></tt> to find itself (if it can). This happens, for |
|---|
| 376 | example, when executed by Apache. If it has been upx-ed, this symbolic link |
|---|
| 377 | points to the tempfile created by the upx stub and PyInstaller will fail (please |
|---|
| 378 | see the UPX docs for more information). So for now, at least, you can't use upx |
|---|
| 379 | for CGI's executed by Apache. Otherwise, you can ignore the warnings in the UPX |
|---|
| 380 | docs, since what PyInstaller opens is the executable Installer created, not the |
|---|
| 381 | temporary upx-created executable.</p> |
|---|
| 382 | <p><a class="reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 383 | </div> |
|---|
| 384 | <div class="section"> |
|---|
| 385 | <h2><a class="toc-backref" href="#id11" id="a-note-on-onefile" name="a-note-on-onefile">A Note on <tt class="docutils literal docutils literal"><span class="pre">--onefile</span></tt></a></h2> |
|---|
| 386 | <p>A <tt class="docutils literal"><span class="pre">--onefile</span></tt> works by packing all the shared libs / dlls into the archive |
|---|
| 387 | attached to the bootloader executable (or next to the executable in a non-elf |
|---|
| 388 | configuration). When first started, it finds that it needs to extract these |
|---|
| 389 | files before it can run "for real". That's because locating and loading a |
|---|
| 390 | shared lib or linked-in dll is a system level action, not user-level. With |
|---|
| 391 | PyInstaller v1.0 it always uses a temporary directory (<tt class="docutils literal"><span class="pre">_MEIpid</span></tt>) in the |
|---|
| 392 | user's temp directory. It then executes itself again, setting things up so |
|---|
| 393 | the system will be able to load the shared libs / dlls. When executing is |
|---|
| 394 | complete, it recursively removes the entire directory it created.</p> |
|---|
| 395 | <p>This has a number of implications:</p> |
|---|
| 396 | <ul class="simple"> |
|---|
| 397 | <li>You can run multiple copies - they won't collide.</li> |
|---|
| 398 | <li>Running multiple copies will be rather expensive to the system (nothing is |
|---|
| 399 | shared).</li> |
|---|
| 400 | <li>If you're using the cheat of adding user data as <tt class="docutils literal"><span class="pre">'BINARY'</span></tt>, it will be in |
|---|
| 401 | <tt class="docutils literal"><span class="pre">os.environ['_MEIPASS2']</span></tt>, not in the executable's directory.</li> |
|---|
| 402 | <li>On Windows, using Task Manager to kill the parent process will leave the |
|---|
| 403 | directory behind.</li> |
|---|
| 404 | <li>On *nix, a kill -9 (or crash) will leave the directory behind.</li> |
|---|
| 405 | <li>Otherwise, on both platforms, the directory will be recursively deleted.</li> |
|---|
| 406 | <li>So any files you might create in <tt class="docutils literal"><span class="pre">os.environ['_MEIPASS2']</span></tt> will be deleted.</li> |
|---|
| 407 | <li>The executable can be in a protected or read-only directory.</li> |
|---|
| 408 | <li>If for some reason, the <tt class="docutils literal"><span class="pre">_MEIpid</span></tt> directory already exists, the executable |
|---|
| 409 | will fail. It is created mode 0700, so only the one user can modify it |
|---|
| 410 | (on *nix, of course).</li> |
|---|
| 411 | </ul> |
|---|
| 412 | <p>While we are not a security expert, we believe the scheme is good enough for |
|---|
| 413 | most of the users.</p> |
|---|
| 414 | <p><strong>Notes for *nix users</strong>: Take notice that if the executable does a setuid root, |
|---|
| 415 | a determined hacker could possibly (given enough tries) introduce a malicious |
|---|
| 416 | lookalike of one of the shared libraries during the hole between when the |
|---|
| 417 | library is extracted and when it gets loaded by the execvp'd process. So maybe |
|---|
| 418 | you shouldn't do setuid root programs using <tt class="docutils literal"><span class="pre">--onefile</span></tt>. <strong>In fact, we do not |
|---|
| 419 | recomend the use of --onefile on setuid programs.</strong></p> |
|---|
| 420 | <p><a class="reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 421 | </div> |
|---|
| 422 | <div class="section"> |
|---|
| 423 | <h2><a class="toc-backref" href="#id12" id="a-note-on-egg-files-and-setuptools" name="a-note-on-egg-files-and-setuptools">A Note on .egg files and setuptools</a></h2> |
|---|
| 424 | <p><a class="reference" href="http://peak.telecommunity.com/DevCenter/setuptools">setuptools</a> is a distutils extensions which provide many benefits, including |
|---|
| 425 | the ability to distribute the extension as <tt class="docutils literal"><span class="pre">egg</span></tt> files. Together with the |
|---|
| 426 | nifty <a class="reference" href="http://peak.telecommunity.com/DevCenter/EasyInstall">easy_install</a> (a tool which automatically locates, downloads and |
|---|
| 427 | installs Python extensions), <tt class="docutils literal"><span class="pre">egg</span></tt> files are becoming more and more |
|---|
| 428 | widespread as a way for distributing Python extensions.</p> |
|---|
| 429 | <p><tt class="docutils literal"><span class="pre">egg</span></tt> files are actually ZIP files under the hood, and they rely on the fact |
|---|
| 430 | that Python 2.4 is able to transparently import modules stored within ZIP |
|---|
| 431 | files. PyInstaller is currently <em>not</em> able to import and extract modules |
|---|
| 432 | within ZIP files, so code which uses extensions packaged as <tt class="docutils literal"><span class="pre">egg</span></tt> files |
|---|
| 433 | cannot be packaged with PyInstaller.</p> |
|---|
| 434 | <p>The workaround is pretty easy: you can use <tt class="docutils literal"><span class="pre">easy_install</span> <span class="pre">-Z</span></tt> at installation |
|---|
| 435 | time to ask <tt class="docutils literal"><span class="pre">easy_install</span></tt> to always decompress egg files. This will allow |
|---|
| 436 | PyInstaller to see the files and make the package correctly. If you have already |
|---|
| 437 | installed the modules, you can simply decompress them within a directory with |
|---|
| 438 | the same name of the <tt class="docutils literal"><span class="pre">egg</span></tt> file (including also the extension).</p> |
|---|
| 439 | <p>Support for <tt class="docutils literal"><span class="pre">egg</span></tt> files is planned for a future release of PyInstaller.</p> |
|---|
| 440 | <p><a class="reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 441 | </div> |
|---|
| 442 | </div> |
|---|
| 443 | <div class="section"> |
|---|
| 444 | <h1><a class="toc-backref" href="#id13" id="pyinstaller-utilities" name="pyinstaller-utilities">PyInstaller Utilities</a></h1> |
|---|
| 445 | <div class="section"> |
|---|
| 446 | <h2><a class="toc-backref" href="#id14" id="archiveviewer" name="archiveviewer">ArchiveViewer</a></h2> |
|---|
| 447 | <pre class="literal-block"> |
|---|
| 448 | python ArchiveViewer.py <archivefile> |
|---|
| 449 | </pre> |
|---|
| 450 | <p>ArchiveViewer lets you examine the contents of any archive build with |
|---|
| 451 | PyInstaller or executable (PYZ, PKG or exe). Invoke it with the target as the |
|---|
| 452 | first arg (It has been set up as a Send-To so it shows on the context menu in |
|---|
| 453 | Explorer). The archive can be navigated using these commands:</p> |
|---|
| 454 | <dl class="docutils"> |
|---|
| 455 | <dt>O <nm></dt> |
|---|
| 456 | <dd>Open the embedded archive <nm> (will prompt if omitted).</dd> |
|---|
| 457 | <dt>U</dt> |
|---|
| 458 | <dd>Go up one level (go back to viewing the embedding archive).</dd> |
|---|
| 459 | <dt>X <nm></dt> |
|---|
| 460 | <dd>Extract nm (will prompt if omitted). Prompts for output filename. If none |
|---|
| 461 | given, extracted to stdout.</dd> |
|---|
| 462 | <dt>Q</dt> |
|---|
| 463 | <dd>Quit.</dd> |
|---|
| 464 | </dl> |
|---|
| 465 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 466 | </div> |
|---|
| 467 | <div class="section"> |
|---|
| 468 | <h2><a class="toc-backref" href="#id15" id="bindepend" name="bindepend">bindepend</a></h2> |
|---|
| 469 | <pre class="literal-block"> |
|---|
| 470 | python bindepend.py <executable_or_dynamic_library> |
|---|
| 471 | </pre> |
|---|
| 472 | <p>bindepend will analyze the executable you pass to it, and write to stdout all |
|---|
| 473 | its binary dependencies. This is handy to find out which DLLs are required by |
|---|
| 474 | an executable or another DLL. This module is used by PyInstaller itself to |
|---|
| 475 | follow the chain of dependencies of binary extensions and make sure that all |
|---|
| 476 | of them get included in the final package.</p> |
|---|
| 477 | </div> |
|---|
| 478 | <div class="section"> |
|---|
| 479 | <h2><a class="toc-backref" href="#id16" id="grabversion-windows" name="grabversion-windows">GrabVersion (Windows)</a></h2> |
|---|
| 480 | <pre class="literal-block"> |
|---|
| 481 | python GrabVersion.py <executable_with_version_resource> |
|---|
| 482 | </pre> |
|---|
| 483 | <p>GrabVersion outputs text which can be eval'ed by <tt class="docutils literal"><span class="pre">versionInfo.py</span></tt> to reproduce |
|---|
| 484 | a version resource. Invoke it with the full path name of a Windows executable |
|---|
| 485 | (with a version resource) as the first argument. If you cut & paste (or |
|---|
| 486 | redirect to a file), you can then edit the version information. The edited |
|---|
| 487 | text file can be used in a <tt class="docutils literal"><span class="pre">version</span> <span class="pre">=</span> <span class="pre">myversion.txt</span></tt> option on any executable |
|---|
| 488 | in an PyInstaller spec file.</p> |
|---|
| 489 | <p>This was done in this way because version resources are rather strange beasts, |
|---|
| 490 | and fully understanding them is probably impossible. Some elements are |
|---|
| 491 | optional, others required, but you could spend unbounded amounts of time |
|---|
| 492 | figuring this out, because it's not well documented. When you view the version |
|---|
| 493 | tab on a properties dialog, there's no straightforward relationship between |
|---|
| 494 | how the data is displayed and the structure of the resource itself. So the |
|---|
| 495 | easiest thing to do is find an executable that displays the kind of |
|---|
| 496 | information you want, grab it's resource and edit it. Certainly easier than |
|---|
| 497 | the Version resource wizard in VC++.</p> |
|---|
| 498 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 499 | </div> |
|---|
| 500 | <div class="section"> |
|---|
| 501 | <h2><a class="toc-backref" href="#id17" id="analyzing-dependencies" name="analyzing-dependencies">Analyzing Dependencies</a></h2> |
|---|
| 502 | <p>You can interactively track down dependencies, including getting |
|---|
| 503 | cross-references by using <tt class="docutils literal"><span class="pre">mf.py</span></tt>, documented in section <a class="reference" href="#mf-py-a-modulefinder-replacement">mf.py: A modulefinder |
|---|
| 504 | Replacement</a></p> |
|---|
| 505 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 506 | </div> |
|---|
| 507 | </div> |
|---|
| 508 | <div class="section"> |
|---|
| 509 | <h1><a class="toc-backref" href="#id18" id="spec-files" name="spec-files">Spec Files</a></h1> |
|---|
| 510 | <div class="section"> |
|---|
| 511 | <h2><a class="toc-backref" href="#id19" id="introduction" name="introduction">Introduction</a></h2> |
|---|
| 512 | <p>Spec files are in Python syntax. They are evaluated by Build.py. A simplistic |
|---|
| 513 | spec file might look like this:</p> |
|---|
| 514 | <pre class="literal-block"> |
|---|
| 515 | a = Analysis(['myscript.py']) |
|---|
| 516 | pyz = PYZ(a.pure) |
|---|
| 517 | exe = EXE(pyz, a.scripts, a.binaries, name="myapp.exe") |
|---|
| 518 | </pre> |
|---|
| 519 | <p>This creates a single file deployment with all binaries (extension modules and |
|---|
| 520 | their dependencies) packed into the executable.</p> |
|---|
| 521 | <p>A simplistic single directory deployment might look like this:</p> |
|---|
| 522 | <pre class="literal-block"> |
|---|
| 523 | a = Analysis(['myscript.py']) |
|---|
| 524 | pyz = PYZ(a.pure) |
|---|
| 525 | exe = EXE(a.scripts, pyz, name="myapp.exe", exclude_binaries=1) |
|---|
| 526 | dist = COLLECT(exe, a.binaries, name="dist") |
|---|
| 527 | </pre> |
|---|
| 528 | <p>Note that neither of these examples are realistic. Use <tt class="docutils literal"><span class="pre">Makespec.py</span></tt> (documented |
|---|
| 529 | in section <a class="reference" href="#create-a-spec-file-for-your-project">Create a spec file for your project</a>) to create your specfile, |
|---|
| 530 | and tweak it (if necessary) from there.</p> |
|---|
| 531 | <p>All of the classes you see above are subclasses of <tt class="docutils literal"><span class="pre">Build.Target</span></tt>. A Target acts |
|---|
| 532 | like a rule in a makefile. It knows enough to cache its last inputs and |
|---|
| 533 | outputs. If its inputs haven't changed, it can assume its outputs wouldn't |
|---|
| 534 | change on recomputation. So a spec file acts much like a makefile, only |
|---|
| 535 | rebuilding as much as needs rebuilding. This means, for example, that if you |
|---|
| 536 | change an <tt class="docutils literal"><span class="pre">EXE</span></tt> from <tt class="docutils literal"><span class="pre">debug=1</span></tt> to <tt class="docutils literal"><span class="pre">debug=0</span></tt>, the rebuild will be nearly |
|---|
| 537 | instantaneous.</p> |
|---|
| 538 | <p>The high level view is that an <tt class="docutils literal"><span class="pre">Analysis</span></tt> takes a list of scripts as input, |
|---|
| 539 | and generates three "outputs", held in attributes named <tt class="docutils literal"><span class="pre">scripts</span></tt>, <tt class="docutils literal"><span class="pre">pure</span></tt> |
|---|
| 540 | and <tt class="docutils literal"><span class="pre">binaries</span></tt>. A <tt class="docutils literal"><span class="pre">PYZ</span></tt> (a <tt class="docutils literal"><span class="pre">.pyz</span></tt> archive) is built from the modules in |
|---|
| 541 | pure. The <tt class="docutils literal"><span class="pre">EXE</span></tt> is built from the <tt class="docutils literal"><span class="pre">PYZ</span></tt>, the scripts and, in the case of a |
|---|
| 542 | single-file deployment, the binaries. In a single-directory deployment, a |
|---|
| 543 | directory is built containing a slim executable and the binaries.</p> |
|---|
| 544 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 545 | </div> |
|---|
| 546 | <div class="section"> |
|---|
| 547 | <h2><a class="toc-backref" href="#id20" id="toc-class-table-of-contents" name="toc-class-table-of-contents">TOC Class (Table of Contents)</a></h2> |
|---|
| 548 | <p>Before you can do much with a spec file, you need to understand the |
|---|
| 549 | <tt class="docutils literal"><span class="pre">TOC</span></tt> (Table Of Contents) class.</p> |
|---|
| 550 | <p>A <tt class="docutils literal"><span class="pre">TOC</span></tt> appears to be a list of tuples of the form (name, path, typecode). |
|---|
| 551 | In fact, it's an ordered set, not a list. A TOC contains no duplicates, where |
|---|
| 552 | uniqueness is based on name only. Furthermore, within this constraint, a TOC |
|---|
| 553 | preserves order.</p> |
|---|
| 554 | <p>Besides the normal list methods and operations, TOC supports taking differences |
|---|
| 555 | and intersections (and note that adding or extending is really equivalent to |
|---|
| 556 | union). Furthermore, the operations can take a real list of tuples on the right |
|---|
| 557 | hand side. This makes excluding modules quite easy. For a pure Python module:</p> |
|---|
| 558 | <pre class="literal-block"> |
|---|
| 559 | pyz = PYZ(a.pure - [('badmodule', '', '')]) |
|---|
| 560 | </pre> |
|---|
| 561 | <p>or for an extension module in a single-directory deployment:</p> |
|---|
| 562 | <pre class="literal-block"> |
|---|
| 563 | dist = COLLECT(..., a.binaries - [('badmodule', '', '')], ...) |
|---|
| 564 | </pre> |
|---|
| 565 | <p>or for a single-file deployment:</p> |
|---|
| 566 | <pre class="literal-block"> |
|---|
| 567 | exe = EXE(..., a.binaries - [('badmodule', '', '')], ...) |
|---|
| 568 | </pre> |
|---|
| 569 | <p>To add files to a TOC, you need to know about the typecodes (or the step using |
|---|
| 570 | the TOC won't know what to do with the entry).</p> |
|---|
| 571 | <table border="1" class="docutils"> |
|---|
| 572 | <colgroup> |
|---|
| 573 | <col width="12%" /> |
|---|
| 574 | <col width="44%" /> |
|---|
| 575 | <col width="19%" /> |
|---|
| 576 | <col width="25%" /> |
|---|
| 577 | </colgroup> |
|---|
| 578 | <thead valign="bottom"> |
|---|
| 579 | <tr><th class="head"><strong>typecode</strong></th> |
|---|
| 580 | <th class="head"><strong>description</strong></th> |
|---|
| 581 | <th class="head"><strong>name</strong></th> |
|---|
| 582 | <th class="head"><strong>path</strong></th> |
|---|
| 583 | </tr> |
|---|
| 584 | </thead> |
|---|
| 585 | <tbody valign="top"> |
|---|
| 586 | <tr><td>'EXTENSION'</td> |
|---|
| 587 | <td>An extension module.</td> |
|---|
| 588 | <td>Python internal name.</td> |
|---|
| 589 | <td>Full path name in build.</td> |
|---|
| 590 | </tr> |
|---|
| 591 | <tr><td>'PYSOURCE'</td> |
|---|
| 592 | <td>A script.</td> |
|---|
| 593 | <td>Python internal name.</td> |
|---|
| 594 | <td>Full path name in build.</td> |
|---|
| 595 | </tr> |
|---|
| 596 | <tr><td>'PYMODULE'</td> |
|---|
| 597 | <td>A pure Python module (including __init__ modules).</td> |
|---|
| 598 | <td>Python internal name.</td> |
|---|
| 599 | <td>Full path name in build.</td> |
|---|
| 600 | </tr> |
|---|
| 601 | <tr><td>'PYZ'</td> |
|---|
| 602 | <td>A .pyz archive (archive_rt.ZlibArchive).</td> |
|---|
| 603 | <td>Runtime name.</td> |
|---|
| 604 | <td>Full path name in build.</td> |
|---|
| 605 | </tr> |
|---|
| 606 | <tr><td>'PKG'</td> |
|---|
| 607 | <td>A pkg archive (carchive4.CArchive).</td> |
|---|
| 608 | <td>Runtime name.</td> |
|---|
| 609 | <td>Full path name in build.</td> |
|---|
| 610 | </tr> |
|---|
| 611 | <tr><td>'BINARY'</td> |
|---|
| 612 | <td>A shared library.</td> |
|---|
| 613 | <td>Runtime name.</td> |
|---|
| 614 | <td>Full path name in build.</td> |
|---|
| 615 | </tr> |
|---|
| 616 | <tr><td>'DATA'</td> |
|---|
| 617 | <td>Aribitrary files.</td> |
|---|
| 618 | <td>Runtime name.</td> |
|---|
| 619 | <td>Full path name in build.</td> |
|---|
| 620 | </tr> |
|---|
| 621 | <tr><td>'OPTION'</td> |
|---|
| 622 | <td>A runtime runtime option (frozen into the executable).</td> |
|---|
| 623 | <td>The option.</td> |
|---|
| 624 | <td>Unused.</td> |
|---|
| 625 | </tr> |
|---|
| 626 | </tbody> |
|---|
| 627 | </table> |
|---|
| 628 | <p>You can force the include of any file in much the same way you do excludes:</p> |
|---|
| 629 | <pre class="literal-block"> |
|---|
| 630 | collect = COLLECT(a.binaries + |
|---|
| 631 | [('readme', '/my/project/readme', 'DATA')], ...) |
|---|
| 632 | </pre> |
|---|
| 633 | <p>or even:</p> |
|---|
| 634 | <pre class="literal-block"> |
|---|
| 635 | collect = COLLECT(a.binaries, |
|---|
| 636 | [('readme', '/my/project/readme', 'DATA')], ...) |
|---|
| 637 | </pre> |
|---|
| 638 | <p>(that is, you can use a list of tuples in place of a <tt class="docutils literal"><span class="pre">TOC</span></tt> in most cases).</p> |
|---|
| 639 | <p>There's not much reason to use this technique for <tt class="docutils literal"><span class="pre">PYSOURCE</span></tt>, since an <tt class="docutils literal"><span class="pre">Analysis</span></tt> |
|---|
| 640 | takes a list of scripts as input. For <tt class="docutils literal"><span class="pre">PYMODULEs</span></tt> and <tt class="docutils literal"><span class="pre">EXTENSIONs</span></tt>, the hook |
|---|
| 641 | mechanism discussed here is better because you won't have to remember how you |
|---|
| 642 | got it working next time.</p> |
|---|
| 643 | <p>This technique is most useful for data files (see the <tt class="docutils literal"><span class="pre">Tree</span></tt> class below for a |
|---|
| 644 | way to build a <tt class="docutils literal"><span class="pre">TOC</span></tt> from a directory tree), and for runtime options. The options |
|---|
| 645 | the run executables understand are:</p> |
|---|
| 646 | <table border="1" class="docutils"> |
|---|
| 647 | <colgroup> |
|---|
| 648 | <col width="9%" /> |
|---|
| 649 | <col width="13%" /> |
|---|
| 650 | <col width="18%" /> |
|---|
| 651 | <col width="60%" /> |
|---|
| 652 | </colgroup> |
|---|
| 653 | <thead valign="bottom"> |
|---|
| 654 | <tr><th class="head"><strong>Option</strong></th> |
|---|
| 655 | <th class="head"><strong>Description</strong></th> |
|---|
| 656 | <th class="head"><strong>Example</strong></th> |
|---|
| 657 | <th class="head"><strong>Notes</strong></th> |
|---|
| 658 | </tr> |
|---|
| 659 | </thead> |
|---|
| 660 | <tbody valign="top"> |
|---|
| 661 | <tr><td>v</td> |
|---|
| 662 | <td>Verbose imports</td> |
|---|
| 663 | <td>('v', '', 'OPTION')</td> |
|---|
| 664 | <td>Same as Python -v ...</td> |
|---|
| 665 | </tr> |
|---|
| 666 | <tr><td>u</td> |
|---|
| 667 | <td>Unbuffered stdio</td> |
|---|
| 668 | <td>('u', '', 'OPTION')</td> |
|---|
| 669 | <td>Same as Python -u ...</td> |
|---|
| 670 | </tr> |
|---|
| 671 | <tr><td>W spec</td> |
|---|
| 672 | <td>Warning option</td> |
|---|
| 673 | <td>('W ignore', '', 'OPTION')</td> |
|---|
| 674 | <td>Python 2.1+ only.</td> |
|---|
| 675 | </tr> |
|---|
| 676 | <tr><td>s</td> |
|---|
| 677 | <td>Use site.py</td> |
|---|
| 678 | <td>('s', '', 'OPTION')</td> |
|---|
| 679 | <td>The opposite of Python's -S flag. Note that site.py must be in the executable's directory to be used.</td> |
|---|
| 680 | </tr> |
|---|
| 681 | <tr><td>f</td> |
|---|
| 682 | <td>Force execvp</td> |
|---|
| 683 | <td>('f', '', 'OPTION')</td> |
|---|
| 684 | <td>Linux/unix only. Ensures that LD_LIBRARY_PATH is set properly.</td> |
|---|
| 685 | </tr> |
|---|
| 686 | </tbody> |
|---|
| 687 | </table> |
|---|
| 688 | <p>Advanced users should note that by using set differences and intersections, it |
|---|
| 689 | becomes possible to factor out common modules, and deploy a project containing |
|---|
| 690 | multiple executables with minimal redundancy. You'll need some top level code |
|---|
| 691 | in each executable to mount the common <tt class="docutils literal"><span class="pre">PYZ</span></tt>.</p> |
|---|
| 692 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 693 | </div> |
|---|
| 694 | <div class="section"> |
|---|
| 695 | <h2><a class="toc-backref" href="#id21" id="target-subclasses" name="target-subclasses">Target Subclasses</a></h2> |
|---|
| 696 | <div class="section"> |
|---|
| 697 | <h3><a class="toc-backref" href="#id22" id="analysis" name="analysis">Analysis</a></h3> |
|---|
| 698 | <pre class="literal-block"> |
|---|
| 699 | Analysis(scripts, pathex=None, hookspath=None, excludes=None) |
|---|
| 700 | </pre> |
|---|
| 701 | <dl class="docutils"> |
|---|
| 702 | <dt><tt class="docutils literal"><span class="pre">scripts</span></tt></dt> |
|---|
| 703 | <dd>a list of scripts specified as file names.</dd> |
|---|
| 704 | <dt><tt class="docutils literal"><span class="pre">pathex</span></tt></dt> |
|---|
| 705 | <dd>an optional list of paths to be searched before sys.path.</dd> |
|---|
| 706 | <dt><tt class="docutils literal"><span class="pre">hookspath</span></tt></dt> |
|---|
| 707 | <dd>an optional list of paths used to extend the hooks package.</dd> |
|---|
| 708 | <dt><tt class="docutils literal"><span class="pre">excludes</span></tt></dt> |
|---|
| 709 | <dd>an optional list of module or package names (their Python names, not path |
|---|
| 710 | names) that will be ignored (as though they were not found).</dd> |
|---|
| 711 | </dl> |
|---|
| 712 | <p>An Analysis has three outputs, all <tt class="docutils literal"><span class="pre">TOCs</span></tt> accessed as attributes of the <tt class="docutils literal"><span class="pre">Analysis</span></tt>.</p> |
|---|
| 713 | <dl class="docutils"> |
|---|
| 714 | <dt><tt class="docutils literal"><span class="pre">scripts</span></tt></dt> |
|---|
| 715 | <dd>The scripts you gave Analysis as input, with any runtime hook scripts |
|---|
| 716 | prepended.</dd> |
|---|
| 717 | <dt><tt class="docutils literal"><span class="pre">pure</span></tt></dt> |
|---|
| 718 | <dd>The pure Python modules.</dd> |
|---|
| 719 | <dt><tt class="docutils literal"><span class="pre">binaries</span></tt></dt> |
|---|
| 720 | <dd>The extension modules and their dependencies. The secondary dependencies are |
|---|
| 721 | filtered. On Windows, a long list of MS dlls are excluded. On Linux/Unix, |
|---|
| 722 | any shared lib in <tt class="docutils literal"><span class="pre">/lib</span></tt> or <tt class="docutils literal"><span class="pre">/usr/lib</span></tt> is excluded.</dd> |
|---|
| 723 | </dl> |
|---|
| 724 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 725 | </div> |
|---|
| 726 | <div class="section"> |
|---|
| 727 | <h3><a class="toc-backref" href="#id23" id="pyz" name="pyz">PYZ</a></h3> |
|---|
| 728 | <pre class="literal-block"> |
|---|
| 729 | PYZ(toc, name=None, level=9) |
|---|
| 730 | </pre> |
|---|
| 731 | <dl class="docutils"> |
|---|
| 732 | <dt><tt class="docutils literal"><span class="pre">toc</span></tt></dt> |
|---|
| 733 | <dd>a <tt class="docutils literal"><span class="pre">TOC</span></tt>, normally an <tt class="docutils literal"><span class="pre">Analysis.pure</span></tt>.</dd> |
|---|
| 734 | <dt><tt class="docutils literal"><span class="pre">name</span></tt></dt> |
|---|
| 735 | <dd>A filename for the <tt class="docutils literal"><span class="pre">.pyz</span></tt>. Normally not needed, as the generated name will do fine.</dd> |
|---|
| 736 | <dt><tt class="docutils literal"><span class="pre">level</span></tt></dt> |
|---|
| 737 | <dd>The Zlib compression level to use. If 0, the zlib module is not required.</dd> |
|---|
| 738 | </dl> |
|---|
| 739 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 740 | </div> |
|---|
| 741 | <div class="section"> |
|---|
| 742 | <h3><a class="toc-backref" href="#id24" id="pkg" name="pkg">PKG</a></h3> |
|---|
| 743 | <p>Generally, you will not need to create your own <tt class="docutils literal"><span class="pre">PKGs</span></tt>, as the <tt class="docutils literal"><span class="pre">EXE</span></tt> will do it for |
|---|
| 744 | you. This is one way to include read-only data in a single-file deployment, |
|---|
| 745 | however. A single-file deployment including TK support will use this technique.</p> |
|---|
| 746 | <pre class="literal-block"> |
|---|
| 747 | PKG(toc, name=None, cdict=None, exclude_binaries=0) |
|---|
| 748 | </pre> |
|---|
| 749 | <dl class="docutils"> |
|---|
| 750 | <dt><tt class="docutils literal"><span class="pre">toc</span></tt></dt> |
|---|
| 751 | <dd>a <tt class="docutils literal"><span class="pre">TOC</span></tt>.</dd> |
|---|
| 752 | <dt><tt class="docutils literal"><span class="pre">name</span></tt></dt> |
|---|
| 753 | <dd>a filename for the <tt class="docutils literal"><span class="pre">PKG</span></tt> (optional).</dd> |
|---|
| 754 | <dt><tt class="docutils literal"><span class="pre">cdict</span></tt></dt> |
|---|
| 755 | <dd>a dictionary that specifies compression by typecode. For example, <tt class="docutils literal"><span class="pre">PYZ</span></tt> is |
|---|
| 756 | left uncompressed so that it can be accessed inside the <tt class="docutils literal"><span class="pre">PKG</span></tt>. The default |
|---|
| 757 | uses sensible values. If zlib is not available, no compression is used.</dd> |
|---|
| 758 | <dt><tt class="docutils literal"><span class="pre">exclude_binaries</span></tt></dt> |
|---|
| 759 | <dd>If 1, <tt class="docutils literal"><span class="pre">EXTENSIONs</span></tt> and <tt class="docutils literal"><span class="pre">BINARYs</span></tt> will be left out of the <tt class="docutils literal"><span class="pre">PKG</span></tt>, and |
|---|
| 760 | forwarded to its container (usually a <tt class="docutils literal"><span class="pre">COLLECT</span></tt>).</dd> |
|---|
| 761 | </dl> |
|---|
| 762 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 763 | </div> |
|---|
| 764 | <div class="section"> |
|---|
| 765 | <h3><a class="toc-backref" href="#id25" id="exe" name="exe">EXE</a></h3> |
|---|
| 766 | <pre class="literal-block"> |
|---|
| 767 | EXE(*args, **kws) |
|---|
| 768 | </pre> |
|---|
| 769 | <dl class="docutils"> |
|---|
| 770 | <dt><tt class="docutils literal"><span class="pre">args</span></tt></dt> |
|---|
| 771 | <dd>One or more arguments which are either <tt class="docutils literal"><span class="pre">TOCs</span></tt> or <tt class="docutils literal"><span class="pre">Targets</span></tt>.</dd> |
|---|
| 772 | <dt><tt class="docutils literal"><span class="pre">kws</span></tt></dt> |
|---|
| 773 | <dd><p class="first">Possible keyword arguments:</p> |
|---|
| 774 | <dl class="last docutils"> |
|---|
| 775 | <dt><tt class="docutils literal"><span class="pre">console</span></tt></dt> |
|---|
| 776 | <dd>Always 1 on Linux/unix. On Windows, governs whether to use the console |
|---|
| 777 | executable, or the Windows subsystem executable.</dd> |
|---|
| 778 | <dt><tt class="docutils literal"><span class="pre">debug</span></tt></dt> |
|---|
| 779 | <dd>Setting to 1 gives you progress messages from the executable (for a |
|---|
| 780 | <tt class="docutils literal"><span class="pre">console=0</span></tt>, these will be annoying MessageBoxes).</dd> |
|---|
| 781 | <dt><tt class="docutils literal"><span class="pre">name</span></tt></dt> |
|---|
| 782 | <dd>The filename for the executable.</dd> |
|---|
| 783 | <dt><tt class="docutils literal"><span class="pre">exclude_binaries</span></tt></dt> |
|---|
| 784 | <dd>Forwarded to the <tt class="docutils literal"><span class="pre">PKG</span></tt> the <tt class="docutils literal"><span class="pre">EXE</span></tt> builds.</dd> |
|---|
| 785 | <dt><tt class="docutils literal"><span class="pre">icon</span></tt></dt> |
|---|
| 786 | <dd>Windows NT family only. <tt class="docutils literal"><span class="pre">icon='myicon.ico'</span></tt> to use an icon file, or |
|---|
| 787 | <tt class="docutils literal"><span class="pre">icon='notepad.exe,0'</span></tt> to grab an icon resource.</dd> |
|---|
| 788 | <dt><tt class="docutils literal"><span class="pre">version</span></tt></dt> |
|---|
| 789 | <dd>Windows NT family only. <tt class="docutils literal"><span class="pre">version='myversion.txt'</span></tt>. Use <tt class="docutils literal"><span class="pre">GrabVersion.py</span></tt> to |
|---|
| 790 | steal a version resource from an executable, and then edit the ouput to |
|---|
| 791 | create your own. (The syntax of version resources is so arcane that I |
|---|
| 792 | wouldn't attempt to write one from scratch.)</dd> |
|---|
| 793 | </dl> |
|---|
| 794 | </dd> |
|---|
| 795 | </dl> |
|---|
| 796 | <p>There are actually two <tt class="docutils literal"><span class="pre">EXE</span></tt> classes - one for ELF platforms (where the |
|---|
| 797 | bootloader, that is the <tt class="docutils literal"><span class="pre">run</span></tt> executable, and the <tt class="docutils literal"><span class="pre">PKG</span></tt> are concatenated), |
|---|
| 798 | and one for non-ELF platforms (where the run executable is simply renamed, and |
|---|
| 799 | expects a <tt class="docutils literal"><span class="pre">exename.pkg</span></tt> in the same directory). Which class becomes available |
|---|
| 800 | as <tt class="docutils literal"><span class="pre">EXE</span></tt> is determined by a flag in <tt class="docutils literal"><span class="pre">config.dat</span></tt>. This flag is set to |
|---|
| 801 | non-ELF when using <tt class="docutils literal"><span class="pre">Make.py</span> <span class="pre">-n</span></tt>.</p> |
|---|
| 802 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 803 | </div> |
|---|
| 804 | <div class="section"> |
|---|
| 805 | <h3><a class="toc-backref" href="#id26" id="dll" name="dll">DLL</a></h3> |
|---|
| 806 | <p>On Windows, this provides support for doing in-process COM servers. It is not |
|---|
| 807 | generalized. However, embedders can follow the same model to build a special |
|---|
| 808 | purpose DLL so the Python support in their app is hidden. You will need to |
|---|
| 809 | write your own dll, but thanks to Allan Green for refactoring the C code and |
|---|
| 810 | making that a managable task.</p> |
|---|
| 811 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 812 | </div> |
|---|
| 813 | <div class="section"> |
|---|
| 814 | <h3><a class="toc-backref" href="#id27" id="collect" name="collect">COLLECT</a></h3> |
|---|
| 815 | <pre class="literal-block"> |
|---|
| 816 | COLLECT(*args, **kws) |
|---|
| 817 | </pre> |
|---|
| 818 | <dl class="docutils"> |
|---|
| 819 | <dt><tt class="docutils literal"><span class="pre">args</span></tt></dt> |
|---|
| 820 | <dd>One or more arguments which are either <tt class="docutils literal"><span class="pre">TOCs</span></tt> or <tt class="docutils literal"><span class="pre">Targets</span></tt>.</dd> |
|---|
| 821 | <dt><tt class="docutils literal"><span class="pre">kws</span></tt></dt> |
|---|
| 822 | <dd><p class="first">Possible keyword arguments:</p> |
|---|
| 823 | <dl class="last docutils"> |
|---|
| 824 | <dt><tt class="docutils literal"><span class="pre">name</span></tt></dt> |
|---|
| 825 | <dd>The name of the directory to be built.</dd> |
|---|
| 826 | </dl> |
|---|
| 827 | </dd> |
|---|
| 828 | </dl> |
|---|
| 829 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 830 | </div> |
|---|
| 831 | <div class="section"> |
|---|
| 832 | <h3><a class="toc-backref" href="#id28" id="tree" name="tree">Tree</a></h3> |
|---|
| 833 | <pre class="literal-block"> |
|---|
| 834 | Tree(root, prefix=None, excludes=None) |
|---|
| 835 | </pre> |
|---|
| 836 | <dl class="docutils"> |
|---|
| 837 | <dt><tt class="docutils literal"><span class="pre">root</span></tt></dt> |
|---|
| 838 | <dd>The root of the tree (on the build system).</dd> |
|---|
| 839 | <dt><tt class="docutils literal"><span class="pre">prefix</span></tt></dt> |
|---|
| 840 | <dd>Optional prefix to the names on the target system.</dd> |
|---|
| 841 | <dt><tt class="docutils literal"><span class="pre">excludes</span></tt></dt> |
|---|
| 842 | <dd><p class="first">A list of names to exclude. Two forms are allowed:</p> |
|---|
| 843 | <dl class="last docutils"> |
|---|
| 844 | <dt><tt class="docutils literal"><span class="pre">name</span></tt></dt> |
|---|
| 845 | <dd>files with this basename will be excluded (do not include the path).</dd> |
|---|
| 846 | <dt><tt class="docutils literal"><span class="pre">*.ext</span></tt></dt> |
|---|
| 847 | <dd>any file with the given extension will be excluded.</dd> |
|---|
| 848 | </dl> |
|---|
| 849 | </dd> |
|---|
| 850 | </dl> |
|---|
| 851 | <p>Since a <tt class="docutils literal"><span class="pre">Tree</span></tt> is a <tt class="docutils literal"><span class="pre">TOC</span></tt>, you can also use the exclude technique described above |
|---|
| 852 | in the section on <tt class="docutils literal"><span class="pre">TOCs</span></tt>.</p> |
|---|
| 853 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 854 | </div> |
|---|
| 855 | </div> |
|---|
| 856 | </div> |
|---|
| 857 | <div class="section"> |
|---|
| 858 | <h1><a class="toc-backref" href="#id29" id="when-things-go-wrong" name="when-things-go-wrong">When Things Go Wrong</a></h1> |
|---|
| 859 | <div class="section"> |
|---|
| 860 | <h2><a class="toc-backref" href="#id30" id="finding-out-what-went-wrong" name="finding-out-what-went-wrong">Finding out What Went Wrong</a></h2> |
|---|
| 861 | <div class="section"> |
|---|
| 862 | <h3><a class="toc-backref" href="#id31" id="buildtime-warnings" name="buildtime-warnings">Buildtime Warnings</a></h3> |
|---|
| 863 | <p>When an <tt class="docutils literal"><span class="pre">Analysis</span></tt> step runs, it produces a warnings file (named <tt class="docutils literal"><span class="pre">warnproject.txt</span></tt>) |
|---|
| 864 | in the spec file's directory. Generally, most of these warnings are harmless. |
|---|
| 865 | For example, <tt class="docutils literal"><span class="pre">os.py</span></tt> (which is cross-platform) works by figuring out what |
|---|
| 866 | platform it is on, then importing (and rebinding names from) the appropriate |
|---|
| 867 | platform-specific module. So analyzing <tt class="docutils literal"><span class="pre">os.py</span></tt> will produce a set of warnings |
|---|
| 868 | like:</p> |
|---|
| 869 | <pre class="literal-block"> |
|---|
| 870 | W: no module named dos (conditional import by os) |
|---|
| 871 | W: no module named ce (conditional import by os) |
|---|
| 872 | W: no module named os2 (conditional import by os) |
|---|
| 873 | </pre> |
|---|
| 874 | <p>Note that the analysis has detected that the import is within a conditional |
|---|
| 875 | block (an if statement). The analysis also detects if an import within a |
|---|
| 876 | function or class, (delayed) or at the top level. A top-level, non-conditional |
|---|
| 877 | import failure is really a hard error. There's at least a reasonable chance |
|---|
| 878 | that conditional and / or delayed import will be handled gracefully at runtime.</p> |
|---|
| 879 | <p>Ignorable warnings may also be produced when a class or function is declared in |
|---|
| 880 | a package (an <tt class="docutils literal"><span class="pre">__init__.py</span></tt> module), and the import specifies |
|---|
| 881 | <tt class="docutils literal"><span class="pre">package.name</span></tt>. In this case, the analysis can't tell if name is supposed to |
|---|
| 882 | refer to a submodule of package.</p> |
|---|
| 883 | <p>Warnings are also produced when an <tt class="docutils literal"><span class="pre">__import__</span></tt>, <tt class="docutils literal"><span class="pre">exec</span></tt> or <tt class="docutils literal"><span class="pre">eval</span></tt> statement is |
|---|
| 884 | encountered. The <tt class="docutils literal"><span class="pre">__import__</span></tt> warnings should almost certainly be investigated. |
|---|
| 885 | Both <tt class="docutils literal"><span class="pre">exec</span></tt> and <tt class="docutils literal"><span class="pre">eval</span></tt> can be used to implement import hacks, but usually their use |
|---|
| 886 | is more benign.</p> |
|---|
| 887 | <p>Any problem detected here can be handled by hooking the analysis of the module. |
|---|
| 888 | See <a class="reference" href="#listing-hidden-imports">Listing Hidden Imports</a> below for how to do it.</p> |
|---|
| 889 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 890 | </div> |
|---|
| 891 | <div class="section"> |
|---|
| 892 | <h3><a class="toc-backref" href="#id32" id="getting-debug-messages" name="getting-debug-messages">Getting Debug Messages</a></h3> |
|---|
| 893 | <p>Setting <tt class="docutils literal"><span class="pre">debug=1</span></tt> on an <tt class="docutils literal"><span class="pre">EXE</span></tt> will cause the executable to put out progress |
|---|
| 894 | messages (for console apps, these go to stdout; for Windows apps, these show as |
|---|
| 895 | MessageBoxes). This can be useful if you are doing complex packaging, or your |
|---|
| 896 | app doesn't seem to be starting, or just to learn how the runtime works.</p> |
|---|
| 897 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 898 | </div> |
|---|
| 899 | <div class="section"> |
|---|
| 900 | <h3><a class="toc-backref" href="#id33" id="getting-python-s-verbose-imports" name="getting-python-s-verbose-imports">Getting Python's Verbose Imports</a></h3> |
|---|
| 901 | <p>You can also pass a <tt class="docutils literal"><span class="pre">-v</span></tt> (verbose imports) flag to the embedded Python. This can |
|---|
| 902 | be extremely useful. I usually try it even on apparently working apps, just to |
|---|
| 903 | make sure that I'm always getting my copies of the modules and no import has |
|---|
| 904 | leaked out to the installed Python.</p> |
|---|
| 905 | <p>You set this (like the other runtime options) by feeding a phone <tt class="docutils literal"><span class="pre">TOC</span></tt> entry to |
|---|
| 906 | the <tt class="docutils literal"><span class="pre">EXE</span></tt>. The easiest way to do this is to change the <tt class="docutils literal"><span class="pre">EXE</span></tt> from:</p> |
|---|
| 907 | <pre class="literal-block"> |
|---|
| 908 | EXE(..., anal.scripts, ....) |
|---|
| 909 | </pre> |
|---|
| 910 | <p>to:</p> |
|---|
| 911 | <pre class="literal-block"> |
|---|
| 912 | EXE(..., anal.scripts + [('v', '', 'OPTION')], ...) |
|---|
| 913 | </pre> |
|---|
| 914 | <p>These messages will always go to <tt class="docutils literal"><span class="pre">stdout</span></tt>, so you won't see them on Windows if |
|---|
| 915 | <tt class="docutils literal"><span class="pre">console=0</span></tt>.</p> |
|---|
| 916 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 917 | </div> |
|---|
| 918 | </div> |
|---|
| 919 | <div class="section"> |
|---|
| 920 | <h2><a class="toc-backref" href="#id34" id="helping-installer-find-modules" name="helping-installer-find-modules">Helping Installer Find Modules</a></h2> |
|---|
| 921 | <div class="section"> |
|---|
| 922 | <h3><a class="toc-backref" href="#id35" id="extending-the-path" name="extending-the-path">Extending the Path</a></h3> |
|---|
| 923 | <p>When the analysis phase cannot find needed modules, it may be that the code is |
|---|
| 924 | manipulating <tt class="docutils literal"><span class="pre">sys.path</span></tt>. The easiest thing to do in this case is tell <tt class="docutils literal"><span class="pre">Analysis</span></tt> |
|---|
| 925 | about the new directory through the second arg to the constructor:</p> |
|---|
| 926 | <pre class="literal-block"> |
|---|
| 927 | anal = Analysis(['somedir/myscript.py'], |
|---|
| 928 | ['path/to/thisdir', 'path/to/thatdir']) |
|---|
| 929 | </pre> |
|---|
| 930 | <p>In this case, the <tt class="docutils literal"><span class="pre">Analysis</span></tt> will have a search path:</p> |
|---|
| 931 | <pre class="literal-block"> |
|---|
| 932 | ['somedir', 'path/to/thisdir', 'path/to/thatdir'] + sys.path |
|---|
| 933 | </pre> |
|---|
| 934 | <p>You can do the same when running <tt class="docutils literal"><span class="pre">Makespec.py</span></tt>:</p> |
|---|
| 935 | <pre class="literal-block"> |
|---|
| 936 | Makespec.py --paths=path/to/thisdir;path/to/thatdir ... |
|---|
| 937 | </pre> |
|---|
| 938 | <p>(on *nix, use <tt class="docutils literal"><span class="pre">:</span></tt> as the path separator).</p> |
|---|
| 939 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 940 | </div> |
|---|
| 941 | <div class="section"> |
|---|
| 942 | <h3><a class="toc-backref" href="#id36" id="listing-hidden-imports" name="listing-hidden-imports">Listing Hidden Imports</a></h3> |
|---|
| 943 | <p>Hidden imports are fairly common. These can occur when the code is using |
|---|
| 944 | <tt class="docutils literal"><span class="pre">__import__</span></tt> (or, perhaps <tt class="docutils literal"><span class="pre">exec</span></tt> or <tt class="docutils literal"><span class="pre">eval</span></tt>), in which case you will see a warning in |
|---|
| 945 | the <tt class="docutils literal"><span class="pre">warnproject.txt</span></tt> file. They can also occur when an extension module uses the |
|---|
| 946 | Python/C API to do an import, in which case Analysis can't detect anything. You |
|---|
| 947 | can verify that hidden import is the problem by using Python's verbose imports |
|---|
| 948 | flag. If the import messages say "module not found", but the <tt class="docutils literal"><span class="pre">warnproject.txt</span></tt> |
|---|
| 949 | file has no "no module named..." message for the same module, then the problem |
|---|
| 950 | is a hidden import.</p> |
|---|
| 951 | <div class="sidebar"> |
|---|
| 952 | <p class="first sidebar-title">Standard hidden imports are already included!</p> |
|---|
| 953 | <p class="last">If you are getting worried while reading this paragraph, do not worry: |
|---|
| 954 | having hidden imports is the exception, not the norm! And anyway, |
|---|
| 955 | PyInstaller already ships with a large set of hooks that take care of |
|---|
| 956 | hidden imports for the most common packages out there. For instance, |
|---|
| 957 | <a class="reference" href="http://www.pythonware.com/products/pil/">PIL</a>, <a class="reference" href="http://starship.python.net/crew/mhammond/win32/">PyWin32</a>, <a class="reference" href="http://www.riverbankcomputing.co.uk/pyqt/index.php">PyQt</a> are already taken care of.</p> |
|---|
| 958 | </div> |
|---|
| 959 | <p>Hidden imports are handled by hooking the module (the one doing the hidden |
|---|
| 960 | imports) at <tt class="docutils literal"><span class="pre">Analysis</span></tt> time. Do this by creating a file named <tt class="docutils literal"><span class="pre">hook-module.py</span></tt> |
|---|
| 961 | (where module is the fully-qualified Python name, eg, <tt class="docutils literal"><span class="pre">hook-xml.dom.py</span></tt>), and |
|---|
| 962 | placing it in the <tt class="docutils literal"><span class="pre">hooks</span></tt> package under PyInstaller's root directory, |
|---|
| 963 | (alternatively, you can save it elsewhere, and then use the <tt class="docutils literal"><span class="pre">hookspath</span></tt> arg to |
|---|
| 964 | <tt class="docutils literal"><span class="pre">Analysis</span></tt> so your private hooks directory will be searched). Normally, it will |
|---|
| 965 | have only one line:</p> |
|---|
| 966 | <pre class="literal-block"> |
|---|
| 967 | hiddenimports = ['module1', 'module2'] |
|---|
| 968 | </pre> |
|---|
| 969 | <p>When the <tt class="docutils literal"><span class="pre">Analysis</span></tt> finds this file, it will proceed exactly as though the module |
|---|
| 970 | explicitly imported <tt class="docutils literal"><span class="pre">module1</span></tt> and <tt class="docutils literal"><span class="pre">module2</span></tt>. (Full details on the analysis-time |
|---|
| 971 | hook mechanism is in the <a class="reference" href="#hooks">Hooks</a> section).</p> |
|---|
| 972 | <p>If you successfully hook a publicly distributed module in this way, please send |
|---|
| 973 | us the hook so we can make it available to others.</p> |
|---|
| 974 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 975 | </div> |
|---|
| 976 | <div class="section"> |
|---|
| 977 | <h3><a class="toc-backref" href="#id37" id="extending-a-package-s-path" name="extending-a-package-s-path">Extending a Package's <tt class="docutils literal docutils literal"><span class="pre">__path__</span></tt></a></h3> |
|---|
| 978 | <p>Python allows a package to extend the search path used to find modules and |
|---|
| 979 | sub-packages through the <tt class="docutils literal"><span class="pre">__path__</span></tt> mechanism. Normally, a package's <tt class="docutils literal"><span class="pre">__path__</span></tt> has |
|---|
| 980 | only one entry - the directory in which the <tt class="docutils literal"><span class="pre">__init__.py</span></tt> was found. But |
|---|
| 981 | <tt class="docutils literal"><span class="pre">__init__.py</span></tt> is free to extend its <tt class="docutils literal"><span class="pre">__path__</span></tt> to include other directories. For |
|---|
| 982 | example, the <tt class="docutils literal"><span class="pre">win32com.shell.shell</span></tt> module actually resolves to |
|---|
| 983 | <tt class="docutils literal"><span class="pre">win32com/win32comext/shell/shell.pyd</span></tt>. This is because <tt class="docutils literal"><span class="pre">win32com/__init__.py</span></tt> |
|---|
| 984 | appends <tt class="docutils literal"><span class="pre">../win32comext</span></tt> to its <tt class="docutils literal"><span class="pre">__path__</span></tt>.</p> |
|---|
| 985 | <p>Because the <tt class="docutils literal"><span class="pre">__init__.py</span></tt> is not actually run during an analysis, we use the same |
|---|
| 986 | hook mechanism we use for hidden imports. A static list of names won't do, |
|---|
| 987 | however, because the new entry on <tt class="docutils literal"><span class="pre">__path__</span></tt> may well require computation. So |
|---|
| 988 | <tt class="docutils literal"><span class="pre">hook-module.py</span></tt> should define a method <tt class="docutils literal"><span class="pre">hook(mod)</span></tt>. The mod argument is an |
|---|
| 989 | instance of <tt class="docutils literal"><span class="pre">mf.Module</span></tt> which has (more or less) the same attributes as a real |
|---|
| 990 | module object. The hook function should return a <tt class="docutils literal"><span class="pre">mf.Module</span></tt> instance - perhaps |
|---|
| 991 | a brand new one, but more likely the same one used as an arg, but mutated. |
|---|
| 992 | See <a class="reference" href="#mf-py-a-modulefinder-replacement">mf.py: A Modulefinder Replacement</a> for details, and <a class="reference" href="http://pyinstaller.hpcf.upr.edu/pyinstaller/browser/trunk/hooks/hook-win32com.py?rev=latest">hooks/hook-win32com.py</a> |
|---|
| 993 | for an example.</p> |
|---|
| 994 | <p>Note that manipulations of <tt class="docutils literal"><span class="pre">__path__</span></tt> hooked in this way apply to the analysis, |
|---|
| 995 | and only the analysis. That is, at runtime <tt class="docutils literal"><span class="pre">win32com.shell</span></tt> is resolved the same |
|---|
| 996 | way as <tt class="docutils literal"><span class="pre">win32com.anythingelse</span></tt>, and <tt class="docutils literal"><span class="pre">win32com.__path__</span></tt> knows nothing of <tt class="docutils literal"><span class="pre">../win32comext</span></tt>.</p> |
|---|
| 997 | <p>Once in awhile, that's not enough.</p> |
|---|
| 998 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 999 | </div> |
|---|
| 1000 | <div class="section"> |
|---|
| 1001 | <h3><a class="toc-backref" href="#id38" id="changing-runtime-behavior" name="changing-runtime-behavior">Changing Runtime Behavior</a></h3> |
|---|
| 1002 | <p>More bizarre situations can be accomodated with runtime hooks. These are small |
|---|
| 1003 | scripts that manipulate the environment before your main script runs, |
|---|
| 1004 | effectively providing additional top-level code to your script.</p> |
|---|
| 1005 | <p>At the tail end of an analysis, the module list is examined for matches in |
|---|
| 1006 | <tt class="docutils literal"><span class="pre">rthooks.dat</span></tt>, which is the string representation of a Python dictionary. The |
|---|
| 1007 | key is the module name, and the value is a list of hook-script pathnames.</p> |
|---|
| 1008 | <p>So putting an entry:</p> |
|---|
| 1009 | <pre class="literal-block"> |
|---|
| 1010 | 'somemodule': ['path/to/somescript.py'], |
|---|
| 1011 | </pre> |
|---|
| 1012 | <p>into <tt class="docutils literal"><span class="pre">rthooks.dat</span></tt> is almost the same thing as doing this:</p> |
|---|
| 1013 | <pre class="literal-block"> |
|---|
| 1014 | anal = Analysis(['path/to/somescript.py', 'main.py'], ... |
|---|
| 1015 | </pre> |
|---|
| 1016 | <p>except that in using the hook, <tt class="docutils literal"><span class="pre">path/to/somescript.py</span></tt> will not be analyzed, |
|---|
| 1017 | (that's not a feature - we just haven't found a sane way fit the recursion into |
|---|
| 1018 | my persistence scheme).</p> |
|---|
| 1019 | <p>Hooks done in this way, while they need to be careful of what they import, are |
|---|
| 1020 | free to do almost anything. One provided hook sets things up so that win32com |
|---|
| 1021 | can generate modules at runtime (to disk), and the generated modules can be |
|---|
| 1022 | found in the win32com package.</p> |
|---|
| 1023 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1024 | </div> |
|---|
| 1025 | <div class="section"> |
|---|
| 1026 | <h3><a class="toc-backref" href="#id39" id="adapting-to-being-frozen" name="adapting-to-being-frozen">Adapting to being "frozen"</a></h3> |
|---|
| 1027 | <p>In most sophisticated apps, it becomes necessary to figure out (at runtime) |
|---|
| 1028 | whether you're running "live" or "frozen". For example, you might have a |
|---|
| 1029 | configuration file that (running "live") you locate based on a module's |
|---|
| 1030 | <tt class="docutils literal"><span class="pre">__file__</span></tt> attribute. That won't work once the code is packaged up. You'll |
|---|
| 1031 | probably want to look for it based on <tt class="docutils literal"><span class="pre">sys.executable</span></tt> instead.</p> |
|---|
| 1032 | <p>The bootloaders set <tt class="docutils literal"><span class="pre">sys.frozen=1</span></tt> (and, for in-process COM servers, the |
|---|
| 1033 | embedding DLL sets <tt class="docutils literal"><span class="pre">sys.frozen='dll'</span></tt>).</p> |
|---|
| 1034 | <p>For really advanced users, you can access the <tt class="docutils literal"><span class="pre">iu.ImportManager</span></tt> as |
|---|
| 1035 | <tt class="docutils literal"><span class="pre">sys.importManager</span></tt>. See <a class="reference" href="#iu-py">iu.py</a> for how you might make use of this fact.</p> |
|---|
| 1036 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1037 | </div> |
|---|
| 1038 | <div class="section"> |
|---|
| 1039 | <h3><a class="toc-backref" href="#id40" id="accessing-data-files" name="accessing-data-files">Accessing Data Files</a></h3> |
|---|
| 1040 | <p>In a <tt class="docutils literal"><span class="pre">--onedir</span></tt> distribution, this is easy: pass a list of your data files |
|---|
| 1041 | (in <tt class="docutils literal"><span class="pre">TOC</span></tt> format) to the <tt class="docutils literal"><span class="pre">COLLECT</span></tt>, and they will show up in the distribution |
|---|
| 1042 | directory tree. The name in the <tt class="docutils literal"><span class="pre">(name,</span> <span class="pre">path,</span> <span class="pre">'DATA')</span></tt> tuple can be a relative |
|---|
| 1043 | path name. Then, at runtime, you can use code like this to find the file:</p> |
|---|
| 1044 | <pre class="literal-block"> |
|---|
| 1045 | os.path.join(os.path.dirname(sys.executable), relativename)) |
|---|
| 1046 | </pre> |
|---|
| 1047 | <p>In a <tt class="docutils literal"><span class="pre">--onefile</span></tt>, it's a bit trickier. You can cheat, and add the files to the |
|---|
| 1048 | <tt class="docutils literal"><span class="pre">EXE</span></tt> as <tt class="docutils literal"><span class="pre">BINARY</span></tt>. They will then be extracted at runtime into the work directory |
|---|
| 1049 | by the C code (which does not create directories, so the name must be a plain |
|---|
| 1050 | name), and cleaned up on exit. The work directory is best found by |
|---|
| 1051 | <tt class="docutils literal"><span class="pre">os.environ['_MEIPASS2']</span></tt>. Be awawre, though, that if you use <tt class="docutils literal"><span class="pre">--strip</span></tt> or <tt class="docutils literal"><span class="pre">--upx</span></tt>, |
|---|
| 1052 | strange things may happen to your data - <tt class="docutils literal"><span class="pre">BINARY</span></tt> is really for shared |
|---|
| 1053 | libs / dlls.</p> |
|---|
| 1054 | <p>If you add them as <tt class="docutils literal"><span class="pre">'DATA'</span></tt> to the <tt class="docutils literal"><span class="pre">EXE</span></tt>, then it's up to you to extract them. Use |
|---|
| 1055 | code like this:</p> |
|---|
| 1056 | <pre class="literal-block"> |
|---|
| 1057 | import sys, carchive |
|---|
| 1058 | this = carchive.CArchive(sys.executable) |
|---|
| 1059 | data = this.extract('mystuff')[1] |
|---|
| 1060 | </pre> |
|---|
| 1061 | <p>to get the contents as a binary string. See <a class="reference" href="http://pyinstaller.hpcf.upr.edu/pyinstaller/browser/trunk/support/unpackTK.py?rev=latest">support/unpackTK.py</a> for an advanced |
|---|
| 1062 | example (the TCL and TK lib files are in a PKG which is opened in place, and |
|---|
| 1063 | then extracted to the filesystem).</p> |
|---|
| 1064 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1065 | </div> |
|---|
| 1066 | </div> |
|---|
| 1067 | </div> |
|---|
| 1068 | <div class="section"> |
|---|
| 1069 | <h1><a class="toc-backref" href="#id41" id="miscellaneous" name="miscellaneous">Miscellaneous</a></h1> |
|---|
| 1070 | <div class="section"> |
|---|
| 1071 | <h2><a class="toc-backref" href="#id42" id="pmw-python-mega-widgets" name="pmw-python-mega-widgets">Pmw -- Python Mega Widgets</a></h2> |
|---|
| 1072 | <p><a class="reference" href="http://pmw.sourceforge.net/">Pmw</a> comes with a script named <tt class="docutils literal"><span class="pre">bundlepmw</span></tt> in the bin directory. If you follow the |
|---|
| 1073 | instructions in that script, you'll end up with a module named <tt class="docutils literal"><span class="pre">Pmw.py</span></tt>. Ensure |
|---|
| 1074 | that Builder finds that module and not the development package.</p> |
|---|
| 1075 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1076 | </div> |
|---|
| 1077 | <div class="section"> |
|---|
| 1078 | <h2><a class="toc-backref" href="#id43" id="win9xpopen" name="win9xpopen">Win9xpopen</a></h2> |
|---|
| 1079 | <p>If you're using popen on Windows and want the code to work on Win9x, you'll |
|---|
| 1080 | need to distribute <tt class="docutils literal"><span class="pre">win9xpopen.exe</span></tt> with your app. On older Pythons with |
|---|
| 1081 | Win32all, this would apply to Win32pipe and <tt class="docutils literal"><span class="pre">win32popenWin9x.exe</span></tt>. (On yet older |
|---|
| 1082 | Pythons, no form of popen worked on Win9x).</p> |
|---|
| 1083 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1084 | </div> |
|---|
| 1085 | <div class="section"> |
|---|
| 1086 | <h2><a class="toc-backref" href="#id44" id="self-extracting-executables" name="self-extracting-executables">Self-extracting executables</a></h2> |
|---|
| 1087 | <p>The ELF executable format (Windows, Linux and some others) allows arbitrary |
|---|
| 1088 | data to be concatenated to the end of the executable without disturbing its |
|---|
| 1089 | functionality. For this reason, a <tt class="docutils literal"><span class="pre">CArchive</span></tt>'s Table of Contents is at the end of |
|---|
| 1090 | the archive. The executable can open itself as a binary file name, seek to the |
|---|
| 1091 | end and 'open' the <tt class="docutils literal"><span class="pre">CArchive</span></tt> (see figure 3).</p> |
|---|
| 1092 | <p>On other platforms, the archive and the executable are separate, but the |
|---|
| 1093 | archive is named <tt class="docutils literal"><span class="pre">executable.pkg</span></tt>, and expected to be in the same directory. |
|---|
| 1094 | Other than that, the process is the same.</p> |
|---|
| 1095 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1096 | <div class="section"> |
|---|
| 1097 | <h3><a class="toc-backref" href="#id45" id="one-pass-execution" name="one-pass-execution">One Pass Execution</a></h3> |
|---|
| 1098 | <p>In a single directory deployment (<tt class="docutils literal"><span class="pre">--onedir</span></tt>, which is the default), all of the |
|---|
| 1099 | binaries are already in the file system. In that case, the embedding app:</p> |
|---|
| 1100 | <ul class="simple"> |
|---|
| 1101 | <li>opens the archive</li> |
|---|
| 1102 | <li>starts Python (on Windows, this is done with dynamic loading so one embedding |
|---|
| 1103 | app binary can be used with any Python version)</li> |
|---|
| 1104 | <li>imports all the modules which are at the top level of the archive (basically, |
|---|
| 1105 | bootstraps the import hooks)</li> |
|---|
| 1106 | <li>mounts the <tt class="docutils literal"><span class="pre">ZlibArchive(s)</span></tt> in the outer archive</li> |
|---|
| 1107 | <li>runs all the scripts which are at the top level of the archive</li> |
|---|
| 1108 | <li>finalizes Python</li> |
|---|
| 1109 | </ul> |
|---|
| 1110 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1111 | </div> |
|---|
| 1112 | <div class="section"> |
|---|
| 1113 | <h3><a class="toc-backref" href="#id46" id="two-pass-execution" name="two-pass-execution">Two Pass Execution</a></h3> |
|---|
| 1114 | <p>There are a couple situations which require two passes:</p> |
|---|
| 1115 | <ul class="simple"> |
|---|
| 1116 | <li>a <tt class="docutils literal"><span class="pre">--onefile</span></tt> deployment (on Windows, the files can't be cleaned up afterwards |
|---|
| 1117 | because Python does not call <tt class="docutils literal"><span class="pre">FreeLibrary</span></tt>; on other platforms, Python won't |
|---|
| 1118 | find them if they're extracted in the same process that uses them)</li> |
|---|
| 1119 | <li><tt class="docutils literal"><span class="pre">LD_LIBRARY_PATH</span></tt> needs to be set to find the binaries (not extension modules, |
|---|
| 1120 | but modules the extensions are linked to).</li> |
|---|
| 1121 | </ul> |
|---|
| 1122 | <p>The first pass:</p> |
|---|
| 1123 | <ul class="simple"> |
|---|
| 1124 | <li>opens the archive</li> |
|---|
| 1125 | <li>extracts all the binaries in the archive (in PyInstaller v1.0, this is always to a |
|---|
| 1126 | temporary directory).</li> |
|---|
| 1127 | <li>sets a magic environment variable</li> |
|---|
| 1128 | <li>sets <tt class="docutils literal"><span class="pre">LD_LIBRARY_PATH</span></tt> (non-Windows)</li> |
|---|
| 1129 | <li>executes itself as a child process (letting the child use his stdin, stdout |
|---|
| 1130 | and stderr)</li> |
|---|
| 1131 | <li>waits for the child to exit (on *nix, the child actually replaces the parent)</li> |
|---|
| 1132 | <li>cleans up the extracted binaries (so on *nix, this is done by the child)</li> |
|---|
| 1133 | </ul> |
|---|
| 1134 | <p>The child process executes as in <a class="reference" href="#one-pass-execution">One Pass Execution</a> above (the magic |
|---|
| 1135 | environment variable is what tells it that this is pass two).</p> |
|---|
| 1136 | <p><img alt="SE_exeImage" src="images/SE_exe.png" /> figure 3 - Self Extracting Executable</p> |
|---|
| 1137 | <p>There are, of course, quite a few differences between the Windows and |
|---|
| 1138 | Unix/Linux versions. The major one is that because all of Python on Windows is |
|---|
| 1139 | in <tt class="docutils literal"><span class="pre">pythonXX.dll</span></tt>, and dynamic loading is so simple-minded, that one binary can |
|---|
| 1140 | be use with any version of Python. There's much in common, though, and that C |
|---|
| 1141 | code can be found in <a class="reference" href="http://pyinstaller.hpcf.upr.edu/pyinstaller/browser/trunk/source/common/launch.c?rev=latest">source/common/launch.c</a>.</p> |
|---|
| 1142 | <p>The Unix/Linux build process (which you need to run just once for any version |
|---|
| 1143 | of Python) makes use of the config information in your install (if you |
|---|
| 1144 | installed from RPM, you need the Python-development RPM). It also overrides |
|---|
| 1145 | <tt class="docutils literal"><span class="pre">getpath.c</span></tt> since we don't want it hunting around the filesystem to build |
|---|
| 1146 | <tt class="docutils literal"><span class="pre">sys.path</span></tt>.</p> |
|---|
| 1147 | <p>In both cases, while one PyInstaller download can be used with any Python |
|---|
| 1148 | version, you need to have separate installations for each Python version.</p> |
|---|
| 1149 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1150 | </div> |
|---|
| 1151 | </div> |
|---|
| 1152 | </div> |
|---|
| 1153 | <div class="section"> |
|---|
| 1154 | <h1><a class="toc-backref" href="#id47" id="pyinstaller-archives" name="pyinstaller-archives">PyInstaller Archives</a></h1> |
|---|
| 1155 | <div class="section"> |
|---|
| 1156 | <h2><a class="toc-backref" href="#id48" id="archives-introduction" name="archives-introduction">Archives Introduction</a></h2> |
|---|
| 1157 | <p>You know what an archive is: a <tt class="docutils literal"><span class="pre">.tar</span></tt> file, a <tt class="docutils literal"><span class="pre">.jar</span></tt> file, a <tt class="docutils literal"><span class="pre">.zip</span></tt> file. Two kinds |
|---|
| 1158 | of archives are used here. One is equivalent to a Java <tt class="docutils literal"><span class="pre">.jar</span></tt> file - it allows |
|---|
| 1159 | Python modules to be stored efficiently and, (with some import hooks) imported |
|---|
| 1160 | directly. This is a <tt class="docutils literal"><span class="pre">ZlibArchive</span></tt>. The other (a <tt class="docutils literal"><span class="pre">CArchive</span></tt>) is equivalent to a |
|---|
| 1161 | <tt class="docutils literal"><span class="pre">.zip</span></tt> file - a general way of packing up (and optionally compressing) arbitrary |
|---|
| 1162 | blobs of data. It gets its name from the fact that it can be manipulated easily |
|---|
| 1163 | from C, as well as from Python. Both of these derive from a common base class, |
|---|
| 1164 | making it fairly easy to create new kinds of archives.</p> |
|---|
| 1165 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1166 | </div> |
|---|
| 1167 | <div class="section"> |
|---|
| 1168 | <h2><a class="toc-backref" href="#id49" id="zlibarchive" name="zlibarchive"><tt class="docutils literal docutils literal"><span class="pre">ZlibArchive</span></tt></a></h2> |
|---|
| 1169 | <p>A <tt class="docutils literal"><span class="pre">ZlibArchive</span></tt> contains compressed <tt class="docutils literal"><span class="pre">.pyc</span></tt> (or <tt class="docutils literal"><span class="pre">.pyo</span></tt>) files. The Table of Contents |
|---|
| 1170 | is a marshalled dictionary, with the key (the module's name as given in an |
|---|
| 1171 | <tt class="docutils literal"><span class="pre">import</span></tt> statement) associated with a seek position and length. Because it is |
|---|
| 1172 | all marshalled Python, <tt class="docutils literal"><span class="pre">ZlibArchives</span></tt> are completely cross-platform.</p> |
|---|
| 1173 | <p>A <tt class="docutils literal"><span class="pre">ZlibArchive</span></tt> hooks in with <a class="reference" href="#iu-py">iu.py</a> so that, with a little setup, the archived |
|---|
| 1174 | modules can be imported transparently. Even with compression at level 9, this |
|---|
| 1175 | works out to being faster than the normal import. Instead of searching |
|---|
| 1176 | <tt class="docutils literal"><span class="pre">sys.path</span></tt>, there's a lookup in the dictionary. There's no <tt class="docutils literal"><span class="pre">stat</span></tt>-ing of the <tt class="docutils literal"><span class="pre">.py</span></tt> |
|---|
| 1177 | and <tt class="docutils literal"><span class="pre">.pyc</span></tt> and no file opens (the file is already open). There's just a seek, a |
|---|
| 1178 | read and a decompress. A traceback will point to the source file the archive |
|---|
| 1179 | entry was created from (the <tt class="docutils literal"><span class="pre">__file__</span></tt> attribute from the time the <tt class="docutils literal"><span class="pre">.pyc</span></tt> was |
|---|
| 1180 | compiled). On a user's box with no source installed, this is not terribly |
|---|
| 1181 | useful, but if they send you the traceback, at least you can make sense of it.</p> |
|---|
| 1182 | <p><img alt="ZlibArchiveImage" src="images/ZlibArchive.png" /></p> |
|---|
| 1183 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1184 | </div> |
|---|
| 1185 | <div class="section"> |
|---|
| 1186 | <h2><a class="toc-backref" href="#id50" id="carchive" name="carchive"><tt class="docutils literal docutils literal"><span class="pre">CArchive</span></tt></a></h2> |
|---|
| 1187 | <p>A <tt class="docutils literal"><span class="pre">CArchive</span></tt> contains whatever you want to stuff into it. It's very much like a |
|---|
| 1188 | <tt class="docutils literal"><span class="pre">.zip</span></tt> file. They are easy to create in Python and unpack from C code. <tt class="docutils literal"><span class="pre">CArchives</span></tt> |
|---|
| 1189 | can be appended to other files (like ELF and COFF executables, for example). |
|---|
| 1190 | To allow this, they are opened from the end, so the <tt class="docutils literal"><span class="pre">TOC</span></tt> for a <tt class="docutils literal"><span class="pre">CArchive</span></tt> is at |
|---|
| 1191 | the back, followed only by a cookie that tells you where the <tt class="docutils literal"><span class="pre">TOC</span></tt> starts and |
|---|
| 1192 | where the archive itself starts.</p> |
|---|
| 1193 | <p><tt class="docutils literal"><span class="pre">CArchives</span></tt> can also be embedded within other <tt class="docutils literal"><span class="pre">CArchives</span></tt>. The inner archive can be |
|---|
| 1194 | opened in place (without extraction).</p> |
|---|
| 1195 | <p>Each <tt class="docutils literal"><span class="pre">TOC</span></tt> entry is variable length. The first field in the entry tells you the |
|---|
| 1196 | length of the entry. The last field is the name of the corresponding packed |
|---|
| 1197 | file. The name is null terminated. Compression is optional by member.</p> |
|---|
| 1198 | <p>There is also a type code associated with each entry. If you're using a |
|---|
| 1199 | <tt class="docutils literal"><span class="pre">CArchive</span></tt> as a <tt class="docutils literal"><span class="pre">.zip</span></tt> file, you don't need to worry about this. The type codes |
|---|
| 1200 | are used by the self-extracting executables.</p> |
|---|
| 1201 | <p><img alt="CArchiveImage" src="images/CArchive.png" /></p> |
|---|
| 1202 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1203 | </div> |
|---|
| 1204 | </div> |
|---|
| 1205 | <div class="section"> |
|---|
| 1206 | <h1><a class="toc-backref" href="#id51" id="license" name="license">License</a></h1> |
|---|
| 1207 | <p>PyInstaller is mainly distributed under the |
|---|
| 1208 | <a class="reference" href="http://pyinstaller.hpcf.upr.edu/pyinstaller/browser/trunk/doc/LICENSE.GPL?rev=latest">GPL License</a> |
|---|
| 1209 | but it has an exception such that you can use it to compile commercial products.</p> |
|---|
| 1210 | <p>In a nutshell, the license is GPL for the source code with the exception that:</p> |
|---|
| 1211 | <blockquote> |
|---|
| 1212 | <ol class="arabic simple"> |
|---|
| 1213 | <li>You may use PyInstaller to compile commercial applications out of your |
|---|
| 1214 | source code.</li> |
|---|
| 1215 | <li>The resulting binaries generated by PyInstaller from your source code can be |
|---|
| 1216 | shipped with whatever license you want.</li> |
|---|
| 1217 | <li>You may modify PyInstaller for your own needs but <em>these</em> changes to the |
|---|
| 1218 | PyInstaller source code falls under the terms of the GPL license. In other |
|---|
| 1219 | words, any modifications to will <em>have</em> to be distributed under GPL.</li> |
|---|
| 1220 | </ol> |
|---|
| 1221 | </blockquote> |
|---|
| 1222 | <p>For updated information or clarification see our |
|---|
| 1223 | <a class="reference" href="http://pyinstaller.hpcf.upr.edu/pyinstaller/wiki/FAQ">FAQ</a> at <a class="reference" href="http://pyinstaller.hpcf.upr.edu/pyinstaller">PyInstaller</a> |
|---|
| 1224 | home page: <a class="reference" href="http://pyinstaller.hpcf.upr.edu">http://pyinstaller.hpcf.upr.edu</a></p> |
|---|
| 1225 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1226 | </div> |
|---|
| 1227 | <div class="section"> |
|---|
| 1228 | <h1><a class="toc-backref" href="#id52" id="appendix" name="appendix">Appendix</a></h1> |
|---|
| 1229 | <div class="sidebar"> |
|---|
| 1230 | <p class="first sidebar-title">You can stop reading here...</p> |
|---|
| 1231 | <p class="last">... if you are not interested in technical details. This appendix contains |
|---|
| 1232 | insights of the internal workings of PyInstaller, and you do not need this |
|---|
| 1233 | information unless you plan to work on PyInstaller itself.</p> |
|---|
| 1234 | </div> |
|---|
| 1235 | <div class="section"> |
|---|
| 1236 | <h2><a class="toc-backref" href="#id53" id="mf-py-a-modulefinder-replacement" name="mf-py-a-modulefinder-replacement"><tt class="docutils literal docutils literal"><span class="pre">mf.py</span></tt>: A Modulefinder Replacement</a></h2> |
|---|
| 1237 | <p>Module <tt class="docutils literal"><span class="pre">mf</span></tt> is modelled after <tt class="docutils literal"><span class="pre">iu</span></tt>.</p> |
|---|
| 1238 | <p>It also uses <tt class="docutils literal"><span class="pre">ImportDirectors</span></tt> and <tt class="docutils literal"><span class="pre">Owners</span></tt> to partition the import name space. |
|---|
| 1239 | Except for the fact that these return <tt class="docutils literal"><span class="pre">Module</span></tt> instances instead of real module |
|---|
| 1240 | objects, they are identical.</p> |
|---|
| 1241 | <p>Instead of an <tt class="docutils literal"><span class="pre">ImportManager</span></tt>, <tt class="docutils literal"><span class="pre">mf</span></tt> has an <tt class="docutils literal"><span class="pre">ImportTracker</span></tt> managing things.</p> |
|---|
| 1242 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1243 | <div class="section"> |
|---|
| 1244 | <h3><a class="toc-backref" href="#id54" id="importtracker" name="importtracker">ImportTracker</a></h3> |
|---|
| 1245 | <p><tt class="docutils literal"><span class="pre">ImportTracker</span></tt> can be called in two ways: <tt class="docutils literal"><span class="pre">analyze_one(name,</span> <span class="pre">importername=None)</span></tt> |
|---|
| 1246 | or <tt class="docutils literal"><span class="pre">analyze_r(name,</span> <span class="pre">importername=None)</span></tt>. The second method does what modulefinder |
|---|
| 1247 | does - it recursively finds all the module names that importing name would |
|---|
| 1248 | cause to appear in <tt class="docutils literal"><span class="pre">sys.modules</span></tt>. The first method is non-recursive. This is |
|---|
| 1249 | useful, because it is the only way of answering the question "Who imports |
|---|
| 1250 | name?" But since it is somewhat unrealistic (very few real imports do not |
|---|
| 1251 | involve recursion), it deserves some explanation.</p> |
|---|
| 1252 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1253 | </div> |
|---|
| 1254 | <div class="section"> |
|---|
| 1255 | <h3><a class="toc-backref" href="#id55" id="analyze-one" name="analyze-one"><tt class="docutils literal docutils literal"><span class="pre">analyze_one()</span></tt></a></h3> |
|---|
| 1256 | <p>When a name is imported, there are structural and dynamic effects. The dynamic |
|---|
| 1257 | effects are due to the execution of the top-level code in the module (or |
|---|
| 1258 | modules) that get imported. The structural effects have to do with whether the |
|---|
| 1259 | import is relative or absolute, and whether the name is a dotted name (if there |
|---|
| 1260 | are N dots in the name, then N+1 modules will be imported even without any code |
|---|
| 1261 | running).</p> |
|---|
| 1262 | <p>The analyze_one method determines the structural effects, and defers the |
|---|
| 1263 | dynamic effects. For example, <tt class="docutils literal"><span class="pre">analyze_one("B.C",</span> <span class="pre">"A")</span></tt> could return <tt class="docutils literal"><span class="pre">["B",</span> <span class="pre">"B.C"]</span></tt> |
|---|
| 1264 | or <tt class="docutils literal"><span class="pre">["A.B",</span> <span class="pre">"A.B.C"]</span></tt> depending on whether the import turns out to be relative or |
|---|
| 1265 | absolute. In addition, ImportTracker's modules dict will have Module instances |
|---|
| 1266 | for them.</p> |
|---|
| 1267 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1268 | </div> |
|---|
| 1269 | <div class="section"> |
|---|
| 1270 | <h3><a class="toc-backref" href="#id56" id="module-classes" name="module-classes">Module Classes</a></h3> |
|---|
| 1271 | <p>There are Module subclasses for builtins, extensions, packages and (normal) |
|---|
| 1272 | modules. Besides the normal module object attributes, they have an attribute |
|---|
| 1273 | imports. For packages and normal modules, imports is a list populated by |
|---|
| 1274 | scanning the code object (and therefor, the names in this list may be relative |
|---|
| 1275 | or absolute names - we don't know until they have been analyzed).</p> |
|---|
| 1276 | <p>The highly astute will notice that there is a hole in <tt class="docutils literal"><span class="pre">analyze_one()</span></tt> here. The |
|---|
| 1277 | first thing that happens when <tt class="docutils literal"><span class="pre">B.C</span></tt> is being imported is that <tt class="docutils literal"><span class="pre">B</span></tt> is imported and |
|---|
| 1278 | it's top-level code executed. That top-level code can do various things so that |
|---|
| 1279 | when the import of <tt class="docutils literal"><span class="pre">B.C</span></tt> finally occurs, something completely different happens |
|---|
| 1280 | (from what a structural analysis would predict). But mf can handle this through |
|---|
| 1281 | it's hooks mechanism.</p> |
|---|
| 1282 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1283 | </div> |
|---|
| 1284 | <div class="section"> |
|---|
| 1285 | <h3><a class="toc-backref" href="#id57" id="code-scanning" name="code-scanning">code scanning</a></h3> |
|---|
| 1286 | <p>Like modulefinder, <tt class="docutils literal"><span class="pre">mf</span></tt> scans the byte code of a module, looking for imports. In |
|---|
| 1287 | addition, <tt class="docutils literal"><span class="pre">mf</span></tt> will pick out a module's <tt class="docutils literal"><span class="pre">__all__</span></tt> attribute, if it is built as a |
|---|
| 1288 | list of constant names. This means that if a package declares an <tt class="docutils literal"><span class="pre">__all__</span></tt> list |
|---|
| 1289 | as a list of names, ImportTracker will track those names if asked to analyze |
|---|
| 1290 | <tt class="docutils literal"><span class="pre">package.*</span></tt>. The code scan also notes the occurance of <tt class="docutils literal"><span class="pre">__import__</span></tt>, <tt class="docutils literal"><span class="pre">exec</span></tt> and <tt class="docutils literal"><span class="pre">eval</span></tt>, |
|---|
| 1291 | and can issue warnings when they're found.</p> |
|---|
| 1292 | <p>The code scanning also keeps track (as well as it can) of the context of an |
|---|
| 1293 | import. It recognizes when imports are found at the top-level, and when they |
|---|
| 1294 | are found inside definitions (deferred imports). Within that, it also tracks |
|---|
| 1295 | whether the import is inside a condition (conditional imports).</p> |
|---|
| 1296 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1297 | </div> |
|---|
| 1298 | <div class="section"> |
|---|
| 1299 | <h3><a class="toc-backref" href="#id58" id="hooks" name="hooks">Hooks</a></h3> |
|---|
| 1300 | <p>In modulefinder, scanning the code takes the place of executing the code |
|---|
| 1301 | object. <tt class="docutils literal"><span class="pre">mf</span></tt> goes further and allows a module to be hooked (after it has been |
|---|
| 1302 | scanned, but before analyze_one is done with it). A hook is a module named |
|---|
| 1303 | <tt class="docutils literal"><span class="pre">hook-fullyqualifiedname</span></tt> in the <tt class="docutils literal"><span class="pre">hooks</span></tt> package. These modules should have one or |
|---|
| 1304 | more of the following three global names defined:</p> |
|---|
| 1305 | <dl class="docutils"> |
|---|
| 1306 | <dt><tt class="docutils literal"><span class="pre">hiddenimports</span></tt></dt> |
|---|
| 1307 | <dd>a list of modules names (relative or absolute) that the module imports in some untrackable way.</dd> |
|---|
| 1308 | <dt><tt class="docutils literal"><span class="pre">attrs</span></tt></dt> |
|---|
| 1309 | <dd>a list of <tt class="docutils literal"><span class="pre">(name,</span> <span class="pre">value)</span></tt> pairs (where value is normally meaningless).</dd> |
|---|
| 1310 | <dt><tt class="docutils literal"><span class="pre">hook(mod)</span></tt></dt> |
|---|
| 1311 | <dd>a function taking a <tt class="docutils literal"><span class="pre">Module</span></tt> instance and returning a <tt class="docutils literal"><span class="pre">Module</span></tt> instance (so it can modify or replace).</dd> |
|---|
| 1312 | </dl> |
|---|
| 1313 | <p>The first hook (<tt class="docutils literal"><span class="pre">hiddenimports</span></tt>) extends the list created by scanning the code. |
|---|
| 1314 | <tt class="docutils literal"><span class="pre">ExtensionModules</span></tt>, of course, don't get scanned, so this is the only way of |
|---|
| 1315 | recording any imports they do.</p> |
|---|
| 1316 | <p>The second hook (<tt class="docutils literal"><span class="pre">attrs</span></tt>) exists mainly so that ImportTracker won't issue |
|---|
| 1317 | spurious warnings when the rightmost node in a dotted name turns out to be an |
|---|
| 1318 | attribute in a package module, instead of a missing submodule.</p> |
|---|
| 1319 | <p>The callable hook exists for things like dynamic modification of a package's |
|---|
| 1320 | <tt class="docutils literal"><span class="pre">__path__</span></tt> or perverse situations, like <tt class="docutils literal"><span class="pre">xml.__init__</span></tt> replacing itself in |
|---|
| 1321 | <tt class="docutils literal"><span class="pre">sys.modules</span></tt> with <tt class="docutils literal"><span class="pre">_xmlplus.__init__</span></tt>. (It takes nine hook modules to properly |
|---|
| 1322 | trace through PyXML-using code, and I can't believe that it's any easier for |
|---|
| 1323 | the poor programmer using that package). The <tt class="docutils literal"><span class="pre">hook(mod)</span></tt> (if it exists) is |
|---|
| 1324 | called before looking at the others - that way it can, for example, test |
|---|
| 1325 | <tt class="docutils literal"><span class="pre">sys.version</span></tt> and adjust what's in <tt class="docutils literal"><span class="pre">hiddenimports</span></tt>.</p> |
|---|
| 1326 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1327 | </div> |
|---|
| 1328 | <div class="section"> |
|---|
| 1329 | <h3><a class="toc-backref" href="#id59" id="warnings" name="warnings">Warnings</a></h3> |
|---|
| 1330 | <p><tt class="docutils literal"><span class="pre">ImportTracker</span></tt> has a <tt class="docutils literal"><span class="pre">getwarnings()</span></tt> method that returns all the warnings |
|---|
| 1331 | accumulated by the instance, and by the <tt class="docutils literal"><span class="pre">Module</span></tt> instances in its modules dict. |
|---|
| 1332 | Generally, it is <tt class="docutils literal"><span class="pre">ImportTracker</span></tt> who will accumulate the warnings generated |
|---|
| 1333 | during the structural phase, and <tt class="docutils literal"><span class="pre">Modules</span></tt> that will get the warnings generated |
|---|
| 1334 | during the code scan.</p> |
|---|
| 1335 | <p>Note that by using a hook module, you can silence some particularly tiresome |
|---|
| 1336 | warnings, but not all of them.</p> |
|---|
| 1337 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1338 | </div> |
|---|
| 1339 | <div class="section"> |
|---|
| 1340 | <h3><a class="toc-backref" href="#id60" id="cross-reference" name="cross-reference">Cross Reference</a></h3> |
|---|
| 1341 | <p>Once a full analysis (that is, an <tt class="docutils literal"><span class="pre">analyze_r</span></tt> call) has been done, you can get a |
|---|
| 1342 | cross reference by using <tt class="docutils literal"><span class="pre">getxref()</span></tt>. This returns a list of tuples. Each tuple |
|---|
| 1343 | is <tt class="docutils literal"><span class="pre">(modulename,</span> <span class="pre">importers)</span></tt>, where importers is a list of the (fully qualified) |
|---|
| 1344 | names of the modules importing <tt class="docutils literal"><span class="pre">modulename</span></tt>. Both the returned list and the |
|---|
| 1345 | importers list are sorted.</p> |
|---|
| 1346 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1347 | </div> |
|---|
| 1348 | <div class="section"> |
|---|
| 1349 | <h3><a class="toc-backref" href="#id61" id="usage" name="usage">Usage</a></h3> |
|---|
| 1350 | <p>A simple example follows:</p> |
|---|
| 1351 | <blockquote> |
|---|
| 1352 | <pre class="doctest-block"> |
|---|
| 1353 | >>> import mf |
|---|
| 1354 | >>> a = mf.ImportTracker() |
|---|
| 1355 | >>> a.analyze_r("os") |
|---|
| 1356 | ['os', 'sys', 'posixpath', 'nt', 'stat', 'string', 'strop', |
|---|
| 1357 | 're', 'pcre', 'ntpath', 'dospath', 'macpath', 'win32api', |
|---|
| 1358 | 'UserDict', 'copy', 'types', 'repr', 'tempfile'] |
|---|
| 1359 | >>> a.analyze_one("os") |
|---|
| 1360 | ['os'] |
|---|
| 1361 | >>> a.modules['string'].imports |
|---|
| 1362 | [('strop', 0, 0), ('strop.*', 0, 0), ('re', 1, 1)] |
|---|
| 1363 | >>> |
|---|
| 1364 | </pre> |
|---|
| 1365 | </blockquote> |
|---|
| 1366 | <p>The tuples in the imports list are (name, delayed, conditional).</p> |
|---|
| 1367 | <blockquote> |
|---|
| 1368 | <pre class="doctest-block"> |
|---|
| 1369 | >>> for w in a.modules['string'].warnings: print w |
|---|
| 1370 | ... |
|---|
| 1371 | W: delayed eval hack detected at line 359 |
|---|
| 1372 | W: delayed eval hack detected at line 389 |
|---|
| 1373 | W: delayed eval hack detected at line 418 |
|---|
| 1374 | >>> for w in a.getwarnings(): print w |
|---|
| 1375 | ... |
|---|
| 1376 | W: no module named pwd (delayed, conditional import by posixpath) |
|---|
| 1377 | W: no module named dos (conditional import by os) |
|---|
| 1378 | W: no module named os2 (conditional import by os) |
|---|
| 1379 | W: no module named posix (conditional import by os) |
|---|
| 1380 | W: no module named mac (conditional import by os) |
|---|
| 1381 | W: no module named MACFS (delayed, conditional import by tempfile) |
|---|
| 1382 | W: no module named macfs (delayed, conditional import by tempfile) |
|---|
| 1383 | W: top-level conditional exec statment detected at line 47 |
|---|
| 1384 | - os (C:\Program Files\Python\Lib\os.py) |
|---|
| 1385 | W: delayed eval hack detected at line 359 |
|---|
| 1386 | - string (C:\Program Files\Python\Lib\string.py) |
|---|
| 1387 | W: delayed eval hack detected at line 389 |
|---|
| 1388 | - string (C:\Program Files\Python\Lib\string.py) |
|---|
| 1389 | W: delayed eval hack detected at line 418 |
|---|
| 1390 | - string (C:\Program Files\Python\Lib\string.py) |
|---|
| 1391 | >>> |
|---|
| 1392 | </pre> |
|---|
| 1393 | </blockquote> |
|---|
| 1394 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1395 | </div> |
|---|
| 1396 | </div> |
|---|
| 1397 | <div class="section"> |
|---|
| 1398 | <h2><a class="toc-backref" href="#id62" id="iu-py-an-imputil-replacement" name="iu-py-an-imputil-replacement"><span id="iu-py"></span><tt class="docutils literal docutils literal"><span class="pre">iu.py</span></tt>: An <em>imputil</em> Replacement</a></h2> |
|---|
| 1399 | <p>Module <tt class="docutils literal"><span class="pre">iu</span></tt> grows out of the pioneering work that Greg Stein did with <tt class="docutils literal"><span class="pre">imputil</span></tt> |
|---|
| 1400 | (actually, it includes some verbatim <tt class="docutils literal"><span class="pre">imputil</span></tt> code, but since Greg didn't |
|---|
| 1401 | copyright it, we won't mention it). Both modules can take over Python's |
|---|
| 1402 | builtin import and ease writing of at least certain kinds of import hooks.</p> |
|---|
| 1403 | <p><tt class="docutils literal"><span class="pre">iu</span></tt> differs from <tt class="docutils literal"><span class="pre">imputil</span></tt>: |
|---|
| 1404 | * faster |
|---|
| 1405 | * better emulation of builtin import |
|---|
| 1406 | * more managable</p> |
|---|
| 1407 | <p>There is an <tt class="docutils literal"><span class="pre">ImportManager</span></tt> which provides the replacement for builtin import |
|---|
| 1408 | and hides all the semantic complexities of a Python import request from it's |
|---|
| 1409 | delegates.</p> |
|---|
| 1410 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1411 | <div class="section"> |
|---|
| 1412 | <h3><a class="toc-backref" href="#id63" id="importmanager" name="importmanager"><tt class="docutils literal docutils literal"><span class="pre">ImportManager</span></tt></a></h3> |
|---|
| 1413 | <p><tt class="docutils literal"><span class="pre">ImportManager</span></tt> formalizes the concept of a metapath. This concept implicitly |
|---|
| 1414 | exists in native Python in that builtins and frozen modules are searched |
|---|
| 1415 | before <tt class="docutils literal"><span class="pre">sys.path</span></tt>, (on Windows there's also a search of the registry while on |
|---|
| 1416 | Mac, resources may be searched). This metapath is a list populated with |
|---|
| 1417 | <tt class="docutils literal"><span class="pre">ImportDirector</span></tt> instances. There are <tt class="docutils literal"><span class="pre">ImportDirector</span></tt> subclasses for builtins, |
|---|
| 1418 | frozen modules, (on Windows) modules found through the registry and a |
|---|
| 1419 | <tt class="docutils literal"><span class="pre">PathImportDirector</span></tt> for handling <tt class="docutils literal"><span class="pre">sys.path</span></tt>. For a top-level import (that is, not |
|---|
| 1420 | an import of a module in a package), <tt class="docutils literal"><span class="pre">ImportManager</span></tt> tries each director on it's |
|---|
| 1421 | metapath until one succeeds.</p> |
|---|
| 1422 | <p><tt class="docutils literal"><span class="pre">ImportManager</span></tt> hides the semantic complexity of an import from the directors. |
|---|
| 1423 | It's up to the <tt class="docutils literal"><span class="pre">ImportManager</span></tt> to decide if an import is relative or absolute; |
|---|
| 1424 | to see if the module has already been imported; to keep <tt class="docutils literal"><span class="pre">sys.modules</span></tt> up to |
|---|
| 1425 | date; to handle the fromlist and return the correct module object.</p> |
|---|
| 1426 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1427 | </div> |
|---|
| 1428 | <div class="section"> |
|---|
| 1429 | <h3><a class="toc-backref" href="#id64" id="importdirector" name="importdirector"><tt class="docutils literal docutils literal"><span class="pre">ImportDirector</span></tt></a></h3> |
|---|
| 1430 | <p>An <tt class="docutils literal"><span class="pre">ImportDirector</span></tt> just needs to respond to <tt class="docutils literal"><span class="pre">getmod(name)</span></tt> by returning a module |
|---|
| 1431 | object or <tt class="docutils literal"><span class="pre">None</span></tt>. As you will see, an <tt class="docutils literal"><span class="pre">ImportDirector</span></tt> can consider name to be |
|---|
| 1432 | atomic - it has no need to examine name to see if it is dotted.</p> |
|---|
| 1433 | <p>To see how this works, we need to examine the <tt class="docutils literal"><span class="pre">PathImportDirector</span></tt>.</p> |
|---|
| 1434 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1435 | </div> |
|---|
| 1436 | <div class="section"> |
|---|
| 1437 | <h3><a class="toc-backref" href="#id65" id="pathimportdirector" name="pathimportdirector"><tt class="docutils literal docutils literal"><span class="pre">PathImportDirector</span></tt></a></h3> |
|---|
| 1438 | <p>The <tt class="docutils literal"><span class="pre">PathImportDirector</span></tt> subclass manages a list of names - most notably, |
|---|
| 1439 | <tt class="docutils literal"><span class="pre">sys.path</span></tt>. To do so, it maintains a shadowpath - a dictionary mapping the names |
|---|
| 1440 | on its pathlist (eg, <tt class="docutils literal"><span class="pre">sys.path</span></tt>) to their associated <tt class="docutils literal"><span class="pre">Owners</span></tt>. (It could do this |
|---|
| 1441 | directly, but the assumption that sys.path is occupied solely by strings seems |
|---|
| 1442 | ineradicable.) <tt class="docutils literal"><span class="pre">Owners</span></tt> of the appropriate kind are created as needed (if all |
|---|
| 1443 | your imports are satisfied by the first two elements of <tt class="docutils literal"><span class="pre">sys.path</span></tt>, the |
|---|
| 1444 | <tt class="docutils literal"><span class="pre">PathImportDirector</span></tt>'s shadowpath will only have two entries).</p> |
|---|
| 1445 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1446 | </div> |
|---|
| 1447 | <div class="section"> |
|---|
| 1448 | <h3><a class="toc-backref" href="#id66" id="owner" name="owner"><tt class="docutils literal docutils literal"><span class="pre">Owner</span></tt></a></h3> |
|---|
| 1449 | <p>An <tt class="docutils literal"><span class="pre">Owner</span></tt> is much like an <tt class="docutils literal"><span class="pre">ImportDirector</span></tt> but manages a much more concrete piece |
|---|
| 1450 | of turf. For example, a <tt class="docutils literal"><span class="pre">DirOwner</span></tt> manages one directory. Since there are no |
|---|
| 1451 | other officially recognized filesystem-like namespaces for importing, that's |
|---|
| 1452 | all that's included in iu, but it's easy to imagine <tt class="docutils literal"><span class="pre">Owners</span></tt> for zip files |
|---|
| 1453 | (and I have one for my own <tt class="docutils literal"><span class="pre">.pyz</span></tt> archive format) or even URLs.</p> |
|---|
| 1454 | <p>As with <tt class="docutils literal"><span class="pre">ImportDirectors</span></tt>, an <tt class="docutils literal"><span class="pre">Owner</span></tt> just needs to respond to <tt class="docutils literal"><span class="pre">getmod(name)</span></tt> by |
|---|
| 1455 | returning a module object or <tt class="docutils literal"><span class="pre">None</span></tt>, and it can consider name to be atomic.</p> |
|---|
| 1456 | <p>So structurally, we have a tree, rooted at the <tt class="docutils literal"><span class="pre">ImportManager</span></tt>. At the next |
|---|
| 1457 | level, we have a set of <tt class="docutils literal"><span class="pre">ImportDirectors</span></tt>. At least one of those directors, the |
|---|
| 1458 | <tt class="docutils literal"><span class="pre">PathImportDirector</span></tt> in charge of <tt class="docutils literal"><span class="pre">sys.path</span></tt>, has another level beneath it, |
|---|
| 1459 | consisting of <tt class="docutils literal"><span class="pre">Owners</span></tt>. This much of the tree covers the entire top-level import |
|---|
| 1460 | namespace.</p> |
|---|
| 1461 | <p>The rest of the import namespace is covered by treelets, each rooted in a |
|---|
| 1462 | package module (an <tt class="docutils literal"><span class="pre">__init__.py</span></tt>).</p> |
|---|
| 1463 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1464 | </div> |
|---|
| 1465 | <div class="section"> |
|---|
| 1466 | <h3><a class="toc-backref" href="#id67" id="packages" name="packages">Packages</a></h3> |
|---|
| 1467 | <p>To make this work, <tt class="docutils literal"><span class="pre">Owners</span></tt> need to recognize when a module is a package. For a |
|---|
| 1468 | <tt class="docutils literal"><span class="pre">DirOwner</span></tt>, this means that name is a subdirectory which contains an <tt class="docutils literal"><span class="pre">__init__.py</span></tt>. |
|---|
| 1469 | The <tt class="docutils literal"><span class="pre">__init__</span></tt> module is loaded and its <tt class="docutils literal"><span class="pre">__path__</span></tt> is initialized with the |
|---|
| 1470 | subdirectory. Then, a <tt class="docutils literal"><span class="pre">PathImportDirector</span></tt> is created to manage this <tt class="docutils literal"><span class="pre">__path__</span></tt>. |
|---|
| 1471 | Finally the new <tt class="docutils literal"><span class="pre">PathImportDirector</span></tt>'s <tt class="docutils literal"><span class="pre">getmod</span></tt> is assigned to the package's |
|---|
| 1472 | <tt class="docutils literal"><span class="pre">__importsub__</span></tt> function.</p> |
|---|
| 1473 | <p>When a module within the package is imported, the request is routed (by the |
|---|
| 1474 | <tt class="docutils literal"><span class="pre">ImportManager</span></tt>) diretly to the package's <tt class="docutils literal"><span class="pre">__importsub__</span></tt>. In a hierarchical |
|---|
| 1475 | namespace (like a filesystem), this means that <tt class="docutils literal"><span class="pre">__importsub__</span></tt> (which is really |
|---|
| 1476 | the bound getmod method of a <tt class="docutils literal"><span class="pre">PathImportDirector</span></tt> instance) needs only the |
|---|
| 1477 | module name, not the package name or the fully qualified name. And that's |
|---|
| 1478 | exactly what it gets. (In a flat namespace - like most archives - it is |
|---|
| 1479 | perfectly easy to route the request back up the package tree to the archive |
|---|
| 1480 | <tt class="docutils literal"><span class="pre">Owner</span></tt>, qualifying the name at each step.)</p> |
|---|
| 1481 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1482 | </div> |
|---|
| 1483 | <div class="section"> |
|---|
| 1484 | <h3><a class="toc-backref" href="#id68" id="possibilities" name="possibilities">Possibilities</a></h3> |
|---|
| 1485 | <p>Let's say we want to import from zip files. So, we subclass <tt class="docutils literal"><span class="pre">Owner</span></tt>. The |
|---|
| 1486 | <tt class="docutils literal"><span class="pre">__init__</span></tt> method should take a filename, and raise a <tt class="docutils literal"><span class="pre">ValueError</span></tt> if the file is |
|---|
| 1487 | not an acceptable <tt class="docutils literal"><span class="pre">.zip</span></tt> file, (when a new name is encountered on <tt class="docutils literal"><span class="pre">sys.path</span></tt> or a |
|---|
| 1488 | package's <tt class="docutils literal"><span class="pre">__path__</span></tt>, registered Owners are tried until one accepts the name). |
|---|
| 1489 | The <tt class="docutils literal"><span class="pre">getmod</span></tt> method would check the zip file's contents and return <tt class="docutils literal"><span class="pre">None</span></tt> if the |
|---|
| 1490 | name is not found. Otherwise, it would extract the marshalled code object from |
|---|
| 1491 | the zip, create a new module object and perform a bit of initialization (12 |
|---|
| 1492 | lines of code all told for my own archive format, including initializing a pack |
|---|
| 1493 | age with it's <tt class="docutils literal"><span class="pre">__subimporter__</span></tt>).</p> |
|---|
| 1494 | <p>Once the new <tt class="docutils literal"><span class="pre">Owner</span></tt> class is registered with <tt class="docutils literal"><span class="pre">iu</span></tt>, you can put a zip file on |
|---|
| 1495 | <tt class="docutils literal"><span class="pre">sys.path</span></tt>. A package could even put a zip file on its <tt class="docutils literal"><span class="pre">__path__</span></tt>.</p> |
|---|
| 1496 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1497 | </div> |
|---|
| 1498 | <div class="section"> |
|---|
| 1499 | <h3><a class="toc-backref" href="#id69" id="compatibility" name="compatibility">Compatibility</a></h3> |
|---|
| 1500 | <p>This code has been tested with the PyXML, mxBase and Win32 packages, covering |
|---|
| 1501 | over a dozen import hacks from manipulations of <tt class="docutils literal"><span class="pre">__path__</span></tt> to replacing a module |
|---|
| 1502 | in <tt class="docutils literal"><span class="pre">sys.modules</span></tt> with a different one. Emulation of Python's native import is |
|---|
| 1503 | nearly exact, including the names recorded in <tt class="docutils literal"><span class="pre">sys.modules</span></tt> and module attributes |
|---|
| 1504 | (packages imported through <tt class="docutils literal"><span class="pre">iu</span></tt> have an extra attribute - <tt class="docutils literal"><span class="pre">__importsub__</span></tt>).</p> |
|---|
| 1505 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1506 | </div> |
|---|
| 1507 | <div class="section"> |
|---|
| 1508 | <h3><a class="toc-backref" href="#id70" id="performance" name="performance">Performance</a></h3> |
|---|
| 1509 | <p>In most cases, <tt class="docutils literal"><span class="pre">iu</span></tt> is slower than builtin import (by 15 to 20%) but faster than |
|---|
| 1510 | <tt class="docutils literal"><span class="pre">imputil</span></tt> (by 15 to 20%). By inserting archives at the front of <tt class="docutils literal"><span class="pre">sys.path</span></tt> |
|---|
| 1511 | containing the standard lib and the package being tested, this can be reduced |
|---|
| 1512 | to 5 to 10% slower (or, on my 1.52 box, 10% faster!) than builtin import. A bit |
|---|
| 1513 | more can be shaved off by manipulating the <tt class="docutils literal"><span class="pre">ImportManager</span></tt>'s metapath.</p> |
|---|
| 1514 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1515 | </div> |
|---|
| 1516 | <div class="section"> |
|---|
| 1517 | <h3><a class="toc-backref" href="#id71" id="limitations" name="limitations">Limitations</a></h3> |
|---|
| 1518 | <p>This module makes no attempt to facilitate policy import hacks. It is easy to |
|---|
| 1519 | implement certain kinds of policies within a particular domain, but |
|---|
| 1520 | fundamentally iu works by dividing up the import namespace into independent |
|---|
| 1521 | domains.</p> |
|---|
| 1522 | <p>Quite simply, I think cross-domain import hacks are a very bad idea. As author |
|---|
| 1523 | of the original package on which PyInstaller is based, McMillan worked with |
|---|
| 1524 | import hacks for many years. Many of them are highly fragile; they often rely |
|---|
| 1525 | on undocumented (maybe even accidental) features of implementation. |
|---|
| 1526 | A cross-domain import hack is not likely to work with PyXML, for example.</p> |
|---|
| 1527 | <p>That rant aside, you can modify <tt class="docutils literal"><span class="pre">ImportManger</span></tt> to implement different policies. |
|---|
| 1528 | For example, a version that implements three import primitives: absolute |
|---|
| 1529 | import, relative import and recursive-relative import. No idea what the Python |
|---|
| 1530 | syntax for those should be, but <tt class="docutils literal"><span class="pre">__aimport__</span></tt>, <tt class="docutils literal"><span class="pre">__rimport__</span></tt> and <tt class="docutils literal"><span class="pre">__rrimport__</span></tt> were |
|---|
| 1531 | easy to implement.</p> |
|---|
| 1532 | </div> |
|---|
| 1533 | <div class="section"> |
|---|
| 1534 | <h3><a class="toc-backref" href="#id72" id="id1" name="id1">Usage</a></h3> |
|---|
| 1535 | <p>Here's a simple example of using <tt class="docutils literal"><span class="pre">iu</span></tt> as a builtin import replacement.</p> |
|---|
| 1536 | <blockquote> |
|---|
| 1537 | <pre class="doctest-block"> |
|---|
| 1538 | >>> import iu |
|---|
| 1539 | >>> iu.ImportManager().install() |
|---|
| 1540 | >>> |
|---|
| 1541 | >>> import DateTime |
|---|
| 1542 | >>> DateTime.__importsub__ |
|---|
| 1543 | <method PathImportDirector.getmod |
|---|
| 1544 | of PathImportDirector instance at 825900> |
|---|
| 1545 | >>> |
|---|
| 1546 | </pre> |
|---|
| 1547 | </blockquote> |
|---|
| 1548 | <p><a class="reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p> |
|---|
| 1549 | </div> |
|---|
| 1550 | </div> |
|---|
| 1551 | </div> |
|---|
| 1552 | </div> |
|---|
| 1553 | <div class="footer"> |
|---|
| 1554 | <hr class="footer" /> |
|---|
| 1555 | <a class="reference" href="source/Manual.rst">View document source</a>. |
|---|
| 1556 | Generated on: 2006-02-08 14:02 UTC. |
|---|
| 1557 | Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source. |
|---|
| 1558 | |
|---|
| 1559 | </div> |
|---|
| 1560 | </body> |
|---|
| 1561 | </html> |
|---|
