Tools/freeze/README

   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/)