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 a number of files: frozen.c, config.c and Makefile, | |
plus one file for each Python module that gets included named | |
M_<module>.c. 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 without a Tcl/Tk installation. The best way to ship a | |
frozen Tkinter program is to decide in advance where you are going | |
to place the Tcl and Tk library files in the distributed setup, and | |
then declare these directories in your frozen Python program using | |
the TCL_LIBRARY, TK_LIBRARY and TIX_LIBRARY environment variables. | |
For example, assume you will ship your frozen program in the directory | |
<root>/bin/windows-x86 and will place your Tcl library files | |
in <root>/lib/tcl8.2 and your Tk library files in <root>/lib/tk8.2. Then | |
placing the following lines in your frozen Python script before importing | |
Tkinter or Tix would set the environment correctly for Tcl/Tk/Tix: | |
import os | |
import os.path | |
RootDir = os.path.dirname(os.path.dirname(os.getcwd())) | |
import sys | |
if sys.platform == "win32": | |
sys.path = ['', '..\\..\\lib\\python-2.0'] | |
os.environ['TCL_LIBRARY'] = RootDir + '\\lib\\tcl8.2' | |
os.environ['TK_LIBRARY'] = RootDir + '\\lib\\tk8.2' | |
os.environ['TIX_LIBRARY'] = RootDir + '\\lib\\tix8.1' | |
elif sys.platform == "linux2": | |
sys.path = ['', '../../lib/python-2.0'] | |
os.environ['TCL_LIBRARY'] = RootDir + '/lib/tcl8.2' | |
os.environ['TK_LIBRARY'] = RootDir + '/lib/tk8.2' | |
os.environ['TIX_LIBRARY'] = RootDir + '/lib/tix8.1' | |
elif sys.platform == "solaris": | |
sys.path = ['', '../../lib/python-2.0'] | |
os.environ['TCL_LIBRARY'] = RootDir + '/lib/tcl8.2' | |
os.environ['TK_LIBRARY'] = RootDir + '/lib/tk8.2' | |
os.environ['TIX_LIBRARY'] = RootDir + '/lib/tix8.1' | |
This also adds <root>/lib/python-2.0 to your Python path | |
for any Python files such as _tkinter.pyd you may need. | |
Note that the dynamic libraries (such as tcl82.dll tk82.dll python20.dll | |
under Windows, or libtcl8.2.so and libtcl8.2.so under Unix) are required | |
at program load time, and are searched by the operating system loader | |
before Python can be started. Under Windows, the environment | |
variable PATH is consulted, and under Unix, it may be the | |
environment variable LD_LIBRARY_PATH and/or the system | |
shared library cache (ld.so). An additional preferred directory for | |
finding the dynamic libraries is built into the .dll or .so files at | |
compile time - see the LIB_RUNTIME_DIR variable in the Tcl makefile. | |
The OS must find the dynamic libraries or your frozen program won't start. | |
Usually I make sure that the .so or .dll files are in the same directory | |
as the executable, but this may not be foolproof. | |
A workaround to installing your Tcl library files with your frozen | |
executable 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. An easier approach is to freeze the | |
Tcl/Tk/Tix code into the dynamic libraries using the Tcl ET code, | |
or the Tix Stand-Alone-Module code. Of course, you can also simply | |
require that Tcl/Tk is required on the target installation, but be | |
careful that the version corresponds. | |
There are some caveats using frozen Tkinter applications: | |
Under Windows if you use the -s windows option, writing | |
to stdout or stderr is an error. | |
The Tcl [info nameofexecutable] will be set to where the | |
program was frozen, not where it is run from. | |
The global variables argc and argv do not exist. | |
A warning about shared library modules | |
-------------------------------------- | |
When your Python installation uses shared library modules such as | |
_tkinter.pyd, 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. Or use the approach described in the previous | |
section to declare a library path using sys.path, and place the modules | |
such as _tkinter.pyd there. | |
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 PYTHON20.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 | |
python20.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 | |
python20.lib file is generated in the subdirectory vc40 of the Python | |
source tree). | |
It is possible to create frozen programs that don't have a console | |
window, by specifying the option '-s windows'. See the Usage below. | |
Usage | |
----- | |
Here is a list of all of the options (taken from freeze.__doc__): | |
usage: freeze [options...] script [module]... | |
Options: | |
-p prefix: This is the prefix used when you ran ``make install'' | |
in the Python build directory. | |
(If you never ran this, freeze won't work.) | |
The default is whatever sys.prefix evaluates to. | |
It can also be the top directory of the Python source | |
tree; then -P must point to the build tree. | |
-P exec_prefix: Like -p but this is the 'exec_prefix', used to | |
install objects etc. The default is whatever sys.exec_prefix | |
evaluates to, or the -p argument if given. | |
If -p points to the Python source tree, -P must point | |
to the build tree, if different. | |
-e extension: A directory containing additional .o files that | |
may be used to resolve modules. This directory | |
should also have a Setup file describing the .o files. | |
On Windows, the name of a .INI file describing one | |
or more extensions is passed. | |
More than one -e option may be given. | |
-o dir: Directory where the output files are created; default '.'. | |
-m: Additional arguments are module names instead of filenames. | |
-a package=dir: Additional directories to be added to the package's | |
__path__. Used to simulate directories added by the | |
package at runtime (eg, by OpenGL and win32com). | |
More than one -a option may be given for each package. | |
-l file: Pass the file to the linker (windows only) | |
-d: Debugging mode for the module finder. | |
-q: Make the module finder totally quiet. | |
-h: Print this help message. | |
-x module Exclude the specified module. | |
-i filename: Include a file with additional command line options. Used | |
to prevent command lines growing beyond the capabilities of | |
the shell/OS. All arguments specified in filename | |
are read and the -i option replaced with the parsed | |
params (note - quoting args in this file is NOT supported) | |
-s subsystem: Specify the subsystem (For Windows only.); | |
'console' (default), 'windows', 'service' or 'com_dll' | |
-w: Toggle Windows (NT or 95) behavior. | |
(For debugging only -- on a win32 platform, win32 behavior | |
is automatic.) | |
Arguments: | |
script: The Python script to be executed by the resulting binary. | |
module ...: Additional Python modules (referenced by pathname) | |
that will be included in the resulting binary. These | |
may be .py or .pyc files. If -m is specified, these are | |
module names that are search in the path instead. | |
--Guido van Rossum (home page: http://www.python.org/~guido/) |