blob: 81be2c84326a70d109303718380d6b5865be687f [file] [log] [blame]
Guido van Rossumd8336c21994-10-05 16:13:01 +00001THE FREEZE SCRIPT
2=================
3
Guido van Rossumcef85a21998-03-07 04:51:54 +00004(Directions for Windows are at the end of this file.)
Guido van Rossum7ba3de41997-08-14 02:12:04 +00005
Guido van Rossumd8336c21994-10-05 16:13:01 +00006
7What is Freeze?
8---------------
9
10Freeze make it possible to ship arbitrary Python programs to people
11who don't have Python. The shipped file (called a "frozen" version of
12your Python program) is an executable, so this only works if your
13platform is compatible with that on the receiving end (this is usually
14a matter of having the same major operating system revision and CPU
15type).
16
17The shipped file contains a Python interpreter and large portions of
18the Python run-time. Some measures have been taken to avoid linking
19unneeded modules, but the resulting binary is usually not small.
20
21The Python source code of your program (and of the library modules
22written in Python that it uses) is not included in the binary --
23instead, the compiled byte-code (the instruction stream used
24internally by the interpreter) is incorporated. This gives some
25protection of your Python source code, though not much -- a
26disassembler for Python byte-code is available in the standard Python
27library. At least someone running "strings" on your binary won't see
28the source.
29
30
31How does Freeze know which modules to include?
32----------------------------------------------
33
Guido van Rossumcef85a21998-03-07 04:51:54 +000034Previous versions of Freeze used a pretty simple-minded algorithm to
35find the modules that your program uses, essentially searching for
36lines starting with the word "import". It was pretty easy to trick it
37into making mistakes, either missing valid import statements, or
38mistaking string literals (e.g. doc strings) for import statements.
Guido van Rossumd8336c21994-10-05 16:13:01 +000039
Guido van Rossumcef85a21998-03-07 04:51:54 +000040This has been remedied: Freeze now uses the regular Python parser to
41parse the program (and all its modules) and scans the generated byte
42code for IMPORT instructions. It may still be confused -- it will not
43know about calls to the __import__ built-in function, or about import
44statements constructed on the fly and executed using the 'exec'
45statement, and it will consider import statements even when they are
46unreachable (e.g. "if 0: import foobar").
Guido van Rossumd8336c21994-10-05 16:13:01 +000047
Guido van Rossumcef85a21998-03-07 04:51:54 +000048This new version of Freeze also knows about Python's new package
49import mechanism, and uses exactly the same rules to find imported
50modules and packages. One exception: if you write 'from package
51import *', Python will look into the __all__ variable of the package
52to determine which modules are to be imported, while Freeze will do a
53directory listing.
Guido van Rossumd8336c21994-10-05 16:13:01 +000054
55One tricky issue: Freeze assumes that the Python interpreter and
56environment you're using to run Freeze is the same one that would be
57used to run your program, which should also be the same whose sources
58and installed files you will learn about in the next section. In
59particular, your PYTHONPATH setting should be the same as for running
60your program locally. (Tip: if the program doesn't run when you type
61"python hello.py" there's little chance of getting the frozen version
62to run.)
63
64
65How do I use Freeze?
66--------------------
67
Guido van Rossum96c4dd91996-08-26 05:14:20 +000068Normally, you should be able to use it as follows:
Guido van Rossumd8336c21994-10-05 16:13:01 +000069
70 python freeze.py hello.py
71
72where hello.py is your program and freeze.py is the main file of
73Freeze (in actuality, you'll probably specify an absolute pathname
Guido van Rossum96c4dd91996-08-26 05:14:20 +000074such as /usr/joe/python/Tools/freeze/freeze.py).
Guido van Rossumd8336c21994-10-05 16:13:01 +000075
Guido van Rossumd8336c21994-10-05 16:13:01 +000076
Guido van Rossumd8336c21994-10-05 16:13:01 +000077What do I do next?
78------------------
79
Guido van Rossumbaf06031998-08-25 14:06:55 +000080Freeze creates a number of files: frozen.c, config.c and Makefile,
81plus one file for each Python module that gets included named
82M_<module>.c. To produce the frozen version of your program, you can
83simply type "make". This should produce a binary file. If the
84filename argument to Freeze was "hello.py", the binary will be called
85"hello".
Guido van Rossum96c4dd91996-08-26 05:14:20 +000086
87Note: you can use the -o option to freeze to specify an alternative
88directory where these files are created. This makes it easier to
Guido van Rossumcef85a21998-03-07 04:51:54 +000089clean up after you've shipped the frozen binary. You should invoke
90"make" in the given directory.
91
92
93Freezing Tkinter programs
94-------------------------
95
96Unfortunately, it is currently not possible to freeze programs that
Guido van Rossumecc463a2001-01-03 23:50:59 +000097use Tkinter without a Tcl/Tk installation. The best way to ship a
98frozen Tkinter program is to decide in advance where you are going
99to place the Tcl and Tk library files in the distributed setup, and
100then declare these directories in your frozen Python program using
101the TCL_LIBRARY, TK_LIBRARY and TIX_LIBRARY environment variables.
Guido van Rossumcef85a21998-03-07 04:51:54 +0000102
Guido van Rossumecc463a2001-01-03 23:50:59 +0000103For example, assume you will ship your frozen program in the directory
104<root>/bin/windows-x86 and will place your Tcl library files
105in <root>/lib/tcl8.2 and your Tk library files in <root>/lib/tk8.2. Then
106placing the following lines in your frozen Python script before importing
107Tkinter or Tix would set the environment correctly for Tcl/Tk/Tix:
108
109import os
110import os.path
111RootDir = os.path.dirname(os.path.dirname(os.getcwd()))
112
113import sys
114if sys.platform == "win32":
115 sys.path = ['', '..\\..\\lib\\python-2.0']
116 os.environ['TCL_LIBRARY'] = RootDir + '\\lib\\tcl8.2'
117 os.environ['TK_LIBRARY'] = RootDir + '\\lib\\tk8.2'
118 os.environ['TIX_LIBRARY'] = RootDir + '\\lib\\tix8.1'
119elif sys.platform == "linux2":
120 sys.path = ['', '../../lib/python-2.0']
121 os.environ['TCL_LIBRARY'] = RootDir + '/lib/tcl8.2'
122 os.environ['TK_LIBRARY'] = RootDir + '/lib/tk8.2'
123 os.environ['TIX_LIBRARY'] = RootDir + '/lib/tix8.1'
124elif sys.platform == "solaris":
125 sys.path = ['', '../../lib/python-2.0']
126 os.environ['TCL_LIBRARY'] = RootDir + '/lib/tcl8.2'
127 os.environ['TK_LIBRARY'] = RootDir + '/lib/tk8.2'
128 os.environ['TIX_LIBRARY'] = RootDir + '/lib/tix8.1'
129
130This also adds <root>/lib/python-2.0 to your Python path
131for any Python files such as _tkinter.pyd you may need.
132
133Note that the dynamic libraries (such as tcl82.dll tk82.dll python20.dll
134under Windows, or libtcl8.2.so and libtcl8.2.so under Unix) are required
135at program load time, and are searched by the operating system loader
136before Python can be started. Under Windows, the environment
137variable PATH is consulted, and under Unix, it may be the
Walter Dörwaldf0dfc7a2003-10-20 14:01:56 +0000138environment variable LD_LIBRARY_PATH and/or the system
Guido van Rossumecc463a2001-01-03 23:50:59 +0000139shared library cache (ld.so). An additional preferred directory for
140finding the dynamic libraries is built into the .dll or .so files at
141compile time - see the LIB_RUNTIME_DIR variable in the Tcl makefile.
142The OS must find the dynamic libraries or your frozen program won't start.
143Usually I make sure that the .so or .dll files are in the same directory
144as the executable, but this may not be foolproof.
145
146A workaround to installing your Tcl library files with your frozen
147executable would be possible, in which the Tcl/Tk library files are
Guido van Rossumcef85a21998-03-07 04:51:54 +0000148incorporated in a frozen Python module as string literals and written
149to a temporary location when the program runs; this is currently left
Guido van Rossumecc463a2001-01-03 23:50:59 +0000150as an exercise for the reader. An easier approach is to freeze the
151Tcl/Tk/Tix code into the dynamic libraries using the Tcl ET code,
152or the Tix Stand-Alone-Module code. Of course, you can also simply
153require that Tcl/Tk is required on the target installation, but be
154careful that the version corresponds.
Guido van Rossumcef85a21998-03-07 04:51:54 +0000155
Guido van Rossumecc463a2001-01-03 23:50:59 +0000156There are some caveats using frozen Tkinter applications:
157 Under Windows if you use the -s windows option, writing
158to stdout or stderr is an error.
159 The Tcl [info nameofexecutable] will be set to where the
160program was frozen, not where it is run from.
161 The global variables argc and argv do not exist.
Guido van Rossumcef85a21998-03-07 04:51:54 +0000162
163
Guido van Rossumecc463a2001-01-03 23:50:59 +0000164A warning about shared library modules
165--------------------------------------
Guido van Rossumcef85a21998-03-07 04:51:54 +0000166
Guido van Rossumecc463a2001-01-03 23:50:59 +0000167When your Python installation uses shared library modules such as
168_tkinter.pyd, these will not be incorporated in the frozen program.
169 Again, the frozen program will work when you test it, but it won't
170 work when you ship it to a site without a Python installation.
Guido van Rossumcef85a21998-03-07 04:51:54 +0000171
172Freeze prints a warning when this is the case at the end of the
173freezing process:
174
175 Warning: unknown modules remain: ...
176
177When this occurs, the best thing to do is usually to rebuild Python
Guido van Rossumecc463a2001-01-03 23:50:59 +0000178using static linking only. Or use the approach described in the previous
179section to declare a library path using sys.path, and place the modules
180such as _tkinter.pyd there.
Guido van Rossumd8336c21994-10-05 16:13:01 +0000181
182
Guido van Rossumbf6bdb01995-04-05 10:59:20 +0000183Troubleshooting
184---------------
Guido van Rossumd8336c21994-10-05 16:13:01 +0000185
Guido van Rossumbf6bdb01995-04-05 10:59:20 +0000186If you have trouble using Freeze for a large program, it's probably
Guido van Rossum96c4dd91996-08-26 05:14:20 +0000187best to start playing with a really simple program first (like the file
188hello.py). If you can't get that to work there's something
189fundamentally wrong -- perhaps you haven't installed Python. To do a
190proper install, you should do "make install" in the Python root
191directory.
Guido van Rossumbf6bdb01995-04-05 10:59:20 +0000192
193
Guido van Rossumcef85a21998-03-07 04:51:54 +0000194Usage under Windows 95 or NT
195----------------------------
Guido van Rossum7ba3de41997-08-14 02:12:04 +0000196
Guido van Rossumcef85a21998-03-07 04:51:54 +0000197Under Windows 95 or NT, you *must* use the -p option and point it to
198the top of the Python source tree.
Guido van Rossum7ba3de41997-08-14 02:12:04 +0000199
200WARNING: the resulting executable is not self-contained; it requires
Peter Schneider-Kamp332c59c2000-07-24 16:02:00 +0000201the Python DLL, currently PYTHON20.DLL (it does not require the
Guido van Rossumcef85a21998-03-07 04:51:54 +0000202standard library of .py files though). It may also require one or
203more extension modules loaded from .DLL or .PYD files; the module
204names are printed in the warning message about remaining unknown
205modules.
Guido van Rossum7ba3de41997-08-14 02:12:04 +0000206
207The driver script generates a Makefile that works with the Microsoft
208command line C compiler (CL). To compile, run "nmake"; this will
209build a target "hello.exe" if the source was "hello.py". Only the
210files frozenmain.c and frozen.c are used; no config.c is generated or
211used, since the standard DLL is used.
212
213In order for this to work, you must have built Python using the VC++
214(Developer Studio) 5.0 compiler. The provided project builds
Peter Schneider-Kamp332c59c2000-07-24 16:02:00 +0000215python20.lib in the subdirectory pcbuild\Release of thje Python source
Guido van Rossum7ba3de41997-08-14 02:12:04 +0000216tree, and this is where the generated Makefile expects it to be. If
217this is not the case, you can edit the Makefile or (probably better)
218winmakemakefile.py (e.g., if you are using the 4.2 compiler, the
Peter Schneider-Kamp332c59c2000-07-24 16:02:00 +0000219python20.lib file is generated in the subdirectory vc40 of the Python
Guido van Rossum7ba3de41997-08-14 02:12:04 +0000220source tree).
221
Guido van Rossumcef85a21998-03-07 04:51:54 +0000222It is possible to create frozen programs that don't have a console
Guido van Rossumecc463a2001-01-03 23:50:59 +0000223window, by specifying the option '-s windows'. See the Usage below.
224
225Usage
226-----
227
228Here is a list of all of the options (taken from freeze.__doc__):
229
230usage: freeze [options...] script [module]...
231
232Options:
233-p prefix: This is the prefix used when you ran ``make install''
234 in the Python build directory.
235 (If you never ran this, freeze won't work.)
236 The default is whatever sys.prefix evaluates to.
237 It can also be the top directory of the Python source
238 tree; then -P must point to the build tree.
239
240-P exec_prefix: Like -p but this is the 'exec_prefix', used to
241 install objects etc. The default is whatever sys.exec_prefix
242 evaluates to, or the -p argument if given.
243 If -p points to the Python source tree, -P must point
244 to the build tree, if different.
245
246-e extension: A directory containing additional .o files that
247 may be used to resolve modules. This directory
248 should also have a Setup file describing the .o files.
249 On Windows, the name of a .INI file describing one
250 or more extensions is passed.
251 More than one -e option may be given.
252
253-o dir: Directory where the output files are created; default '.'.
254
255-m: Additional arguments are module names instead of filenames.
256
257-a package=dir: Additional directories to be added to the package's
258 __path__. Used to simulate directories added by the
259 package at runtime (eg, by OpenGL and win32com).
260 More than one -a option may be given for each package.
261
262-l file: Pass the file to the linker (windows only)
263
264-d: Debugging mode for the module finder.
265
266-q: Make the module finder totally quiet.
267
268-h: Print this help message.
269
270-x module Exclude the specified module.
271
272-i filename: Include a file with additional command line options. Used
273 to prevent command lines growing beyond the capabilities of
274 the shell/OS. All arguments specified in filename
275 are read and the -i option replaced with the parsed
276 params (note - quoting args in this file is NOT supported)
277
278-s subsystem: Specify the subsystem (For Windows only.);
279 'console' (default), 'windows', 'service' or 'com_dll'
280
281-w: Toggle Windows (NT or 95) behavior.
282 (For debugging only -- on a win32 platform, win32 behavior
283 is automatic.)
284
285Arguments:
286
287script: The Python script to be executed by the resulting binary.
288
289module ...: Additional Python modules (referenced by pathname)
290 that will be included in the resulting binary. These
291 may be .py or .pyc files. If -m is specified, these are
292 module names that are search in the path instead.
293
294
Guido van Rossum7ba3de41997-08-14 02:12:04 +0000295
Guido van Rossum96c4dd91996-08-26 05:14:20 +0000296--Guido van Rossum (home page: http://www.python.org/~guido/)