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