1THE FREEZE SCRIPT 2================= 3 4(Directions for Windows are at the end of this file.) 5 6 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 34Previous 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. 39 40This 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"). 47 48This 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. 54 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 68Normally, you should be able to use it as follows: 69 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 74such as /usr/joe/python/Tools/freeze/freeze.py). 75 76 77What do I do next? 78------------------ 79 80Freeze 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". 86 87Note: you can use the -o option to freeze to specify an alternative 88directory where these files are created. This makes it easier to 89clean 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 97use 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. 102 103For 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 138environment variable LD_LIBRARY_PATH and/or the system 139shared 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 148incorporated in a frozen Python module as string literals and written 149to a temporary location when the program runs; this is currently left 150as 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. 155 156There 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. 162 163 164A warning about shared library modules 165-------------------------------------- 166 167When 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. 171 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 178using 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. 181 182 183Troubleshooting 184--------------- 185 186If you have trouble using Freeze for a large program, it's probably 187best 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. 192 193 194Usage under Windows 95 or NT 195---------------------------- 196 197Under Windows 95 or NT, you *must* use the -p option and point it to 198the top of the Python source tree. 199 200WARNING: the resulting executable is not self-contained; it requires 201the Python DLL, currently PYTHON20.DLL (it does not require the 202standard 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. 206 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 215python20.lib in the subdirectory pcbuild\Release of thje Python source 216tree, 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 219python20.lib file is generated in the subdirectory vc40 of the Python 220source tree). 221 222It is possible to create frozen programs that don't have a console 223window, 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 295 296--Guido van Rossum (home page: http://www.python.org/~guido/) 297