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.  It *seems* to work, but when you ship the frozen program
  98 to a site without a Tcl/Tk installation, it will fail with a complaint
  99 about missing Tcl/Tk initialization files.
 100
 101 A workaround would be possible, in which the Tcl/Tk library files are
 102 incorporated in a frozen Python module as string literals and written
 103 to a temporary location when the program runs; this is currently left
 104 as an exercise for the reader.  (If you implement this, please post to
 105 the Python newsgroup!)
 106
 107 Of course, you can also simply require that Tcl/Tk is required on the
 108 target installation.
 109
 110
 111 A warning against shared library modules
 112 ----------------------------------------
 113
 114 When your Python installation uses shared library modules, these will
 115 not be incorporated in the frozen program.  Again, the frozen program
 116 will work when you test it, but it won't work when you ship it to a
 117 site without a Python installation.
 118
 119 Freeze prints a warning when this is the case at the end of the
 120 freezing process:
 121
 122         Warning: unknown modules remain: ...
 123
 124 When this occurs, the best thing to do is usually to rebuild Python
 125 using static linking only.
 126
 127
 128 Troubleshooting
 129 ---------------
 130
 131 If you have trouble using Freeze for a large program, it's probably
 132 best to start playing with a really simple program first (like the file
 133 hello.py).  If you can't get that to work there's something
 134 fundamentally wrong -- perhaps you haven't installed Python.  To do a
 135 proper install, you should do "make install" in the Python root
 136 directory.
 137
 138
 139 Usage under Windows 95 or NT
 140 ----------------------------
 141
 142 Under Windows 95 or NT, you *must* use the -p option and point it to
 143 the top of the Python source tree.
 144
 145 WARNING: the resulting executable is not self-contained; it requires
 146 the Python DLL, currently PYTHON20.DLL (it does not require the
 147 standard library of .py files though).  It may also require one or
 148 more extension modules loaded from .DLL or .PYD files; the module
 149 names are printed in the warning message about remaining unknown
 150 modules.
 151
 152 The driver script generates a Makefile that works with the Microsoft
 153 command line C compiler (CL).  To compile, run "nmake"; this will
 154 build a target "hello.exe" if the source was "hello.py".  Only the
 155 files frozenmain.c and frozen.c are used; no config.c is generated or
 156 used, since the standard DLL is used.
 157
 158 In order for this to work, you must have built Python using the VC++
 159 (Developer Studio) 5.0 compiler.  The provided project builds
 160 python20.lib in the subdirectory pcbuild\Release of thje Python source
 161 tree, and this is where the generated Makefile expects it to be.  If
 162 this is not the case, you can edit the Makefile or (probably better)
 163 winmakemakefile.py (e.g., if you are using the 4.2 compiler, the
 164 python20.lib file is generated in the subdirectory vc40 of the Python
 165 source tree).
 166
 167 You can freeze programs that use Tkinter, but Tcl/Tk must be installed
 168 on the target system.
 169
 170 It is possible to create frozen programs that don't have a console
 171 window, by specifying the option '-s windows'.
 172
 173 --Guido van Rossum (home page: http://www.python.org/~guido/)