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, TK_LIBRARY and TIX_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 or Tix would set the environment correctly for Tcl/Tk/Tix: 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 os.environ['TIX_LIBRARY'] = RootDir + '\\lib\\tix8.1' 119 elif 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' 124 elif 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 130 This also adds <root>/lib/python-2.0 to your Python path 131 for any Python files such as _tkinter.pyd you may need. 132 133 Note that the dynamic libraries (such as tcl82.dll tk82.dll python20.dll 134 under Windows, or libtcl8.2.so and libtcl8.2.so under Unix) are required 135 at program load time, and are searched by the operating system loader 136 before Python can be started. Under Windows, the environment 137 variable PATH is consulted, and under Unix, it may be the 138 environment variable LD_LIBRARY_PATH and/or the system 139 shared library cache (ld.so). An additional preferred directory for 140 finding the dynamic libraries is built into the .dll or .so files at 141 compile time - see the LIB_RUNTIME_DIR variable in the Tcl makefile. 142 The OS must find the dynamic libraries or your frozen program won't start. 143 Usually I make sure that the .so or .dll files are in the same directory 144 as the executable, but this may not be foolproof. 145 146 A workaround to installing your Tcl library files with your frozen 147 executable would be possible, in which the Tcl/Tk library files are 148 incorporated in a frozen Python module as string literals and written 149 to a temporary location when the program runs; this is currently left 150 as an exercise for the reader. An easier approach is to freeze the 151 Tcl/Tk/Tix code into the dynamic libraries using the Tcl ET code, 152 or the Tix Stand-Alone-Module code. Of course, you can also simply 153 require that Tcl/Tk is required on the target installation, but be 154 careful that the version corresponds. 155 156 There are some caveats using frozen Tkinter applications: 157 Under Windows if you use the -s windows option, writing 158 to stdout or stderr is an error. 159 The Tcl [info nameofexecutable] will be set to where the 160 program was frozen, not where it is run from. 161 The global variables argc and argv do not exist. 162 163 164 A warning about shared library modules 165 -------------------------------------- 166 167 When 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 172 Freeze prints a warning when this is the case at the end of the 173 freezing process: 174 175 Warning: unknown modules remain: ... 176 177 When this occurs, the best thing to do is usually to rebuild Python 178 using static linking only. Or use the approach described in the previous 179 section to declare a library path using sys.path, and place the modules 180 such as _tkinter.pyd there. 181 182 183 Troubleshooting 184 --------------- 185 186 If you have trouble using Freeze for a large program, it's probably 187 best to start playing with a really simple program first (like the file 188 hello.py). If you can't get that to work there's something 189 fundamentally wrong -- perhaps you haven't installed Python. To do a 190 proper install, you should do "make install" in the Python root 191 directory. 192 193 194 Usage under Windows 95 or NT 195 ---------------------------- 196 197 Under Windows 95 or NT, you *must* use the -p option and point it to 198 the top of the Python source tree. 199 200 WARNING: the resulting executable is not self-contained; it requires 201 the Python DLL, currently PYTHON20.DLL (it does not require the 202 standard library of .py files though). It may also require one or 203 more extension modules loaded from .DLL or .PYD files; the module 204 names are printed in the warning message about remaining unknown 205 modules. 206 207 The driver script generates a Makefile that works with the Microsoft 208 command line C compiler (CL). To compile, run "nmake"; this will 209 build a target "hello.exe" if the source was "hello.py". Only the 210 files frozenmain.c and frozen.c are used; no config.c is generated or 211 used, since the standard DLL is used. 212 213 In order for this to work, you must have built Python using the VC++ 214 (Developer Studio) 5.0 compiler. The provided project builds 215 python20.lib in the subdirectory pcbuild\Release of thje Python source 216 tree, and this is where the generated Makefile expects it to be. If 217 this is not the case, you can edit the Makefile or (probably better) 218 winmakemakefile.py (e.g., if you are using the 4.2 compiler, the 219 python20.lib file is generated in the subdirectory vc40 of the Python 220 source tree). 221 222 It is possible to create frozen programs that don't have a console 223 window, by specifying the option '-s windows'. See the Usage below. 224 225 Usage 226 ----- 227 228 Here is a list of all of the options (taken from freeze.__doc__): 229 230 usage: freeze [options...] script [module]... 231 232 Options: 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 285 Arguments: 286 287 script: The Python script to be executed by the resulting binary. 288 289 module ...: 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
