172 lines
6.8 KiB
Plaintext
172 lines
6.8 KiB
Plaintext
THE FREEZE SCRIPT
|
|
=================
|
|
|
|
(Directions for Windows are at the end of this file.)
|
|
|
|
|
|
What is Freeze?
|
|
---------------
|
|
|
|
Freeze make it possible to ship arbitrary Python programs to people
|
|
who don't have Python. The shipped file (called a "frozen" version of
|
|
your Python program) is an executable, so this only works if your
|
|
platform is compatible with that on the receiving end (this is usually
|
|
a matter of having the same major operating system revision and CPU
|
|
type).
|
|
|
|
The shipped file contains a Python interpreter and large portions of
|
|
the Python run-time. Some measures have been taken to avoid linking
|
|
unneeded modules, but the resulting binary is usually not small.
|
|
|
|
The Python source code of your program (and of the library modules
|
|
written in Python that it uses) is not included in the binary --
|
|
instead, the compiled byte-code (the instruction stream used
|
|
internally by the interpreter) is incorporated. This gives some
|
|
protection of your Python source code, though not much -- a
|
|
disassembler for Python byte-code is available in the standard Python
|
|
library. At least someone running "strings" on your binary won't see
|
|
the source.
|
|
|
|
|
|
How does Freeze know which modules to include?
|
|
----------------------------------------------
|
|
|
|
Previous versions of Freeze used a pretty simple-minded algorithm to
|
|
find the modules that your program uses, essentially searching for
|
|
lines starting with the word "import". It was pretty easy to trick it
|
|
into making mistakes, either missing valid import statements, or
|
|
mistaking string literals (e.g. doc strings) for import statements.
|
|
|
|
This has been remedied: Freeze now uses the regular Python parser to
|
|
parse the program (and all its modules) and scans the generated byte
|
|
code for IMPORT instructions. It may still be confused -- it will not
|
|
know about calls to the __import__ built-in function, or about import
|
|
statements constructed on the fly and executed using the 'exec'
|
|
statement, and it will consider import statements even when they are
|
|
unreachable (e.g. "if 0: import foobar").
|
|
|
|
This new version of Freeze also knows about Python's new package
|
|
import mechanism, and uses exactly the same rules to find imported
|
|
modules and packages. One exception: if you write 'from package
|
|
import *', Python will look into the __all__ variable of the package
|
|
to determine which modules are to be imported, while Freeze will do a
|
|
directory listing.
|
|
|
|
One tricky issue: Freeze assumes that the Python interpreter and
|
|
environment you're using to run Freeze is the same one that would be
|
|
used to run your program, which should also be the same whose sources
|
|
and installed files you will learn about in the next section. In
|
|
particular, your PYTHONPATH setting should be the same as for running
|
|
your program locally. (Tip: if the program doesn't run when you type
|
|
"python hello.py" there's little chance of getting the frozen version
|
|
to run.)
|
|
|
|
|
|
How do I use Freeze?
|
|
--------------------
|
|
|
|
Normally, you should be able to use it as follows:
|
|
|
|
python freeze.py hello.py
|
|
|
|
where hello.py is your program and freeze.py is the main file of
|
|
Freeze (in actuality, you'll probably specify an absolute pathname
|
|
such as /usr/joe/python/Tools/freeze/freeze.py).
|
|
|
|
|
|
What do I do next?
|
|
------------------
|
|
|
|
Freeze creates three files: frozen.c, config.c and Makefile. To
|
|
produce the frozen version of your program, you can simply type
|
|
"make". This should produce a binary file. If the filename argument
|
|
to Freeze was "hello.py", the binary will be called "hello".
|
|
|
|
Note: you can use the -o option to freeze to specify an alternative
|
|
directory where these files are created. This makes it easier to
|
|
clean up after you've shipped the frozen binary. You should invoke
|
|
"make" in the given directory.
|
|
|
|
|
|
Freezing Tkinter programs
|
|
-------------------------
|
|
|
|
Unfortunately, it is currently not possible to freeze programs that
|
|
use Tkinter. It *seems* to work, but when you ship the frozen program
|
|
to a site without a Tcl/Tk installation, it will fail with a complaint
|
|
about missing Tcl/Tk initialization files.
|
|
|
|
A workaround would be possible, in which the Tcl/Tk library files are
|
|
incorporated in a frozen Python module as string literals and written
|
|
to a temporary location when the program runs; this is currently left
|
|
as an exercise for the reader. (If you implement this, please post to
|
|
the Python newsgroup!)
|
|
|
|
Of course, you can also simply require that Tcl/Tk is required on the
|
|
target installation.
|
|
|
|
|
|
A warning against shared library modules
|
|
----------------------------------------
|
|
|
|
When your Python installation uses shared library modules, these will
|
|
not be incorporated in the frozen program. Again, the frozen program
|
|
will work when you test it, but it won't work when you ship it to a
|
|
site without a Python installation.
|
|
|
|
Freeze prints a warning when this is the case at the end of the
|
|
freezing process:
|
|
|
|
Warning: unknown modules remain: ...
|
|
|
|
When this occurs, the best thing to do is usually to rebuild Python
|
|
using static linking only.
|
|
|
|
|
|
Troubleshooting
|
|
---------------
|
|
|
|
If you have trouble using Freeze for a large program, it's probably
|
|
best to start playing with a really simple program first (like the file
|
|
hello.py). If you can't get that to work there's something
|
|
fundamentally wrong -- perhaps you haven't installed Python. To do a
|
|
proper install, you should do "make install" in the Python root
|
|
directory.
|
|
|
|
|
|
Usage under Windows 95 or NT
|
|
----------------------------
|
|
|
|
Under Windows 95 or NT, you *must* use the -p option and point it to
|
|
the top of the Python source tree.
|
|
|
|
WARNING: the resulting executable is not self-contained; it requires
|
|
the Python DLL, currently PYTHON15.DLL (it does not require the
|
|
standard library of .py files though). It may also require one or
|
|
more extension modules loaded from .DLL or .PYD files; the module
|
|
names are printed in the warning message about remaining unknown
|
|
modules.
|
|
|
|
The driver script generates a Makefile that works with the Microsoft
|
|
command line C compiler (CL). To compile, run "nmake"; this will
|
|
build a target "hello.exe" if the source was "hello.py". Only the
|
|
files frozenmain.c and frozen.c are used; no config.c is generated or
|
|
used, since the standard DLL is used.
|
|
|
|
In order for this to work, you must have built Python using the VC++
|
|
(Developer Studio) 5.0 compiler. The provided project builds
|
|
python15.lib in the subdirectory pcbuild\Release of thje Python source
|
|
tree, and this is where the generated Makefile expects it to be. If
|
|
this is not the case, you can edit the Makefile or (probably better)
|
|
winmakemakefile.py (e.g., if you are using the 4.2 compiler, the
|
|
python15.lib file is generated in the subdirectory vc40 of the Python
|
|
source tree).
|
|
|
|
You can freeze programs that use Tkinter, but Tcl/Tk must be installed
|
|
on the target system.
|
|
|
|
It is possible to create frozen programs that don't have a console
|
|
window, by specifying the option '-s windows'.
|
|
|
|
--Guido van Rossum (home page: http://www.python.org/~guido/)
|