mirror of
https://github.com/kennethreitz-archive/pyinstaller.git
synced 2026-06-05 23:50:17 +00:00
Changes to documentation and Licenses files. Documentation is not yet completed and validated as reST.
git-svn-id: http://svn.pyinstaller.org/trunk@26 8dd32b29-ccff-0310-8a9a-9233e24343b1
This commit is contained in:
williamcaban
+10
-8
@@ -1,7 +1,7 @@
|
||||
Installer version 5 beta 5
|
||||
PyInstaller version 1.0
|
||||
|
||||
Use:
|
||||
see doc/begin.html
|
||||
Use:
|
||||
see doc/Tutorial.txt
|
||||
|
||||
Installation in brief:
|
||||
|
||||
@@ -13,10 +13,12 @@ Non-Windows users should:
|
||||
Everyone should:
|
||||
python Configure.py
|
||||
|
||||
Now you're ready to use it!
|
||||
see Makespec in doc/begin.html
|
||||
python Makespec.py /path/to/yourscript.py /path/for/specfile.spec
|
||||
|
||||
python Build.py /path/for/specfile.spec
|
||||
|
||||
.done.
|
||||
|
||||
Major changes in this release:
|
||||
--onefile always creates a temporary directory (see doc/begin.html)
|
||||
- can use UPX if you have it installed
|
||||
- many bug fixes.
|
||||
* __write_changes_here__
|
||||
* many bug fixes.
|
||||
|
||||
+40
@@ -0,0 +1,40 @@
|
||||
#
|
||||
#
|
||||
|
||||
A NOTE ON PYINSTALLER LICENSE
|
||||
|
||||
The original base code of this software was licensed under the MIT license
|
||||
by McMillan Enterprises as presented at LICENSE.MCMILLAN. The current code
|
||||
is distributed under GPL as agreed by McMillan. NOW, THERE IS AN EXCEPTION
|
||||
that specifically apply to the bootloader and some runtime libraries the
|
||||
exception is as follows:
|
||||
|
||||
|
||||
=======================================================================
|
||||
GCC is free software; you can redistribute it and/or modify it under
|
||||
the terms of the GNU General Public License as published by the Free
|
||||
Software Foundation; either version 2, or (at your option) any later
|
||||
version.
|
||||
|
||||
In addition to the permissions in the GNU General Public License, the
|
||||
Copyright holders gives you unlimited permission to link the *compiled*
|
||||
version of this file into combinations with other programs,
|
||||
and to distribute *those combinations* without any restriction coming
|
||||
from the use of this file. (The General Public License restrictions
|
||||
*do apply* in other respects; for example, they cover modification of
|
||||
the file, and distribution when not linked into a combine executable.)
|
||||
|
||||
This code is distributed in the hope that it will be useful, but WITHOUT ANY
|
||||
WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
||||
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
||||
for more details.
|
||||
|
||||
You should have received a copy of the GNU General Public License
|
||||
along with GCC; see the file LICENSE.GPL.
|
||||
=======================================================================
|
||||
|
||||
|
||||
The rest of the code is GPL. For more information look at each file header.
|
||||
|
||||
#
|
||||
#
|
||||
+280
@@ -0,0 +1,280 @@
|
||||
GNU GENERAL PUBLIC LICENSE
|
||||
Version 2, June 1991
|
||||
|
||||
Copyright (C) 1989, 1991 Free Software Foundation, Inc.
|
||||
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
|
||||
Everyone is permitted to copy and distribute verbatim copies
|
||||
of this license document, but changing it is not allowed.
|
||||
|
||||
Preamble
|
||||
|
||||
The licenses for most software are designed to take away your
|
||||
freedom to share and change it. By contrast, the GNU General Public
|
||||
License is intended to guarantee your freedom to share and change free
|
||||
software--to make sure the software is free for all its users. This
|
||||
General Public License applies to most of the Free Software
|
||||
Foundation's software and to any other program whose authors commit to
|
||||
using it. (Some other Free Software Foundation software is covered by
|
||||
the GNU Library General Public License instead.) You can apply it to
|
||||
your programs, too.
|
||||
|
||||
When we speak of free software, we are referring to freedom, not
|
||||
price. Our General Public Licenses are designed to make sure that you
|
||||
have the freedom to distribute copies of free software (and charge for
|
||||
this service if you wish), that you receive source code or can get it
|
||||
if you want it, that you can change the software or use pieces of it
|
||||
in new free programs; and that you know you can do these things.
|
||||
|
||||
To protect your rights, we need to make restrictions that forbid
|
||||
anyone to deny you these rights or to ask you to surrender the rights.
|
||||
These restrictions translate to certain responsibilities for you if you
|
||||
distribute copies of the software, or if you modify it.
|
||||
|
||||
For example, if you distribute copies of such a program, whether
|
||||
gratis or for a fee, you must give the recipients all the rights that
|
||||
you have. You must make sure that they, too, receive or can get the
|
||||
source code. And you must show them these terms so they know their
|
||||
rights.
|
||||
|
||||
We protect your rights with two steps: (1) copyright the software, and
|
||||
(2) offer you this license which gives you legal permission to copy,
|
||||
distribute and/or modify the software.
|
||||
|
||||
Also, for each author's protection and ours, we want to make certain
|
||||
that everyone understands that there is no warranty for this free
|
||||
software. If the software is modified by someone else and passed on, we
|
||||
want its recipients to know that what they have is not the original, so
|
||||
that any problems introduced by others will not reflect on the original
|
||||
authors' reputations.
|
||||
|
||||
Finally, any free program is threatened constantly by software
|
||||
patents. We wish to avoid the danger that redistributors of a free
|
||||
program will individually obtain patent licenses, in effect making the
|
||||
program proprietary. To prevent this, we have made it clear that any
|
||||
patent must be licensed for everyone's free use or not licensed at all.
|
||||
|
||||
The precise terms and conditions for copying, distribution and
|
||||
modification follow.
|
||||
|
||||
GNU GENERAL PUBLIC LICENSE
|
||||
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
|
||||
|
||||
0. This License applies to any program or other work which contains
|
||||
a notice placed by the copyright holder saying it may be distributed
|
||||
under the terms of this General Public License. The "Program", below,
|
||||
refers to any such program or work, and a "work based on the Program"
|
||||
means either the Program or any derivative work under copyright law:
|
||||
that is to say, a work containing the Program or a portion of it,
|
||||
either verbatim or with modifications and/or translated into another
|
||||
language. (Hereinafter, translation is included without limitation in
|
||||
the term "modification".) Each licensee is addressed as "you".
|
||||
|
||||
Activities other than copying, distribution and modification are not
|
||||
covered by this License; they are outside its scope. The act of
|
||||
running the Program is not restricted, and the output from the Program
|
||||
is covered only if its contents constitute a work based on the
|
||||
Program (independent of having been made by running the Program).
|
||||
Whether that is true depends on what the Program does.
|
||||
|
||||
1. You may copy and distribute verbatim copies of the Program's
|
||||
source code as you receive it, in any medium, provided that you
|
||||
conspicuously and appropriately publish on each copy an appropriate
|
||||
copyright notice and disclaimer of warranty; keep intact all the
|
||||
notices that refer to this License and to the absence of any warranty;
|
||||
and give any other recipients of the Program a copy of this License
|
||||
along with the Program.
|
||||
|
||||
You may charge a fee for the physical act of transferring a copy, and
|
||||
you may at your option offer warranty protection in exchange for a fee.
|
||||
|
||||
2. You may modify your copy or copies of the Program or any portion
|
||||
of it, thus forming a work based on the Program, and copy and
|
||||
distribute such modifications or work under the terms of Section 1
|
||||
above, provided that you also meet all of these conditions:
|
||||
|
||||
a) You must cause the modified files to carry prominent notices
|
||||
stating that you changed the files and the date of any change.
|
||||
|
||||
b) You must cause any work that you distribute or publish, that in
|
||||
whole or in part contains or is derived from the Program or any
|
||||
part thereof, to be licensed as a whole at no charge to all third
|
||||
parties under the terms of this License.
|
||||
|
||||
c) If the modified program normally reads commands interactively
|
||||
when run, you must cause it, when started running for such
|
||||
interactive use in the most ordinary way, to print or display an
|
||||
announcement including an appropriate copyright notice and a
|
||||
notice that there is no warranty (or else, saying that you provide
|
||||
a warranty) and that users may redistribute the program under
|
||||
these conditions, and telling the user how to view a copy of this
|
||||
License. (Exception: if the Program itself is interactive but
|
||||
does not normally print such an announcement, your work based on
|
||||
the Program is not required to print an announcement.)
|
||||
|
||||
These requirements apply to the modified work as a whole. If
|
||||
identifiable sections of that work are not derived from the Program,
|
||||
and can be reasonably considered independent and separate works in
|
||||
themselves, then this License, and its terms, do not apply to those
|
||||
sections when you distribute them as separate works. But when you
|
||||
distribute the same sections as part of a whole which is a work based
|
||||
on the Program, the distribution of the whole must be on the terms of
|
||||
this License, whose permissions for other licensees extend to the
|
||||
entire whole, and thus to each and every part regardless of who wrote it.
|
||||
|
||||
Thus, it is not the intent of this section to claim rights or contest
|
||||
your rights to work written entirely by you; rather, the intent is to
|
||||
exercise the right to control the distribution of derivative or
|
||||
collective works based on the Program.
|
||||
|
||||
In addition, mere aggregation of another work not based on the Program
|
||||
with the Program (or with a work based on the Program) on a volume of
|
||||
a storage or distribution medium does not bring the other work under
|
||||
the scope of this License.
|
||||
|
||||
3. You may copy and distribute the Program (or a work based on it,
|
||||
under Section 2) in object code or executable form under the terms of
|
||||
Sections 1 and 2 above provided that you also do one of the following:
|
||||
|
||||
a) Accompany it with the complete corresponding machine-readable
|
||||
source code, which must be distributed under the terms of Sections
|
||||
1 and 2 above on a medium customarily used for software interchange; or,
|
||||
|
||||
b) Accompany it with a written offer, valid for at least three
|
||||
years, to give any third party, for a charge no more than your
|
||||
cost of physically performing source distribution, a complete
|
||||
machine-readable copy of the corresponding source code, to be
|
||||
distributed under the terms of Sections 1 and 2 above on a medium
|
||||
customarily used for software interchange; or,
|
||||
|
||||
c) Accompany it with the information you received as to the offer
|
||||
to distribute corresponding source code. (This alternative is
|
||||
allowed only for noncommercial distribution and only if you
|
||||
received the program in object code or executable form with such
|
||||
an offer, in accord with Subsection b above.)
|
||||
|
||||
The source code for a work means the preferred form of the work for
|
||||
making modifications to it. For an executable work, complete source
|
||||
code means all the source code for all modules it contains, plus any
|
||||
associated interface definition files, plus the scripts used to
|
||||
control compilation and installation of the executable. However, as a
|
||||
special exception, the source code distributed need not include
|
||||
anything that is normally distributed (in either source or binary
|
||||
form) with the major components (compiler, kernel, and so on) of the
|
||||
operating system on which the executable runs, unless that component
|
||||
itself accompanies the executable.
|
||||
|
||||
If distribution of executable or object code is made by offering
|
||||
access to copy from a designated place, then offering equivalent
|
||||
access to copy the source code from the same place counts as
|
||||
distribution of the source code, even though third parties are not
|
||||
compelled to copy the source along with the object code.
|
||||
|
||||
4. You may not copy, modify, sublicense, or distribute the Program
|
||||
except as expressly provided under this License. Any attempt
|
||||
otherwise to copy, modify, sublicense or distribute the Program is
|
||||
void, and will automatically terminate your rights under this License.
|
||||
However, parties who have received copies, or rights, from you under
|
||||
this License will not have their licenses terminated so long as such
|
||||
parties remain in full compliance.
|
||||
|
||||
5. You are not required to accept this License, since you have not
|
||||
signed it. However, nothing else grants you permission to modify or
|
||||
distribute the Program or its derivative works. These actions are
|
||||
prohibited by law if you do not accept this License. Therefore, by
|
||||
modifying or distributing the Program (or any work based on the
|
||||
Program), you indicate your acceptance of this License to do so, and
|
||||
all its terms and conditions for copying, distributing or modifying
|
||||
the Program or works based on it.
|
||||
|
||||
6. Each time you redistribute the Program (or any work based on the
|
||||
Program), the recipient automatically receives a license from the
|
||||
original licensor to copy, distribute or modify the Program subject to
|
||||
these terms and conditions. You may not impose any further
|
||||
restrictions on the recipients' exercise of the rights granted herein.
|
||||
You are not responsible for enforcing compliance by third parties to
|
||||
this License.
|
||||
|
||||
7. If, as a consequence of a court judgment or allegation of patent
|
||||
infringement or for any other reason (not limited to patent issues),
|
||||
conditions are imposed on you (whether by court order, agreement or
|
||||
otherwise) that contradict the conditions of this License, they do not
|
||||
excuse you from the conditions of this License. If you cannot
|
||||
distribute so as to satisfy simultaneously your obligations under this
|
||||
License and any other pertinent obligations, then as a consequence you
|
||||
may not distribute the Program at all. For example, if a patent
|
||||
license would not permit royalty-free redistribution of the Program by
|
||||
all those who receive copies directly or indirectly through you, then
|
||||
the only way you could satisfy both it and this License would be to
|
||||
refrain entirely from distribution of the Program.
|
||||
|
||||
If any portion of this section is held invalid or unenforceable under
|
||||
any particular circumstance, the balance of the section is intended to
|
||||
apply and the section as a whole is intended to apply in other
|
||||
circumstances.
|
||||
|
||||
It is not the purpose of this section to induce you to infringe any
|
||||
patents or other property right claims or to contest validity of any
|
||||
such claims; this section has the sole purpose of protecting the
|
||||
integrity of the free software distribution system, which is
|
||||
implemented by public license practices. Many people have made
|
||||
generous contributions to the wide range of software distributed
|
||||
through that system in reliance on consistent application of that
|
||||
system; it is up to the author/donor to decide if he or she is willing
|
||||
to distribute software through any other system and a licensee cannot
|
||||
impose that choice.
|
||||
|
||||
This section is intended to make thoroughly clear what is believed to
|
||||
be a consequence of the rest of this License.
|
||||
|
||||
8. If the distribution and/or use of the Program is restricted in
|
||||
certain countries either by patents or by copyrighted interfaces, the
|
||||
original copyright holder who places the Program under this License
|
||||
may add an explicit geographical distribution limitation excluding
|
||||
those countries, so that distribution is permitted only in or among
|
||||
countries not thus excluded. In such case, this License incorporates
|
||||
the limitation as if written in the body of this License.
|
||||
|
||||
9. The Free Software Foundation may publish revised and/or new versions
|
||||
of the General Public License from time to time. Such new versions will
|
||||
be similar in spirit to the present version, but may differ in detail to
|
||||
address new problems or concerns.
|
||||
|
||||
Each version is given a distinguishing version number. If the Program
|
||||
specifies a version number of this License which applies to it and "any
|
||||
later version", you have the option of following the terms and conditions
|
||||
either of that version or of any later version published by the Free
|
||||
Software Foundation. If the Program does not specify a version number of
|
||||
this License, you may choose any version ever published by the Free Software
|
||||
Foundation.
|
||||
|
||||
10. If you wish to incorporate parts of the Program into other free
|
||||
programs whose distribution conditions are different, write to the author
|
||||
to ask for permission. For software which is copyrighted by the Free
|
||||
Software Foundation, write to the Free Software Foundation; we sometimes
|
||||
make exceptions for this. Our decision will be guided by the two goals
|
||||
of preserving the free status of all derivatives of our free software and
|
||||
of promoting the sharing and reuse of software generally.
|
||||
|
||||
NO WARRANTY
|
||||
|
||||
11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
|
||||
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
|
||||
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
|
||||
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
|
||||
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
|
||||
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
|
||||
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
|
||||
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
|
||||
REPAIR OR CORRECTION.
|
||||
|
||||
12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
|
||||
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
|
||||
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
|
||||
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
|
||||
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
|
||||
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
|
||||
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
|
||||
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
|
||||
POSSIBILITY OF SUCH DAMAGES.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
@@ -1,36 +0,0 @@
|
||||
<HTML>
|
||||
<HEAD>
|
||||
<TITLE>
|
||||
Python Archives
|
||||
</TITLE>
|
||||
|
||||
</HEAD>
|
||||
|
||||
<BODY>
|
||||
<FONT FACE="Helvetica"><TABLE CELLPADDING=5 CELLSPACING=5>
|
||||
<TR ALIGN="center">
|
||||
<TD COLSPAN=2><IMG SRC="me_inc.gif" HEIGHT=36 WIDTH=480><HR></TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VALIGN="top" NOWRAP BGCOLOR="#D8D0F0"><H4>Sitemap</H4><SMALL><A HREF="begin.html">Getting Started</A><BR><A HREF="utilities.html">Utilities</A><BR><A HREF="specfiles.html">Spec Files</A><BR><A HREF="help.html">When Things Go Wrong</A><BR><A HREF="standalones.html">Standalone Executables</A><BR>Python Archives<BR><A HREF="mf4.html">Analyzing Python Modules</A><BR><A HREF="iu4.html">An Import Framework</A><BR><BR><a href="http://www.mcmillan-inc.com/cgi-bin/BTSCGI.py/BTS/">Bug Tracker</a><BR></SMALL></TD>
|
||||
<TD ROWSPAN=2><P><h2>Archives</h2></P>
|
||||
<P>You know what an archive is: a .tar file, a .jar file, a .zip file. Two kinds of archives are used here. One is equivalent to a Java .jar file - it allows Python modules to be stored efficiently and, (with some import hooks) imported directly. This is a <i>ZlibArchive</i>. The other (a <i>CArchive</i>) is equivalent to a .zip file - a general way of packing up (and optionally compressing) arbitrary blobs of data. It gets its name from the fact that it can be manipulated easily from C, as well as from Python. Both of these derive from a common base class, making it fairly easy to create new kinds of archives.</P>
|
||||
<P><h3>ZlibArchive</h3></P>
|
||||
<P>A ZlibArchive contains compressed .pyc (or .pyo) files. The Table of Contents is a marshalled dictionary, with the key (the module's name as given in an "import" statement) associated with a seek position and length. Because it is all marshaled Python, ZlibArchives are completely cross-platform.</P>
|
||||
<P>A ZlibArchive hooks in with <A HREF="iu4.html">iu.py</A> so that, with a little setup, the archived modules can be imported transparently. Even with compression at level 9, this works out to being faster than the normal import. Instead of searching sys.path, there's a lookup in the dictionary. There's no stat-ing of the .py and .pyc and no file opens (the file is already open). There's just a seek, a read and a decompress. A traceback will point to the source file the archive entry was created from (the __file__ attribute from the time the .pyc was compiled). On a user's box with no source installed, this is not terribly useful, but if they send you the traceback, at least you can make sense of it.
|
||||
<img src="ZlibArchive.gif" ></P>
|
||||
<P><h3>CArchive</h3></P>
|
||||
<P><img src="CArchive.gif"></P>
|
||||
<P>A CArchive contains whatever you want to stuff into it. It's very much like a .zip file. They are easy to create in Python and unpack from C code. CArchives can be appended to other files (like ELF and COFF executables, for example). To allow this, they are opened from the end, so the TOC for a CArchive is at the back, followed only by a cookie that tells you where the TOC starts and where the archive itself starts. </P>
|
||||
<P>CArchives can also be embedded within other CArchives. The inner archive can be opened in place (without extraction).</P>
|
||||
<P>Each TOC entry is variable length. The first field in the entry tells you the length of the entry. The last field is the name of the corresponding packed file. The name is null terminated. Compression is optional by member.</P>
|
||||
<P>There is also a type code associated with each entry. If you're using a CArchive as a .zip file, you don't need to worry about this. The type codes are used by the <A HREF="standalones.html">self-extracting executables</a>.
|
||||
</P>
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VALIGN="bottom" BGCOLOR="#D8D0F0"><SMALL>copyright 1999-2002<BR>McMillan Enterprises, Inc.<BR></SMALL></TD>
|
||||
</TR>
|
||||
</TABLE></FONT>
|
||||
</BODY>
|
||||
</HTML>
|
||||
-149
@@ -1,149 +0,0 @@
|
||||
<HTML>
|
||||
<HEAD>
|
||||
<TITLE>
|
||||
Getting Started
|
||||
</TITLE>
|
||||
|
||||
</HEAD>
|
||||
|
||||
<BODY>
|
||||
<FONT FACE="Helvetica"><TABLE CELLPADDING=5 CELLSPACING=5>
|
||||
<TR ALIGN="center">
|
||||
<TD COLSPAN=2><IMG SRC="me_inc.gif" HEIGHT=36 WIDTH=480><HR></TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VALIGN="top" NOWRAP BGCOLOR="#D8D0F0"><H4>Sitemap</H4><SMALL>Getting Started<BR><A HREF="utilities.html">Utilities</A><BR><A HREF="specfiles.html">Spec Files</A><BR><A HREF="help.html">When Things Go Wrong</A><BR><A HREF="standalones.html">Standalone Executables</A><BR><A HREF="archives.html">Python Archives</A><BR><A HREF="mf4.html">Analyzing Python Modules</A><BR><A HREF="iu4.html">An Import Framework</A><BR><BR><a href="http://www.mcmillan-inc.com/cgi-bin/BTSCGI.py/BTS/">Bug Tracker</a><BR></SMALL></TD>
|
||||
<TD ROWSPAN=2><P><h1>Getting Started</h1></P>
|
||||
<P>Contents:<br>
|
||||
<ul>
|
||||
<li><a href="#step0">Installing</a></li>
|
||||
<li><a href="#step1">Building the runtime executables</a> (on non-Windows)</li>
|
||||
<li><a href="#step2">Configuring your Installer setup</a></li>
|
||||
<li><a href="#step3">Create a spec file for your project</a></li>
|
||||
<li><a href="#step4">Build your project</a></li>
|
||||
<li><a href="#comserver">Windows COM Server support</a></li>
|
||||
<li><a href="#optimized">Building Optimized</a></li>
|
||||
<li><a href="#upx">A Note on using UPX</a></li>
|
||||
<li><a href="#onefile">A Note on --onefile</a></li>
|
||||
<li><a href="#sponsor">Sponsorship</a></li>
|
||||
<li><a href="#license">License</a></li>
|
||||
<li><a href="#reportingbugs">Reporting Bugs</a></li>
|
||||
</ul>
|
||||
|
||||
<a name="step0"><h2>Installing Installer</h2></a></P>
|
||||
<P>First, unpack the archive <b>wherever you want to</b>. Installer is not a Python package, so it doesn't need to go in <code>site-packages</code>, or have a <code>.pth</code> file. You will be using a couple of scripts in the root directory, and these will find everything they need from their own location. Since you will be running a couple scripts, you might want to keep the paths to these scripts short (don't install in a deeply nested subdirectory).</P>
|
||||
<P>You <b>will</b> need a separate copy for each Python version you wish to work with (or you'll need to rerun
|
||||
<code>Configure.py</code> every time you switch).</P>
|
||||
<P><a name="step1"><h2>I - Building the runtime executables</h2></a></P>
|
||||
<P>Windows users can skip this step, because all of Python is contained in pythonXX.dll, and Installer will use your pythonXX.dll.</P>
|
||||
<P>On non-Windows platforms, the first thing to do is build the runtime executables. </P>
|
||||
<P>Change to the <code>source/linux</code> subdirectory. Run <code>Make.py [-n|-e]</code> and then <code>make</code>. This will produce <code>support/run</code> and <code>support/run_d</code>. If you have multiple versions of Python, the Python you use to run <code>Make.py</code> is the one whose configuration is used.</P>
|
||||
<P><font size=-1>
|
||||
The <code>-n</code> and <code>-e</code> options set a <b>n</b>on-elf or <b>e</b>lf flag in your config.dat. As of 5b5, the executable will try both strategies, and this flag just sets how you want your executables built. In the <b>elf</b> strategy, the archive is concatenated to the executable. In the <b>non-elf</b> strategy, the executable expects an archive with the same name as itself in the executable's directory. Note that the executable chases down symbolic links before determining it's name and directory, so putting the archive in the same directory as the symbolic link will not work.</P>
|
||||
<P>Windows distributions come with four executables in the <code>support</code> dir: run.exe, run_d.exe, runw.exe and runw_d.exe. There are also two dlls, inprocsrvr.dll and inprocsrvr_d.dll for doing in-process COM servers. All of these can be rebuilt from the MSVC workspace in <code>source/windows</code>. Please be careful of MS's optimizations - I suggest you disable them in the release builds. (I'm fairly sure these could be built using MinGW, too, but I haven't yet tried it).</P>
|
||||
<P>Note that the <code>_d</code> suffix does not mean the same as it does with extension modules - you don't need a debug build of Python to use them.
|
||||
</font></P>
|
||||
<P><a name="step2"><h2>II - Configuring your Installer setup</h2></a></P>
|
||||
<P>In the root directory, run <code>Configure.py</code>. This saves some information into <code>config.dat</code> that would otherwise be recomputed every time. It can be rerun at any time if your configuration changes. It must be run before trying to build anything.</P>
|
||||
<P><a name="step3"><h2>III - Create a spec file for your project</h2></a></P>
|
||||
<P>[For Windows COM server support, see <a href="#comserver">below</a>.]</P>
|
||||
<P>The root directory has a script <code>Makespec.py</code> for this purpose.
|
||||
<code><pre>
|
||||
>python Makespec.py [OPTIONS] script...
|
||||
</pre></code>
|
||||
Where allowed options are:
|
||||
<dl>
|
||||
<dt>--onefile<dd>produce a single file deployment (see <a href="#onefile">below</a>).
|
||||
<dt>--onedir<dd>produce a single directory deployment (default).
|
||||
<dt>--tk<dd>include TCL/TK in the deployment.
|
||||
<dt>--ascii<dd>do <b>not</b> include encodings. The default (on Python versions with unicode support) is now to include all encodings.
|
||||
<dt>--debug<dd>use debug (verbose) versions of the executables.
|
||||
<dt>--noconsole<dd>Windows: use the Windows subsystem executable (runw.exe or runw_d.exe).
|
||||
<dt>--strip<dd>the executable and all shared libraries will be run through <code>strip</code>. Note that cygwin's <code>strip</code> tends to render normal Win32 dlls unusable.
|
||||
<dt>--upx<dd>if you have <a href="http://upx.sourceforge.net/">UPX</a> installed (detected by Configure), this will use it to compress your executable (and, on Windows, your dlls). See note <a href="#upx">below</a>.
|
||||
<dt>--out <i>directory</i><dd>create the spec file in <i>directory</i>. If not specified, and the current directory is Installer's root directory, an output subdirectory will be created. Otherwise the current directory is used.
|
||||
<dt>--icon <i>file.ico</i><dd>add <i>file.ico</i> to the executable's resources (Windows only).
|
||||
<dt>--icon <i>file.exe,n</i><dd>add the <i>n</i>th incon in <i>file.exe</i> to the executable's resources (Windows only).
|
||||
<dt>--version <i>verfile</i><dd>add <i>verfile</i> as a version resource to the executable (Windows only).
|
||||
<dt>--name <i>name</i><dd>optional name to assign to the project (from which the spec file name is generated). If omitted, the basename of the (first) script is used.
|
||||
</dl>
|
||||
|
||||
[For building with optimization on (like <code>Python -O</code>), see <a href="#optimized">below</a>.]</P>
|
||||
<P>For simple projects, the generated spec file will probably be sufficient. For more complex projects, it should be regarded as a template. The spec file is actually Python code, and modifying it should be <b>much</b> easier than working with the config files used in earlier Installer releases. See <A HREF="specfiles.html">Spec Files</A> for details.</P>
|
||||
<P><a name="step4"><h2>IV - Build your project</h2></a></P>
|
||||
<P><code><pre>
|
||||
>python Build.py <i>specfile</i>
|
||||
</pre></code>
|
||||
A <code>build<i>project</i></code> subdirectory will be created in the <i>specfile</i>'s directory. This is a <b>private workspace</b> so that <code>Build</code> can act like a makefile. Any named targets will appear in the specfile's directory. For --onedir configurations, that include <b><code>dist<i>project</i></code></b>, which is the directory you're interested in. For a --onefile, the executable will be in the specfile's directory.</P>
|
||||
<P>In most cases, this will be all you have to do. If not, see <A HREF="help.html">When things go wrong</A> and be sure to read the introduction to <A HREF="specfiles.html">Spec Files</A>.</P>
|
||||
<P><a name="comserver"><h2>Windows COM Server support</h2></a></P>
|
||||
<P><pre><code>
|
||||
>python MakeCOMServer.py [OPTION] script...
|
||||
</code></pre>
|
||||
will generate a new script <code>drive<i>script</i>.py</code> and a spec file for the script.</P>
|
||||
<P>[For Win32all builds before 151, use <code>MakeCOMServer_old.py</code>.]</P>
|
||||
<P>These options are allowed:
|
||||
<dl>
|
||||
<dt>--debug<dd>Use the verbose version of the executable.
|
||||
<dt>--verbose<dd>Register the COM server(s) with the quiet flag off.
|
||||
<dt>--ascii<dd>do <b>not</b> include encodings (this is passed through to Makespec).
|
||||
<dt>--out <i>dir</i><dd>Generate the driver script and spec file in <i>dir</i>.
|
||||
</dl></P>
|
||||
<P>Now run <code>Build.py</code> on the generated spec file. </P>
|
||||
<P>If you have the <code>win32dbg</code> package installed, you can use it with the generated COM server. In the driver script, set <code>debug=1</code> in the registration line.</P>
|
||||
<P><b>Warnings</b>: the inprocess COM server support will <b>not</b> work when the client process already has Python loaded. It would be rather tricky to non-obtrusively hook into an already running Python, but the show-stopper is that the Python/C API won't let me find out which interpreter instance I should hook into. (If this is important to you, you might experiment with using apartment threading, which seems the best possibility to get this to work).
|
||||
To use a "frozen" COM server from a Python process, you'll have to load it as an exe:
|
||||
<code><pre>
|
||||
o = win32com.client.Dispatch(<i>progid</i>,
|
||||
clsctx=pythoncom.CLSCTX_LOCAL_SERVER)
|
||||
</pre></code></P>
|
||||
<P>MakeCOMServer also assumes that your top level code (registration etc.) is "normal". If it's not, you will have to edit the generated script.</P>
|
||||
<P><a name="optimized"><h2>Building Optimized</h2></a></P>
|
||||
<P>There are two facets to running optimized: gathering <code>.pyo</code>'s, and setting the <code>Py_OptimizeFlag</code>. Installer will gather <code>.pyo</code>'s if it is run optimized:
|
||||
<code><pre>
|
||||
>python -O Build.py ...
|
||||
</pre></code></P>
|
||||
<P>The <code>Py_OptimizeFlag</code> will be set if you use a <code>('O','','OPTION')</code> in one of the <code>TOC</code>s building the <code>EXE</code>.
|
||||
<code><pre>
|
||||
exe = EXE(pyz,
|
||||
a.scripts + [('O','','OPTION')],
|
||||
...
|
||||
</pre></code></P>
|
||||
<P>See <A HREF="specfiles.html">Spec Files</A> for details.</P>
|
||||
<P><a name="upx"><h2>A Note on using UPX</h2></a></P>
|
||||
<P>On both Windows and Linux, UPX can give truly startling compression - the days of fitting something useful on a diskette are not gone forever! Installer has been tested with UPX 1.24 without problems. Just <a href="http://upx.sourceforge.net/">get it</a> and install it on your PATH, then rerun configure. For Windows, that's all you need to know.</P>
|
||||
<P>For Linux, a bit more discussion is in order. First, UPX is only useful on executables, not shared libs. Installer accounts for that, but to get the full benefit, you might rebuild Python with more things statically linked.</P>
|
||||
<P>More importantly, when run finds that it's sys.argv[0] does <b>not</b> contain a path, it will use <code>/proc/<i>pid</i>/exe</code> to find itself (if it can). This happens, for example, when executed by Apache. If it has been upx-ed, this symbolic link points to the tempfile created by the upx stub and Installer will fail (please see the UPX docs for more information). So for now, at least, you can't use upx for CGI's executed by Apache. Otherwise, you can ignore the warnings in the UPX docs, since what Installer opens is the executable Installer created, not the temporary upx-created executable.</P>
|
||||
<P><a name="onefile"><h2>A Note on --onefile</h2></a></P>
|
||||
<P>A <code>--onefile</code> works by packing all the shared libs / dlls into the archive attached to the executable (or next to the executable in a nonelf configuration). When first started, it finds that it needs to extract these files before it can run "for real". That's because locating and loading a shared lib or linked-in dll is a system level action, not user-level. Before 5b5, a --onefile would extract into the executable's directory (if possible). With 5b5 it now <b>always</b> uses a temporary directory (<code>_MEI<i>pid</i></code>) in the user's temp directory. It then executes itself again, setting things up so the system will be able to load the shared libs / dlls. When executing is complete, it recursively removes the entire directory it created.</P>
|
||||
<P>This has a number of implications.
|
||||
<ul>
|
||||
<li>You can run multiple copies - they won't collide.
|
||||
<li>Running multiple copies will be rather expensive to the system (nothing is shared).
|
||||
<li>If you're using the cheat of adding user data as 'BINARY', it will be in <code>os.environ['_MEIPASS2']</code>, not the executable's directory.
|
||||
<li>On Windows, using Task Manager to kill the parent process will leave the directory behind.
|
||||
<li>On *nix, a kill -9 (or crash) will leave the directory behind.
|
||||
<li>Otherwise, on both platforms, the directory will be recursively deleted.
|
||||
<li>So any files you might create in <code>os.environ['_MEIPASS2']</code> will be deleted.
|
||||
<li>The executable can be in a protected or read-only directory.
|
||||
</ul></P>
|
||||
<P>While I am not a security expert, I believe the scheme is reasonably safe. If for some reason, the <code>_MEI<i>pid</i></code> directory already exists, the executable will fail. It is created mode <code>0700</code>, so only the one user can modify it (on *nix, of course). If the executable does a setuid root, a determined hacker could possibly (given enough tries) introduce a malicious lookalike of one of the shared libraries during the hole between when the library is extracted and when it gets loaded by the execvp'd process. So maybe you shouldn't do setuid root programs using --onefile.</P>
|
||||
<P><a name="sponsor"><h3>Sponsorship</h3></a></P>
|
||||
<P><b>Please</b> show your appreciation and help fund continued development of Installer by
|
||||
making a <a href="http://www.mcmillan-inc.com/sponsor.html">contribution</a>. To date, the contributions I have received amount to a tiny bit more than I pay for the hosting of this site for one month. If Installer is contributing
|
||||
to your commercial success, please let your conscience be your guide. I really do not want to go to a dual-licensed model.</P>
|
||||
<P><a name="license"><h3>License</h3></a></P>
|
||||
<P>This code is licensed under the MIT license. Please see <a href="license.txt">license.txt</a>. Note that I do
|
||||
<b>not</b> consider that Installer includes significant portions of itself in the executables it produces, so I make no restrictions on their licensing.</P>
|
||||
<P><a name="reportingbugs"><h3>Reporting Bugs</h3></a></P>
|
||||
<P>Report bugs (or feature requests, or send patches) <a href="/cgi-bin/BTSCGI.py/BTS/">here</a>. Please make sure you set <b>Product</b> to <code>Installer</code>. (If you choose not to become a registered user, please include some contact information in the report itself.) The bug tracker does <b>not</b> send out email, and email addresses are obsfucated in the user list. </P>
|
||||
<P>Subscribe to the Installer <a href="http://trixie.triqs.com/mailman/listinfo/installer">Mailing List</a> to discuss Installer related issues. Having been discovered by the SPAM monsters, you now need to join before you can post (it is a low volume list).
|
||||
</P>
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VALIGN="bottom" BGCOLOR="#D8D0F0"><SMALL>copyright 1999-2002<BR>McMillan Enterprises, Inc.<BR></SMALL></TD>
|
||||
</TR>
|
||||
</TABLE></FONT>
|
||||
</BODY>
|
||||
</HTML>
|
||||
-143
@@ -1,143 +0,0 @@
|
||||
<HTML>
|
||||
<HEAD>
|
||||
<TITLE>
|
||||
When Things Go Wrong
|
||||
</TITLE>
|
||||
|
||||
</HEAD>
|
||||
|
||||
<BODY>
|
||||
<FONT FACE="Helvetica"><TABLE CELLPADDING=5 CELLSPACING=5>
|
||||
<TR ALIGN="center">
|
||||
<TD COLSPAN=2><IMG SRC="me_inc.gif" HEIGHT=36 WIDTH=480><HR></TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VALIGN="top" NOWRAP BGCOLOR="#D8D0F0"><H4>Sitemap</H4><SMALL><A HREF="begin.html">Getting Started</A><BR><A HREF="utilities.html">Utilities</A><BR><A HREF="specfiles.html">Spec Files</A><BR>When Things Go Wrong<BR><A HREF="standalones.html">Standalone Executables</A><BR><A HREF="archives.html">Python Archives</A><BR><A HREF="mf4.html">Analyzing Python Modules</A><BR><A HREF="iu4.html">An Import Framework</A><BR><BR><a href="http://www.mcmillan-inc.com/cgi-bin/BTSCGI.py/BTS/">Bug Tracker</a><BR></SMALL></TD>
|
||||
<TD ROWSPAN=2><P><h1>When Things Go Wrong</h1></P>
|
||||
<P><h4>Contents</h4>
|
||||
<ul>
|
||||
<li><a href="#start">Finding out What Went Wrong</a></li>
|
||||
<ul>
|
||||
<li><a href="#warnings">Buildtime Warnings</a></li>
|
||||
<li><a href="#run_d">Getting Debug Messages</a></li>
|
||||
<li><a href="#verboseimport">Getting Python's Verbose Imports</a></li>
|
||||
</ul>
|
||||
<li><a href="#finding">Helping Installer Find Modules</a></li>
|
||||
<ul>
|
||||
<li><a href="#syspath">Extending the Path</a></li>
|
||||
<li><a href="#hooks">Listing Hidden Imports</a></li>
|
||||
<li><a href="#__path__">Extending a Package's __path__</a></li>
|
||||
<li><a href="#rthooks">Changing Runtime Behavior</a></li>
|
||||
<li><a href="#sysfrozen">Adapting to being "frozen"</a></li>
|
||||
</ul>
|
||||
<li><a href="#datafiles">Accessing Data Files</a></li>
|
||||
<li><a href="#reporting">Reporting Bugs</a></li>
|
||||
<li><a href="#misc">Miscellaneous</a></li>
|
||||
<ul>
|
||||
<li><a href="#pmw">Pmw</a></li>
|
||||
<li><a href="#win9xpopen">Win9xpopen</a></li>
|
||||
</ul>
|
||||
</ul></P>
|
||||
<P><a name="#start"><h2>Finding out What Went Wrong</h2></a></P>
|
||||
<P> <a name="warnings"><h3>Buildtime Warnings</h3></a></P>
|
||||
<P>When an Analysis step runs, it produces a warnings file (named <code>warn<i>project</i>.txt</code>) in the spec file's directory. Generally, most of these warnings are harmless. For example, <code>os.py</code> (which is cross-platform) works by figuring out what platform it is on, then importing (and rebinding names from) the appropriate platform-specific module. So analyzing <code>os.py</code> will produce a set of warnings like:
|
||||
<pre>
|
||||
W: no module named dos (conditional import by os)
|
||||
W: no module named ce (conditional import by os)
|
||||
W: no module named os2 (conditional import by os)
|
||||
</pre>
|
||||
Note that the analysis has detected that the import is within a conditional block (an <code>if</code> statement). The analysis also detects if an import within a function or class, (delayed) or at the top level. A top-level, non-conditional import failure is really a hard error. There's at least a reasonable chance that conditional and / or delayed import will be handled gracefully at runtime.</P>
|
||||
<P>Ignorable warnings may also be produced when a class or function is declared in a package (an <code>__init__.py</code> module), and the import specifies <i>package.name</i>. In this case, the analysis can't tell if <i>name</i> is supposed to refer to a submodule of <i>package</i>.</P>
|
||||
<P>Warnings are also produced when an <code>__import__</code>, <code>exec</code> or <code>eval</code> statement is encountered. The <code>__import__</code> warnings should almost certainly be investigated. Both <code>exec</code> and <code>eval</code> can be used to implement import hacks, but usually their use is more benign.</P>
|
||||
<P>Any problem detected here can be handled by hooking the analysis of the module. See <a href="#hooks">Listing Hidden Imports</a> below for how to do it.</P>
|
||||
<P> <a name="run_d"><h3>Getting Debug Messages</h3></a></P>
|
||||
<P>Setting <code>debug=1</code> on an <code>EXE</code> will cause the executable to put out progress messages (for console apps, these go to <code>stdout</code>; for Windows apps, these show as <code>MessageBox</code>es). This can be useful if you are doing complex packaging, or your app doesn't seem to be starting, or just to learn how the runtime works.</P>
|
||||
<P><a name="verboseimport"> <h3>Getting Python's Verbose Imports</h3> </a></P>
|
||||
<P>You can also pass a <b>-v</b> (verbose imports) flag to the embedded Python. This can be extremely useful. I usually try it even on apparently working apps, just to make sure that I'm always getting my copies of the modules and no import has leaked out to the installed Python.</P>
|
||||
<P>You set this (like the other runtime options) by feeding a phone TOC entry to the EXE. The easiest way to do this is to change the EXE from:
|
||||
<pre><code>
|
||||
EXE(..., anal.scripts, ....)
|
||||
</code>to<code>
|
||||
EXE(..., anal.scripts + [('v', '', 'OPTION')], ...)
|
||||
</code></pre></P>
|
||||
<P>These messages will always go to stdout, so you won't see them on Windows if <code>console=0</code>.
|
||||
|
||||
<a name="finding"><h2>Helping Installer Find Modules</h2></a></P>
|
||||
<P> <a name="syspath"><h3>Extending the Path</h3></a></P>
|
||||
<P>When the analysis phase cannot find needed modules, it may be that the code is manipulating <code>sys.path</code>. The easiest thing to do in this case is tell Analysis about the new directory through the second arg to the constructor.
|
||||
<code><pre>
|
||||
anal = Analysis(['somedir/myscript.py'],
|
||||
['path/to/thisdir', 'path/to/thatdir'])
|
||||
</pre></code>
|
||||
In this case, the Analysis will have a search path:
|
||||
<code><pre>
|
||||
['somedir', 'path/to/thisdir', 'path/to/thatdir'] + sys.path
|
||||
</pre></code></P>
|
||||
<P>You can do the same when running <code>Makespec</code by using
|
||||
<code><pre>
|
||||
Makespec.py --paths=path/to/thisdir;path/to/thatdir ...
|
||||
</pre></code>
|
||||
(on *nix, use <code>:</code> as the path separator).</P>
|
||||
<P><a name="hooks"> <h3>Listing Hidden Imports</h3> </a></P>
|
||||
<P>Hidden imports are fairly common. These can occur when the code is using <code>__import__</code> (or, perhaps <code>exec</code> or <code>eval</code>), in which case you will see a warning in the <code>warn<i>project</i>.txt</code> file. They can also occur when an extension module uses the Python/C API to do an import, in which case Analysis can't detect anything. You can verify that hidden import is the problem by using Python's <a href="#verboseimport">verbose</a> imports flag. If the import messages say "module not found", but the <code>warn<i>project</i>.txt</code> file has no "no module named..." message for the same module, then the problem is a hidden import.</P>
|
||||
<P>Hidden imports are handled by hooking the module (the one doing the hidden imports) at Analysis time. Do this by creating a file named <code>hook-<i>module</i>.py</code> (where <i>module</i> is the fully-qualified Python name, eg, <code>hook-xml.dom.py</code>), and placing it in the <code>hooks</code> package under Installer's root directory, (alternatively, you can save it elsewhere, and then use the <code>hookspath</code> arg to <code>Analysis</code> so your private hooks directory will be searched). Normally, it will have only one line:
|
||||
<code><pre>
|
||||
hiddenimports = ['module1', 'module2']
|
||||
</pre></code>
|
||||
When the Analysis finds this file, it will proceed exactly as though the module explicitly imported <code>module1</code> and <code>module2</code>. (Full details on the analysis-time hook mechanism is <A HREF="mf4.html">here</A>).</P>
|
||||
<P>If you successfully hook a publicly distributed module in this way, please send me the hook so I can make it available to others.</P>
|
||||
<P> <a name="__path__"><h3>Extending a Package's __path__</h3></a></P>
|
||||
<P>Python allows a package to extend the search path used to find modules and sub-packages through the <code>__path__</code> mechanism. Normally, a package's <code>__path__</code> has only one entry - the directory in which the <code>__init__.py</code> was found. But <code>__init__.py</code> is free to extend its <code>__path__</code> to include other directories. For example, the <code>win32com.shell.shell</code> module actually resolves to <code>win32com/win32comext/shell/shell.pyd</code>. This is because <code>win32com/__init__.py</code> appends <code>../win32comext</code> to its <code>__path__</code>.</P>
|
||||
<P>Because the <code>__init__.py</code> is not actually run during an analysis, we use the same hook mechanism we use for hiddenimports. A static list of names won't do, however, because the new entry on <code>__path__</code> may well require computation. So <code>hook-<i>module</i>.py</code> should define a method <code>hook(mod)</code>. The <code>mod</code> argument is an instance of <code>mf.Module</code> which has (more or less) the same attributes as a real <code>module</code> object. The <code>hook</code> function should return a <code>mf.Module</code> instance - perhaps a brand new one, but more likely the same one used as an arg, but mutated. See <A HREF="mf4.html">mf</A> for details, and <code>hook/hook-win32com.py</code> for an example.</P>
|
||||
<P>Note that manipulations of <code>__path__</code> hooked in this way apply to the analysis, and only the analysis. That is, at runtime <code>win32com.shell</code> is resolved the same way as <code>win32com.<i>anythingelse</i></code>, and <code>win32com.__path__</code> knows nothing of <code>../win32comext</code>.</P>
|
||||
<P>Once in awhile, that's not enough.</P>
|
||||
<P> <a name="rthooks"><h3>Changing Runtime Behavior</h3></a></P>
|
||||
<P>More bizarre situations can be accomodated with runtime hooks. These are small scripts that manipulate the environment before your main script runs, effectively providing additional top-level code to your script.</P>
|
||||
<P>At the tail end of an analysis, the module list is examined for matches in <code>rthooks.dat</code>, which is the string representation of a Python dictionary. The key is the module name, and the value is a list of hook-script pathnames.</P>
|
||||
<P>So putting an entry:
|
||||
<code><pre>
|
||||
'somemodule': ['path/to/somescript.py'],
|
||||
</pre></code>
|
||||
into <code>rthooks.dat</code> is <b>almost</b> the same thing as
|
||||
<code><pre>
|
||||
anal = Analysis(['path/to/somescript.py', 'main.py'], ...
|
||||
</pre></code>
|
||||
except that in using the hook, <code>path/to/somescript.py</code> will <b>not</b> be analyzed, (that's not a feature - I just haven't found a sane way fit the recursion into my persistence scheme).</P>
|
||||
<P>Hooks done in this way, while they need to be careful of what they import, are free to do almost anything. One provided hook sets things up so that <code>win32com</code> can generate modules at runtime (to disk), and the generated modules can be found in the <code>win32com</code> package.</P>
|
||||
<P><a name="sysfrozen"><h3>Adapting to being "frozen"</h3></a></P>
|
||||
<P>In most sophisticated apps, it becomes necessary to figure out (at runtime) whether you're running "live" or "frozen". For example, you might have a configuration file that (running "live") you locate based on a module's <code>__file__</code> attribute. That won't work once the code is packaged up. You'll probably want to look for it based on <code>sys.executable</code> instead.</P>
|
||||
<P>The <code>run</code> executables set <code>sys.frozen=1</code> (and, for in-process COM servers, the embedding DLL sets <code>sys.frozen='dll'</code>).</P>
|
||||
<P>For <i>really</i> advanced users, you can access the <code>iu.ImportManager</code> as <code>sys.importManager</code>. See <A HREF="iu4.html">iu</A> for how you might make use of this fact.</P>
|
||||
<P><a name="datafiles"><h2>Accessing Data Files</h2></a></P>
|
||||
<P>In a <code>--onedir</code> distribution, this is easy: pass a list of your data files (in <code>TOC</code> format) to the <code>COLLECT</code>, and they will show up in the distribution
|
||||
directory tree. The <code>name</code> in the <code>(name, path, 'DATA')</code> tuple can be a relative
|
||||
path name. Then, at runtime, you can use code like this to find the file:<code><pre>
|
||||
os.path.join(os.path.dirname(sys.executable), <i>relativename</i>))
|
||||
</pre></code></P>
|
||||
<P>In a <code>--onefile</code>, it's a bit trickier. You can cheat, and add the files to the <code>EXE</code> as <code>BINARY</code>. They will then be extracted at runtime into the work directory by the C code (which does <b>not</b> create directories, so the <code>name</code> must be a plain name), and cleaned up on exit. The work directory is best found by <code>os.environ['_MEIPASS2']</code>. Be awawre, though, that if you use <code>--strip</code> or <code>--upx</code>, strange things may happen to your data - <code>BINARY</code> is really for shared libs / dlls.</P>
|
||||
<P>If you add them as <code>'DATA'</code> to the <code>EXE</code>, then it's up to you to extract them.
|
||||
Use code like this:<code><pre>
|
||||
import sys, carchive
|
||||
this = carchive.CArchive(sys.executable)
|
||||
data = this.extract('mystuff')[1]
|
||||
</pre></code>
|
||||
to get the contents as a binary string. See <code>support/unpackTK.py</code> for an advanced example (the TCL and TK lib files are in a <code>PKG</code> which is opened in place, and
|
||||
then extracted to the filesystem).</P>
|
||||
<P><a name="reporting"><h2>Reporting Bugs</h2></a></P>
|
||||
<P> Report bugs (or feature requests) <a href="http://www.mcmillan-inc.com/cgi-bin/BTSCGI.py/BTS/">here</a>. Please make sure you set <b>Product</b> to <code>Installer</code>. (If you choose not to become a registered user, please include some contact information in the report itself.) Subscribe to the Installer <a href="http://trixie.triqs.com/mailman/listinfo/installer">Mailing List</a> to discuss Installer related issues. And don't forget to show your appreciation <a href="http://www.mcmillan-inc.com/sponsor.html">here</a>.</P>
|
||||
<P><a name="misc"><h2>Miscellaneous</h2></a></P>
|
||||
<P><a name="pmw"><h3>Pmw</h3></a></P>
|
||||
<P>Pmw comes with a script named <CODE>bundlepmw</CODE> in the <CODE>bin</CODE> directory. If you follow the instructions in that script, you'll end up with a module named <CODE>Pmw.py</CODE>. Ensure that Builder finds that module and not the development package.</P>
|
||||
<P><a name="win9xpopen"><h3>Win9xpopen</h3></a></P>
|
||||
<P>If you're using <code>popen</code> on Windows and want the code to work on Win9x, you'll need to distribute
|
||||
<code>win9xpopen.exe</code> with your app. On older Pythons with Win32all, this would apply to <code>Win32pipe</code> and <code>win32popenWin9x.exe</code>. (On yet older Pythons, no form of popen
|
||||
worked on Win9x).
|
||||
</P>
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VALIGN="bottom" BGCOLOR="#D8D0F0"><SMALL>copyright 1999-2002<BR>McMillan Enterprises, Inc.<BR></SMALL></TD>
|
||||
</TR>
|
||||
</TABLE></FONT>
|
||||
</BODY>
|
||||
</HTML>
|
||||
@@ -1,73 +0,0 @@
|
||||
<HTML>
|
||||
<HEAD>
|
||||
<TITLE>
|
||||
An Import Framework
|
||||
</TITLE>
|
||||
|
||||
</HEAD>
|
||||
|
||||
<BODY>
|
||||
<FONT FACE="Helvetica"><TABLE CELLPADDING=5 CELLSPACING=5>
|
||||
<TR ALIGN="center">
|
||||
<TD COLSPAN=2><IMG SRC="me_inc.gif" HEIGHT=36 WIDTH=480><HR></TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VALIGN="top" NOWRAP BGCOLOR="#D8D0F0"><H4>Sitemap</H4><SMALL><A HREF="begin.html">Getting Started</A><BR><A HREF="utilities.html">Utilities</A><BR><A HREF="specfiles.html">Spec Files</A><BR><A HREF="help.html">When Things Go Wrong</A><BR><A HREF="standalones.html">Standalone Executables</A><BR><A HREF="archives.html">Python Archives</A><BR><A HREF="mf4.html">Analyzing Python Modules</A><BR>An Import Framework<BR><BR><a href="http://www.mcmillan-inc.com/cgi-bin/BTSCGI.py/BTS/">Bug Tracker</a><BR></SMALL></TD>
|
||||
<TD ROWSPAN=2><P><h1>An imputil replacement</h1></P>
|
||||
<P>[This is part of Installer release 5. It can also be <a href="dnld/iu.py">downloaded</a> separately.]</P>
|
||||
<P>Module <code>iu</code> grows out of the pioneering work that Greg Stein did with <code>imputil</code> (actually, it includes some verbatim <code>imputil</code> code, but since Greg didn't copyright it, I won't mention it). Both modules can take over Python's builtin import and ease writing of at least certain kinds of import hooks.</P>
|
||||
<P><code>iu</code> differs from <code>imputil</code>:
|
||||
<ul>
|
||||
<li>faster
|
||||
<li>better emulation of builtin <code>import</code>
|
||||
<li>more managable
|
||||
</ul></P>
|
||||
<P>There is an <i>ImportManager</i> which provides the replacement for builtin <code>import</code> and hides all the semantic complexities of a Python import request from it's delegates..</P>
|
||||
<P><h2>ImportManager</h2></P>
|
||||
<P><code>ImportManager</code> formalizes the concept of a <i>metapath</i>. This concept implicitly exists in native Python in that builtins and frozen modules are searched before <code>sys.path</code>, (on Windows there's also a search of the registry while on Mac, resources may be searched). This metapath is a list populated with <i>ImportDirector</i> instances. There are <code>ImportDirector</code> subclasses for builtins, frozen modules, (on Windows) modules found through the registry and a <i>PathImportDirector</i> for handling <code>sys.path</code>. For a top-level import (that is, not an import of a module in a package), <code>ImportManager</code> tries each director on it's metapath until one succeeds.</P>
|
||||
<P><code>ImportManager</code> hides the semantic complexity of an import from the directors. It's up to the <code>ImportManager</code> to decide if an import is relative or absolute; to see if the module has already been imported; to keep <code>sys.modules</code> up to date; to handle the fromlist and return the correct module object.</P>
|
||||
<P><h2>ImportDirectors</h2></P>
|
||||
<P>An <code>ImportDirector</code> just needs to respond to <code>getmod(name)</code> by returning a module object or None. As you will see, an <code>ImportDirector</code> can consider <i>name</i> to be atomic - it has no need to examine <i>name</i> to see if it is dotted.</P>
|
||||
<P>To see how this works, we need to examine the <code>PathImportDirector</code>.</P>
|
||||
<P><h2>PathImportDirector</h2></P>
|
||||
<P>The <code>PathImportDirector</code> subclass manages a list of names - most notably, <code>sys.path</code>. To do so, it maintains a <i>shadowpath</i> - a dictionary mapping the names on it's pathlist (eg, <code>sys.path</code>) to their associated <i>Owners</i>. (It could do this directly, but the assumption that <code>sys.path</code> is occupied solely by strings seems ineradicable.) <code>Owner</code>s of the appropriate kind are created as needed (if all your <code>import</code>s are satisfied by the first two elements of <code>sys.path</code>, the <code>PathImportDirector</code>'s <code>shadowpath</code> will only have two entries).</P>
|
||||
<P><h2>Owners</h2></P>
|
||||
<P>An <code>Owner</code> is much like an <code>ImportDirector</code> but manages a much more concrete piece of turf. For example, a <i>DirOwner</i> manages one directory. Since there are no other officially recognized filesystem-like namespaces for importing, that's all that's included in <code>iu</code>, but it's easy to imagine <code>Owner</code>s for zip files (and I have one for my own .pyz archive format) or even URLs.</P>
|
||||
<P>As with <code>ImportDirector</code>s, an <code>Owner</code> just needs to respond to <code>getmod(name)</code> by returning a module object or None, and it can consider <i>name</i> to be atomic.</P>
|
||||
<P>So structurally, we have a tree, rooted at the <code>ImportManager</code>. At the next level, we have a set of <code>ImportDirector</code>s. At least one of those directors, the <code>PathImportDirector</code> in charge of <code>sys.path</code>, has another level beneath it, consisting of <code>Owners</code>. This much of the tree covers the entire top-level import namespace.</P>
|
||||
<P>The rest of the import namespace is covered by treelets, each rooted in a package module (an <code>__init__.py</code>).</P>
|
||||
<P><h2>Packages</h2></P>
|
||||
<P>To make this work, <code>Owner</code>s need to recognize when a module is a package. For a <code>DirOwner</code>, this means that <i>name</i> is a subdirectory which contains an <code>__init__.py</code>. The <code>__init__</code> module is loaded and it's <code>__path__</code> is initialized with the subdirectory. Then, a <code>PathImportDirector</code> is created to manage this <code>__path__</code>. Finally the new <code>PathImportDirector</code>'s <code>getmod</code> is assigned to the package's <code>__importsub__</code> function.</P>
|
||||
<P>When a module within the package is imported, the request is routed (by the <code>ImportManager</code>) diretly to the package's <code>__importsub__</code>. In a hierarchical namespace (like a filesystem), this means that <code>__importsub__</code> (which is really the bound <code>getmod</code> method of a <code>PathImportDirector</code> instance) needs only the <i>module</i> name, not the package name or the fully qualified name. And that's exactly what it gets. (In a flat namespace - like most archives - it is perfectly easy to route the request back up the package tree to the archive <code>Owner</code>, qualifying the name at each step.)</P>
|
||||
<P><h2>Possibilities</h2></P>
|
||||
<P>Let's say we want to import from .zip files. So, we subclass <code>Owner</code>. The <code>__init__</code> method should take a filename, and raise a <code>ValueError</code> if the file is not an acceptable .zip file, (when a new name is encountered on <code>sys.path</code> or a package's <code>__path__</code>, registered <code>Owner</code>s are tried until one accepts the name). The <code>getmod</code> method would check the .zip file's contents and return <code>None</code> if the name is not found. Otherwise, it would extract the marshalled code object from the .zip, create a new module object and perform a bit of initialization (12 lines of code all told for my own archive format, including initializing a package with it's <code>__subimporter__</code>).</P>
|
||||
<P>Once the new <code>Owner</code> class is registered with <code>iu4</code>, you can put a .zip file on <code>sys.path</code>. A package could even put a .zip file on it's <code>__path__</code>.</P>
|
||||
<P><h2>Compatibility</h2></P>
|
||||
<P>This code has been tested with the PyXML, mxBase and Win32 packages, covering over a dozen import hacks from manipulations of <code>__path__</code> to replacing a module in <code>sys.modules</code> with a different one. Emulation of Python's native import is nearly exact, including the names recorded in <code>sys.modules</code> and module attributes (packages imported through <code>iu</code> have an extra attribute - <code>__importsub__</code>).</P>
|
||||
<P><h2>Performance</h2></P>
|
||||
<P>In most cases, <code>iu</code> is slower than builtin import (by 15 to 20%) but faster than <code>imputil</code> (by 15 to 20%). By inserting archives at the front of <code>sys.path</code> containing the standard lib and the package being tested, this can be reduced to 5 to 10% slower (or, on my 1.52 box, 10% faster!) than builtin import. A bit more can be shaved off by manipulating the <code>ImportManager</code>'s metapath.</P>
|
||||
<P><h2>Limitations</h2></P>
|
||||
<P>This module makes no attempt to facilitate <i>policy</i> import hacks. It is easy to implement certain kinds of policies <i>within a particular domain</i>, but fundamentally <code>iu</code> works by dividing up the import namespace into independent domains.</P>
|
||||
<P>Quite simply, I think cross-domain import hacks are a very bad idea. As author of Installer, I have been dealing with import hacks for three years now. Many of them are highly fragile; they often rely on undocumented (maybe even accidental) features of implementation. A cross-domain import hack is not likely to work with PyXML, for example.</P>
|
||||
<P>That rant aside, you can modify <code>ImportManger</code> to implement different policies. For example, I have a version that implements three import primitives: absolute import, relative import and recursive-relative import. I have no idea what the Python sytax for those should be, but <code>__aimport__</code>, <code>__rimport__</code> and <code>__rrimport__</code> were easy to implement.</P>
|
||||
<P><h2>Usage</h2></P>
|
||||
<P>Here's a simple example of using <code>iu</code> as a builtin import replacement.</P>
|
||||
<P><pre>
|
||||
>>> import iu
|
||||
>>> iu.ImportManager().install()
|
||||
>>>
|
||||
>>> import DateTime
|
||||
>>> DateTime.__importsub__
|
||||
<method PathImportDirector.getmod
|
||||
of PathImportDirector instance at 825900>
|
||||
>>>
|
||||
</pre>
|
||||
</P>
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VALIGN="bottom" BGCOLOR="#D8D0F0"><SMALL>copyright 1999-2002<BR>McMillan Enterprises, Inc.<BR></SMALL></TD>
|
||||
</TR>
|
||||
</TABLE></FONT>
|
||||
</BODY>
|
||||
</HTML>
|
||||
@@ -1,18 +0,0 @@
|
||||
Copyright (c) 2002 McMillan Enterprises, Inc.
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy of
|
||||
this software and associated documentation files (the "Software"), to deal in the
|
||||
Software without restriction, including without limitation the rights to use,
|
||||
copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
|
||||
Software, and to permit persons to whom the Software is furnished to do so,
|
||||
subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
|
||||
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
|
||||
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
|
||||
AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
||||
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 7.4 KiB |
-103
@@ -1,103 +0,0 @@
|
||||
<HTML>
|
||||
<HEAD>
|
||||
<TITLE>
|
||||
Analyzing Python Modules
|
||||
</TITLE>
|
||||
|
||||
</HEAD>
|
||||
|
||||
<BODY>
|
||||
<FONT FACE="Helvetica"><TABLE CELLPADDING=5 CELLSPACING=5>
|
||||
<TR ALIGN="center">
|
||||
<TD COLSPAN=2><IMG SRC="me_inc.gif" HEIGHT=36 WIDTH=480><HR></TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VALIGN="top" NOWRAP BGCOLOR="#D8D0F0"><H4>Sitemap</H4><SMALL><A HREF="begin.html">Getting Started</A><BR><A HREF="utilities.html">Utilities</A><BR><A HREF="specfiles.html">Spec Files</A><BR><A HREF="help.html">When Things Go Wrong</A><BR><A HREF="standalones.html">Standalone Executables</A><BR><A HREF="archives.html">Python Archives</A><BR>Analyzing Python Modules<BR><A HREF="iu4.html">An Import Framework</A><BR><BR><a href="http://www.mcmillan-inc.com/cgi-bin/BTSCGI.py/BTS/">Bug Tracker</a><BR></SMALL></TD>
|
||||
<TD ROWSPAN=2><P><h1>A modulefinder Replacement</h1></P>
|
||||
<P>[This is part of Installer release 5. It can also be <a href="dnld/mf.py">downloaded</a> separately.]</P>
|
||||
<P>Module <code>mf</code> is modelled after <a HREF="iu4.html"><code>iu</code></a> (well, actually I wrote this one first, and it worked so well I created a real importer from it).</P>
|
||||
<P>It also uses <code>ImportDirector</code>s and <code>Owner</code>s to partition the import name space. Except for the fact that these return <code>Module</code> instances instead of real module objects, they are identical.</P>
|
||||
<P>Instead of an <code>ImportManager</code>, <code>mf</code> has an <code>ImportTracker</code> managing things.</P>
|
||||
<P><h2>ImportTracker</h2></P>
|
||||
<P><code>ImportTracker</code> can be called in two ways: <code>analyze_one(<i>name</i>, <i>importername</i>=None)</code> or <code>analyze_r(<i>name</i>, <i>importername</i>=None)</code>. The second method does what <code>modulefinder</code> does - it recursively finds all the module names that importing <i>name</i> would cause to appear in <code>sys.modules</code>. The first method is non-recursive. This is useful, because it is the only way of answering the question "Who imports <i>name</i>?" But since it is somewhat unrealistic (very few real imports do not involve recursion), it deserves some explanation.
|
||||
|
||||
<h2>analyze_one()</h2></P>
|
||||
<P>When a <i>name</i> is imported, there are <b>structural</b> and <b>dynamic</b> effects. The dynamic effects are due to the execution of the top-level code in the module (or modules) that get imported. The structural effects have to do with whether the import is relative or absolute, and whether the name is a dotted name (if there are <b>N</b> dots in the name, then <b>N+1</b> modules will be imported even without any code running).</P>
|
||||
<P>The <code>analyze_one</code> method determines the structural effects, and defers the dynamic effects. For example, <code>analyze_one("B.C", "A")</code> could return <code>["B", "B.C"]</code> or <code>["A.B", "A.B.C"]</code> depending on whether the import turns out to be relative or absolute. In addition, <code>ImportTracker</code>'s <code>modules</code> dict will have <code>Module</code> instances for them.</P>
|
||||
<P><h2>Module Classes</h2></P>
|
||||
<P>There are <code>Module</code> subclasses for builtins, extensions, packages and (normal) modules. Besides the normal module object attributes, they have an attribute <code>imports</code>. For packages and normal modules, <code>imports</code> is a list populated by scanning the code object (and therefor, the names in this list may be relative or absolute names - we don't know until they have been analyzed).</P>
|
||||
<P>The highly astute will notice that there is a hole in <code>analyze_one()</code> here. The first thing that happens when <code>B.C</code> is being imported is that <code>B</code> is imported and it's top-level code executed. That top-level code can do various things so that when the import of <code>B.C</code> finally occurs, something completely different happens (from what a structural analysis would predict). But <code>mf</code> can handle this through it's <i>hooks</i> mechanism.
|
||||
|
||||
<h2>code scanning</h2></P>
|
||||
<P>Like <code>modulefinder</code>, <code>mf</code> scans the byte code of a module, looking for imports. In addition, <code>mf</code> will pick out a module's <code>__all__</code> attribute, if it is built as a list of constant names. This means that if a package declares an <code>__all__</code> list as a list of names, <code>ImportTracker</code> will track those names if asked to analyze <code>package.*</code>. The code scan also notes the occurance of <code>__import__</code>, <code>exec</code> and <code>eval</code>, and can issue warnings when they're found.</P>
|
||||
<P>The code scanning also keeps track (as well as it can) of the context of an import. It recognizes when imports are found at the top-level, and when they are found inside definitions (deferred imports). Within that, it also tracks whether the import is inside a condition (conditional imports).</P>
|
||||
<P><h2>Hooks</h2></P>
|
||||
<P>In <code>modulefinder</code>, scanning the code takes the place of executing the code object. <code>mf</code> goes further and allows a module to be hooked (after it has been scanned, but before <code>analyze_one</code> is done with it). A <i>hook</i> is a module named <code>hook-<i>fullyqualifiedname</i></code> in the <code>hooks</code> package. These modules should have one or more of the following three global names defined:
|
||||
<dl>
|
||||
<dt><code>hiddenimports</code>
|
||||
<dd>a list of modules names (relative or absolute) that the module imports in some untrackable way.
|
||||
<dt><code>attrs</code>
|
||||
<dd>a list of <code>(<i>name</i>, <i>value</i>)</code> pairs, (where <i>value</i> is normally meaningless).
|
||||
<dt><code>hook(mod)</code>
|
||||
<dd>a function taking a Module instance and returning a Module instance (so it can modify or replace).
|
||||
</dl></P>
|
||||
<P>The first hook (<code>hiddenimports</code>) extends the list created by scanning the code. <code>ExtensionModule</code>s, of course, don't get scanned, so this is the only way of recording any imports they do.</P>
|
||||
<P>The second hook (<code>attrs</code>) exists mainly so that <code>ImportTracker</code> won't issue spurious warnings when the rightmost node in a dotted name turns out to be an attribute in a package module, instead of a missing submodule. </P>
|
||||
<P>The callable hook exists for things like dynamic modification of a package's <code>__path__</code> or perverse situations, like <code>xml.__init__</code> replacing itself in <code>sys.modules</code> with <code>_xmlplus.__init__</code>. (It takes nine hook modules to properly trace through PyXML-using code, and I can't believe that it's any easier for the poor programmer using that package). As of Installer 5b5, the <code>hook(mod)</code> (if it exists) is called before looking at the others - that way it can, for example, test sys.version and adjust what's in <code>hiddenimports</code>.</P>
|
||||
<P><b>[Download an example hooks package (as a <a href="dnld/hooks.zip">zip</a> or <a href="dnld/hooks.tar.gz">tar.gz</a> file) - Installer 5 already contains these files.]</b></P>
|
||||
<P><h2>Warnings</h2></P>
|
||||
<P><code>ImportTracker</code> has a <code>getwarnings()</code> method that returns all the warnings accumulated by the instance, and by the <code>Module</code> instances in its <code>modules</code> dict. Generally, it is <code>ImportTracker</code> who will accumulate the warnings generated during the structural phase, and <code>Module</code>s that will get the warnings generated during the code scan.</P>
|
||||
<P>Note that by using a hook module, you can silence some particularly tiresome warnings, but not all of them.</P>
|
||||
<P><h2>Cross Reference</h2></P>
|
||||
<P>Once a full analysis (that is, an <code>analyze_r</code>) has been done, you can get a cross reference by using <code>getxref()</code>. This returns a list of tuples. Each tuple is <code>(modulename, importers)</code>, where <code>importers</code> is a list of the (fully qualified) names of the modules importing <code>modulename</code>. Both the returned list and the importers list are sorted.</P>
|
||||
<P><h2>Usage</h2></P>
|
||||
<P>A simple example follows:
|
||||
<pre>
|
||||
>>> import mf
|
||||
>>> a = mf.ImportTracker()
|
||||
>>> a.analyze_r("os")
|
||||
['os', 'sys', 'posixpath', 'nt', 'stat', 'string', 'strop',
|
||||
're', 'pcre', 'ntpath', 'dospath', 'macpath', 'win32api',
|
||||
'UserDict', 'copy', 'types', 'repr', 'tempfile']
|
||||
>>> a.analyze_one("os")
|
||||
['os']
|
||||
>>> a.modules['string'].imports
|
||||
[('strop', 0, 0), ('strop.*', 0, 0), ('re', 1, 1)]
|
||||
>>>
|
||||
</pre></P>
|
||||
<P>The tuples in the <code>imports</code> list are (<i>name</i>, <code>delayed</code>, <code>conditional</code>).</P>
|
||||
<P><pre>
|
||||
>>> for w in a.modules['string'].warnings: print w
|
||||
...
|
||||
W: delayed eval hack detected at line 359
|
||||
W: delayed eval hack detected at line 389
|
||||
W: delayed eval hack detected at line 418
|
||||
>>> for w in a.getwarnings(): print w
|
||||
...
|
||||
W: no module named pwd (delayed, conditional import by posixpath)
|
||||
W: no module named dos (conditional import by os)
|
||||
W: no module named os2 (conditional import by os)
|
||||
W: no module named posix (conditional import by os)
|
||||
W: no module named mac (conditional import by os)
|
||||
W: no module named MACFS (delayed, conditional import by tempfile)
|
||||
W: no module named macfs (delayed, conditional import by tempfile)
|
||||
W: top-level conditional exec statment detected at line 47
|
||||
- os (C:\Program Files\Python\Lib\os.py)
|
||||
W: delayed eval hack detected at line 359
|
||||
- string (C:\Program Files\Python\Lib\string.py)
|
||||
W: delayed eval hack detected at line 389
|
||||
- string (C:\Program Files\Python\Lib\string.py)
|
||||
W: delayed eval hack detected at line 418
|
||||
- string (C:\Program Files\Python\Lib\string.py)
|
||||
>>>
|
||||
</pre></P>
|
||||
<P>(The historically minded will note the antiquity of the Python used to demonstrate this.)
|
||||
</P>
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VALIGN="bottom" BGCOLOR="#D8D0F0"><SMALL>copyright 1999-2002<BR>McMillan Enterprises, Inc.<BR></SMALL></TD>
|
||||
</TR>
|
||||
</TABLE></FONT>
|
||||
</BODY>
|
||||
</HTML>
|
||||
@@ -1,258 +0,0 @@
|
||||
<HTML>
|
||||
<HEAD>
|
||||
<TITLE>
|
||||
Spec Files
|
||||
</TITLE>
|
||||
|
||||
</HEAD>
|
||||
|
||||
<BODY>
|
||||
<FONT FACE="Helvetica"><TABLE CELLPADDING=5 CELLSPACING=5>
|
||||
<TR ALIGN="center">
|
||||
<TD COLSPAN=2><IMG SRC="me_inc.gif" HEIGHT=36 WIDTH=480><HR></TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VALIGN="top" NOWRAP BGCOLOR="#D8D0F0"><H4>Sitemap</H4><SMALL><A HREF="begin.html">Getting Started</A><BR><A HREF="utilities.html">Utilities</A><BR>Spec Files<BR><A HREF="help.html">When Things Go Wrong</A><BR><A HREF="standalones.html">Standalone Executables</A><BR><A HREF="archives.html">Python Archives</A><BR><A HREF="mf4.html">Analyzing Python Modules</A><BR><A HREF="iu4.html">An Import Framework</A><BR><BR><a href="http://www.mcmillan-inc.com/cgi-bin/BTSCGI.py/BTS/">Bug Tracker</a><BR></SMALL></TD>
|
||||
<TD ROWSPAN=2><P><h1>Spec Files</h1></P>
|
||||
<P>Contents:</br>
|
||||
<ul>
|
||||
<li><a href="#intro">Introduction</a></li>
|
||||
<li><a href="#toc">TOC Class (Table of Contents)</a></li>
|
||||
<li><a href="#subclasses">Target Subclasses</a></li>
|
||||
<ul>
|
||||
<li><a href="#analysis">Analysis</a></li>
|
||||
<li><a href="#pyz">PYZ</a></li>
|
||||
<li><a href="#pkg">PKG</a></li>
|
||||
<li><a href="#exe">EXE</a></li>
|
||||
<li><a href="#dll">DLL</a></li>
|
||||
<li><a href="#collect">COLLECT</a></li>
|
||||
<li><a href="#tree">Tree</a></li>
|
||||
</ul>
|
||||
</ul></P>
|
||||
<P><a name="intro"><h2>Introduction</h2></P>
|
||||
<P>Spec files are in Python syntax. They are evaluated by <code>Build.py</code>. A simplistic spec file might look like this:
|
||||
<code><pre>
|
||||
a = Analysis(['myscript.py'])
|
||||
pyz = PYZ(a.pure)
|
||||
exe = EXE(pyz, a.scripts, a.binaries, name="myapp.exe")
|
||||
</pre></code></P>
|
||||
<P>This creates a single file deployment with all binaries (extension modules and their dependencies) packed into the executable.</P>
|
||||
<P>A simplistic single directory deployment might look like this:
|
||||
<code><pre>
|
||||
a = Analysis(['myscript.py'])
|
||||
pyz = PYZ(a.pure)
|
||||
exe = EXE(a.scripts, pyz, name="myapp.exe", exclude_binaries=1)
|
||||
dist = COLLECT(exe, a.binaries, name="dist")
|
||||
</pre></code></P>
|
||||
<P>Note that neither of these examples are realistic. Use <code>Makespec.py</code> (documented <A HREF="begin.html">here</A>) to create your specfile, and tweak it (if necessary) from there.</P>
|
||||
<P>All of the classes you see above are subclasses of <code>Build.Target</code>. A <code>Target</code> acts like a rule in a makefile. It knows enough to cache its last inputs and outputs. If its inputs haven't changed, it can assume its outputs wouldn't change on recomputation. So a spec file acts much like a makefile, only rebuilding as much as needs rebuilding. This means, for example, that if you change an <code>EXE</code> from <code>debug=1</code> to <code>debug=0</code> that the rebuild will be nearly instantaneous.</P>
|
||||
<P>The high level view is that an Analysis takes a list of scripts as input, and generates three "outputs", held in attributes named <code>scripts</code>, <code>pure</code> and <code>binaries</code>. A <code>PYZ</code> (a .pyz archive) is built from the modules in <code>pure</code>. The <code>EXE</code> is built from the <code>PYZ</code>, the <code>scripts</code> and, in the case of a single-file deployment, the <code>binaries</code>. In a single-directory deployment, a directory is built containing a slim <code>EXE</code> and the <code>binaries</code>.</P>
|
||||
<P><a name="toc"><h2>TOC Class (Table of Contents)</h2></a></P>
|
||||
<P>Before you can do much with a spec file, you need to understand the <code>TOC</code> (Table Of Contents) class.</P>
|
||||
<P>A <code>TOC</code> appears to be a list of tuples of the form <code>(name, path, typecode)</code>. In fact, it's an <b>ordered set</b>, not a list. A <code>TOC</code> contains no duplicates, where uniqueness is based on <code>name</code> only. Furthermore, within this constraint, a <code>TOC</code> preserves order.</P>
|
||||
<P>Besides the normal list methods and operations, <code>TOC</code> supports taking <b>differences</b> and <b>intersections</b> (and note that adding or extending is really equivalent to <b>union</b>). Furthermore, the operations can take a real list of tuples on the right hand side. This makes excluding modules quite easy:
|
||||
<code><pre>
|
||||
pyz = PYZ(a.pure - [('badmodule', '', '')])
|
||||
</pre></code>
|
||||
for a pure Python module and
|
||||
<code><pre>
|
||||
dist = COLLECT(..., a.binaries - [('badmodule', '', '')], ...)
|
||||
</pre></code>
|
||||
for an extension module in a single-directory deployment, or
|
||||
<code><pre>
|
||||
exe = EXE(..., a.binaries - [('badmodule', '', '')], ...)
|
||||
</pre></code>
|
||||
for a single-file deployment.</P>
|
||||
<P>To add files to a <code>TOC</code>, you need to know about the <code>typecode</code>s (or the step using the <code>TOC</code> won't know what to do with the entry).</P>
|
||||
<P><table>
|
||||
<tr>
|
||||
<th>typecode</th><th>description</th><th>name</th><th>path</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>'EXTENSION'</td>
|
||||
<td>An extension module.</td>
|
||||
<td>Python internal name.</td>
|
||||
<td>Full path name in build.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>'PYSOURCE'</td>
|
||||
<td>A script.</td>
|
||||
<td>Python internal name.</td>
|
||||
<td>Full path name in build.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>'PYMODULE'</td>
|
||||
<td>A pure Python module (including <code>__init__</code> modules).</td>
|
||||
<td>Python internal name.</td>
|
||||
<td>Full path name in build.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>'PYZ'</td>
|
||||
<td>A .pyz archive (<code>archive_rt.ZlibArchive</code>).</td>
|
||||
<td>Runtime name.</td>
|
||||
<td>Full path name in build.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>'PKG'</td>
|
||||
<td>A pkg archive (<code>carchive4.CArchive</code>).</td>
|
||||
<td>Runtime name.</td>
|
||||
<td>Full path name in build.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>'BINARY'</td>
|
||||
<td>A shared library.</td>
|
||||
<td>Runtime name.</td>
|
||||
<td>Full path name in build.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>'DATA'</td>
|
||||
<td>Aribitrary files.</td>
|
||||
<td>Runtime name.</td>
|
||||
<td>Full path name in build.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>'OPTION'</td>
|
||||
<td>A runtime runtime option (frozen into the executable).</td>
|
||||
<td>The option.</td>
|
||||
<td>Unused.</td>
|
||||
</tr>
|
||||
</table></P>
|
||||
<P>You can force the include of any file in much the same way you do excludes.
|
||||
<code><pre>
|
||||
collect = COLLECT(a.binaries +
|
||||
[('readme', '/my/project/readme', 'DATA')], ...)
|
||||
</pre></code>
|
||||
or even
|
||||
<code><pre>
|
||||
collect = COLLECT(a.binaries,
|
||||
[('readme', '/my/project/readme', 'DATA')], ...)
|
||||
</pre></code>
|
||||
(that is, you can use a list of tuples in place of a <code>TOC</code> in most cases).</P>
|
||||
<P>There's not much reason to use this technique for <code>PYSOURCE</code>, since an Analysis takes a list of scripts as input. For <code>PYMODULE</code>s and <code>EXTENSION</code>s, the hook mechanism discussed <a HREF="help.html">here</a> is better because you won't have to remember how you got it working next time.</P>
|
||||
<P>This technique is most useful for data files (see the <code>Tree</code> class below for a way to build a <code>TOC</code> from a directory tree), and for runtime options. The options the <code>run</code> executables understand are:</P>
|
||||
<P><table>
|
||||
<tr>
|
||||
<th>Option</th><th>Description</th><th>Example</th><th>Notes</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>v</td>
|
||||
<td>Verbose imports</td>
|
||||
<td>('v', '', 'OPTION')</td>
|
||||
<td>Same as <code>Python -v ...</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>u</td>
|
||||
<td>Unbuffered stdio</td>
|
||||
<td>('u', '', 'OPTION')</td>
|
||||
<td>Same as <code>Python -u ...</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td nowrap>W <i>spec</i></td>
|
||||
<td>Warning option</td>
|
||||
<td>('W ignore', '', 'OPTION')</td>
|
||||
<td>Python 2.1+ only.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>s</td>
|
||||
<td>Use site.py</td>
|
||||
<td>('s', '', 'OPTION')</td>
|
||||
<td>The <b>opposite</b> of Python's -S flag. Note that site.py must be in the executable's directory to be used.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>f</td>
|
||||
<td>Force execvp</td>
|
||||
<td>('f', '', 'OPTION')</td>
|
||||
<td>Linux/unix only. Ensures that <code>LD_LIBRARY_PATH</code> is set properly.</td>
|
||||
</tr>
|
||||
</table></P>
|
||||
<P>Advanced users should note that by using set differences and intersections, it becomes possible to factor out common modules, and deploy a project containing multiple executables with minimal redundancy. You'll need some top level code in each executable to mount the common <code>PYZ</code>.</P>
|
||||
<P><a name="subclasses"><h2>Target Subclasses</h2></a></P>
|
||||
<P><a name="analysis"><h3>Analysis</h3></a></P>
|
||||
<P><code><pre>
|
||||
Analysis(scripts, pathex=None, hookspath=None, excludes=None)
|
||||
</pre></code>
|
||||
<dl>
|
||||
<dt>scripts<dd>a list of scripts specified as file names.
|
||||
<dt>pathex<dd>an optional list of paths to be searched before sys.path.
|
||||
<dt>hookspath<dd>an optional list of paths used to extend the <code>hooks</code> package.
|
||||
<dt>excludes<dd>an optional list of module or package names (their Python names, not path names) that will be ignored (as though they were not found).
|
||||
</dl>
|
||||
An Analysis has three outputs, all <code>TOC</code>s accessed as attributes of the Analysis.
|
||||
<dl>
|
||||
<dt>scripts<dd>The scripts you gave Analysis as input, with any runtime hook scripts prepended.
|
||||
<dt>pure<dd>The pure Python modules.
|
||||
<dt>binaries<dd>The extension modules and their dependencies. The secondary dependencies are filtered. On Windows, a long list of MS dlls are excluded. On Linux/Unix, any shared lib in <code>/lib</code> or <code>/usr/lib</code> is excluded.
|
||||
</dl></P>
|
||||
<P><a name="pyz"><h3>PYZ</h3></a></P>
|
||||
<P><code><pre>
|
||||
PYZ(toc, name=None, level=9)
|
||||
</pre></code>
|
||||
<dl>
|
||||
<dt>toc<dd>a <code>TOC</code>, normally an <code>Analysis.pure</code>.
|
||||
<dt>name<dd>A filename for the .pyz. Normally not needed, as the generated name will do fine.
|
||||
<dt>level<dd>The Zlib compression level to use. If <code>0</code>, the <code>zlib</code> module is not required.
|
||||
</dl></P>
|
||||
<P><a name="pyz"><h3>PKG</h3></a></P>
|
||||
<P>Generally, you will not need to create your own <code>PKG</code>s, as the <code>EXE</code> will do it for you. This is one way to include read-only data in a single-file deployment, however. A single-file deployment including TK support will use this technique.</P>
|
||||
<P><code><pre>
|
||||
PKG(toc, name=None, cdict=None, exclude_binaries=0)
|
||||
</pre></code>
|
||||
<dl>
|
||||
<dt>toc<dd>a <code>TOC</code>
|
||||
<dt>name<dd>a filename for the pkg (optional).
|
||||
<dt>cdict<dd>a dictionary that specifies compression by typecode. For example, <code>PYZ</code> is left uncompressed so that it can be accessed inside the <code>PKG</code>. The default uses sensible values. If <code>zlib</code> is not available, no compression is used.
|
||||
<dt>exclude_binaries<dd>If 1, <code>EXTENSION</code>s and <code>BINARY</code>s will be left out of the <code>PKG</code>, and forwarded to its container (ususally a <code>COLLECT</code>).
|
||||
</dl></P>
|
||||
<P><a name="exe"><h3>EXE</h3></a></P>
|
||||
<P><code><pre>
|
||||
EXE(*args, **kws)
|
||||
</pre></code>
|
||||
<dl>
|
||||
<dt>args<dd>One or more arguments which are either <code>TOC</code>s or <code>Target</code>s.
|
||||
<dt>kws<dd>
|
||||
<dl>
|
||||
<dt>console<dd>Always 1 on Linux/unix. On Windows, governs whether to use the console executable, or the Windows subsystem executable.
|
||||
<dt>debug<dd>Setting to 1 gives you progress messages from the executable (for a <code>console=0</code>, these will be annoying MessageBoxes).
|
||||
<dt>name<dd>The filename for the executable.
|
||||
<dt>exclude_binaries<dd>Forwarded to the <code>PKG</code> the <code>EXE</code> builds.
|
||||
<dt>icon<dd>Windows NT family only. <code>icon='myicon.ico'</code> to use an icon file, or <code>icon='notepad.exe,0'</code> to grab an icon resource.
|
||||
<dt>version<dd>Windows NT family only. <code>version='myversion.txt'</code>. Use <code>GrabVersion.py</code> to steal a version resource from an executable, and then edit the ouput to create your own. (The syntax of version resources is so arcane that I wouldn't attempt to write one from scratch.)
|
||||
</dl>
|
||||
</dl></P>
|
||||
<P>There are actually two <code>EXE</code> classes - one for ELF platforms (where the <code>run</code> executable and the <code>PKG</code> are concatenated), and one for non-ELF platforms (where the <code>run</code> executable is simply renamed, and expects a <code><i>exename</i>.pkg</code> in the same directory). Which class becomes available as <code>EXE</code> is determined by a flag in <code>config.dat</code>. This flag is set to non-ELF when using <code>Make.py -n</code>.</P>
|
||||
<P><a name="dll"><h3>DLL</h3></a></P>
|
||||
<P>On Windows, this provides support for doing in-process COM servers. It is not generalized. However, embedders can follow the same model to build a special purpose DLL so the Python support in their app is hidden. You will need to write your own dll, but thanks to Allan Green for refactoring the C code and making that a managable task.</P>
|
||||
<P><a name="collect"><h3>COLLECT</h3></a></P>
|
||||
<P><code><pre>
|
||||
COLLECT(*args, **kws)
|
||||
</pre></code>
|
||||
<dl>
|
||||
<dt>args<dd>One or more arguments which are either <code>TOC</code>s or <code>Target</code>s.
|
||||
<dt>kws<dd>
|
||||
<dl>
|
||||
<dt>name<dd>The name of the directory to be built.
|
||||
</dl>
|
||||
</dl></P>
|
||||
<P><a name="tree"><h3>Tree</h3></a></P>
|
||||
<P><code><pre>
|
||||
Tree(root, prefix=None, excludes=None)
|
||||
</code></pre>
|
||||
<dl>
|
||||
<dt>root<dd>The root of the tree (on the build system).
|
||||
<dt>prefix<dd>Optional prefix to the names on the target system.
|
||||
<dt>excludes<dd>A list of names to exclude. Two forms are allowed:
|
||||
<dl>
|
||||
<dt>name<dd>files with this basename will be excluded (do not include the path).
|
||||
<dt>*.ext<dd>any file with the given extension will be excluded.
|
||||
</dl>
|
||||
</dl></P>
|
||||
<P>Since a <code>Tree</code> is a <code>TOC</code>, you can also use the exclude technique described above in the section on <a href="#toc"><code>TOC</code>s</a>.
|
||||
</P>
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VALIGN="bottom" BGCOLOR="#D8D0F0"><SMALL>copyright 1999-2002<BR>McMillan Enterprises, Inc.<BR></SMALL></TD>
|
||||
</TR>
|
||||
</TABLE></FONT>
|
||||
</BODY>
|
||||
</HTML>
|
||||
@@ -1,60 +0,0 @@
|
||||
<HTML>
|
||||
<HEAD>
|
||||
<TITLE>
|
||||
Standalone Executables
|
||||
</TITLE>
|
||||
|
||||
</HEAD>
|
||||
|
||||
<BODY>
|
||||
<FONT FACE="Helvetica"><TABLE CELLPADDING=5 CELLSPACING=5>
|
||||
<TR ALIGN="center">
|
||||
<TD COLSPAN=2><IMG SRC="me_inc.gif" HEIGHT=36 WIDTH=480><HR></TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VALIGN="top" NOWRAP BGCOLOR="#D8D0F0"><H4>Sitemap</H4><SMALL><A HREF="begin.html">Getting Started</A><BR><A HREF="utilities.html">Utilities</A><BR><A HREF="specfiles.html">Spec Files</A><BR><A HREF="help.html">When Things Go Wrong</A><BR>Standalone Executables<BR><A HREF="archives.html">Python Archives</A><BR><A HREF="mf4.html">Analyzing Python Modules</A><BR><A HREF="iu4.html">An Import Framework</A><BR><BR><a href="http://www.mcmillan-inc.com/cgi-bin/BTSCGI.py/BTS/">Bug Tracker</a><BR></SMALL></TD>
|
||||
<TD ROWSPAN=2><P><h4>Self-extracting executables</h4></P>
|
||||
<P>The ELF executable format (Windows, Linux and some others) allows arbitrary data to be concatenated to the end of the executable without disturbing it's functionality.
|
||||
For this reason, a <A HREF="archives.html">CArchive</A>'s Table of Contents is at the end of the archive.
|
||||
The executable can open itself as a binary file name, seek to the end and 'open' the CArchive (see figure 3). </P>
|
||||
<P>On other platforms, the archive and the executable are separate, but the archive is named <i>executable</i>.pkg, and expected to be in the same directory. Other than that, the process is the same.</P>
|
||||
<P><h4>One Pass Execution</h4></P>
|
||||
<P>In a single directory deployment (<code>--onedir</code>, which is the default), all of the binaries are already in the file system. In that case, the embedding app:
|
||||
<ul>
|
||||
<li>opens the archive
|
||||
<li>starts Python (on Windows, this is done with dynamic loading so one embedding app binary can be used with any Python version)
|
||||
<li>imports all the modules which are at the top level of the archive (basically, bootstraps the import hooks)
|
||||
<li>mounts the ZlibArchive(s) in the outer archive
|
||||
<li>runs all the scripts which are at the top level of the archive
|
||||
<li>finalizes Python
|
||||
</ul></P>
|
||||
<P><h4>Two Pass Execution</h4></P>
|
||||
<P>There are a couple situations which require two passes:
|
||||
<ul>
|
||||
<li>a <code>--onefile</code> deployment (on Windows, the files can't be cleaned up afterwards because Python does not call <code>FreeLibrary</code>; on other platforms, Python won't find them if they're extracted in the same process that uses them)
|
||||
<li><code>LD_LIBRARY_PATH</code> needs to be set to find the binaries (not extension modules, but modules the extensions are linked to).
|
||||
</ul></P>
|
||||
<P>The first pass:
|
||||
<ul>
|
||||
<li>opens the archive
|
||||
<li>extracts all the binaries in the archive (in 5b5, this is always to a temporary directory).
|
||||
<li>sets a magic environment variable
|
||||
<li>sets <code>LD_LIBRARY_PATH</code> (non-Windows)
|
||||
<li>executes itself as a child process (letting the child use his stdin, stdout and stderr)
|
||||
<li>waits for the child to exit (on *nix, the child actually replaces the parent)
|
||||
<li>cleans up the extracted binaries (so on *nix, this is done by the child)
|
||||
</ul></P>
|
||||
<P>The child process executes as in One Pass Execution above (the magic environment variable is what tells it that this is pass two).</P>
|
||||
<P><img src="SE_exe.gif">
|
||||
figure 3 - Self Extracting Executable</P>
|
||||
<P>There are, of course, quite a few differences between the Windows and Unix/Linux versions. The major one is that because <b>all</b> of Python on Windows is in pythonXX.dll, and dynamic loading is so simple-minded, I can use one binary with any version of Python. There's much in common, though, and that C code can be found in <code>source/common/launch.c</code>.</P>
|
||||
<P>The Unix/Linux build process (which you need to run just once for any version of Python) makes use of the config information in your install (if you installed from RPM, you need the Python-development RPM). It also overrides <code>getpath.c</code> since we don't want it hunting around the filesystem to build <code>sys.path</code>. </P>
|
||||
<P>In both cases, while one Installer download can be used with any Python version, you need to have separate installations for each Python version.</P>
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VALIGN="bottom" BGCOLOR="#D8D0F0"><SMALL>copyright 1999-2002<BR>McMillan Enterprises, Inc.<BR></SMALL></TD>
|
||||
</TR>
|
||||
</TABLE></FONT>
|
||||
</BODY>
|
||||
</HTML>
|
||||
@@ -1,51 +0,0 @@
|
||||
<HTML>
|
||||
<HEAD>
|
||||
<TITLE>
|
||||
Utilities
|
||||
</TITLE>
|
||||
|
||||
</HEAD>
|
||||
|
||||
<BODY>
|
||||
<FONT FACE="Helvetica"><TABLE CELLPADDING=5 CELLSPACING=5>
|
||||
<TR ALIGN="center">
|
||||
<TD COLSPAN=2><IMG SRC="me_inc.gif" HEIGHT=36 WIDTH=480><HR></TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VALIGN="top" NOWRAP BGCOLOR="#D8D0F0"><H4>Sitemap</H4><SMALL><A HREF="begin.html">Getting Started</A><BR>Utilities<BR><A HREF="specfiles.html">Spec Files</A><BR><A HREF="help.html">When Things Go Wrong</A><BR><A HREF="standalones.html">Standalone Executables</A><BR><A HREF="archives.html">Python Archives</A><BR><A HREF="mf4.html">Analyzing Python Modules</A><BR><A HREF="iu4.html">An Import Framework</A><BR><BR><a href="http://www.mcmillan-inc.com/cgi-bin/BTSCGI.py/BTS/">Bug Tracker</a><BR></SMALL></TD>
|
||||
<TD ROWSPAN=2><P><center><h1>The Utilities</h1></center></P>
|
||||
<P><ul>
|
||||
<li><a href="#ArchiveViewer">ArchiveViewer</a>
|
||||
<li><a href="#GrabVersion">GrabVersion</a>
|
||||
<li><a href="#seealso">Others</a>
|
||||
</ul></P>
|
||||
<P><a name="ArchiveViewer"><h2>ArchiveViewer</h2></a></P>
|
||||
<P><code><pre>
|
||||
>python ArchiveViewer.py <i>archivefile</i>
|
||||
</pre></code></P>
|
||||
<P>ArchiveViewer lets you examine the contents of any Installer-built archive or executable (PYZ, PKG or exe). Invoke it with the target as the first arg (I have it set up as a Send-To so it shows on my context menu in Explorer). You can navigate through the archive with these commands:
|
||||
<dl>
|
||||
<dt><b>O <nm></b><dd>Open the embedded archive <nm> (will prompt if omitted).
|
||||
<dt><b>U</b><dd>Go up one level (go back to viewing the embedding archive).
|
||||
<dt><b>X <nm></b><dd>Extract <b>nm</b> (will prompt if omitted). Prompts for output filename. If none given, extracted to stdout.
|
||||
<dt><b>Q</b><dd>Quit.
|
||||
</dl></P>
|
||||
<P><a name="GrabVersion"><h2>GrabVersion (Windows)</h2></a></P>
|
||||
<P><code><pre>
|
||||
>python GrabVersion.py <i>executable_with_version_resource</i>
|
||||
</pre></code></P>
|
||||
<P>GrabVersion outputs text which can be eval'ed by versionInfo to reproduce a version resource. Invoke it with the full path name of a Windows executable (with a version resource) as the first argument. If you cut & paste (or redirect to a file), you can then edit the version information. The edited text file can be used in a <code>version = myversion.txt</code> option on any executable in an Installer spec file.</P>
|
||||
<P>I did it this way because version resources are rather strange beasts, and fully understanding them is probably impossible. Some elements are optional, others required, but you could spend unbounded amounts of time figuring this out, because it's not well documented. When you view the version tab on a properties dialog, there's no straightforward relationship between how the data is displayed and the structure of the resource itself. So the easiest thing to do is find an executable that displays the kind of information you want, grab it's resource and edit it. Certainly easier than the Version resource wizard in VC++.</P>
|
||||
<P><a name="seealso"><h2>Others</h2></a></P>
|
||||
<P><h3>Analyzing Dependencies</h3></P>
|
||||
<P>You can interactively track down dependencies, including getting cross-references by using mf.py, documented <A HREF="mf4.html">here</A>.</P>
|
||||
<P></P>
|
||||
<P> </P>
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VALIGN="bottom" BGCOLOR="#D8D0F0"><SMALL>copyright 1999-2002<BR>McMillan Enterprises, Inc.<BR></SMALL></TD>
|
||||
</TR>
|
||||
</TABLE></FONT>
|
||||
</BODY>
|
||||
</HTML>
|
||||
Reference in New Issue
Block a user