/Tools/freeze/README
http://unladen-swallow.googlecode.com/ · #! · 296 lines · 226 code · 70 blank · 0 comment · 0 complexity · e8fb88d17e06b1049fab99b3f747bf0e MD5 · raw file
- THE FREEZE SCRIPT
- =================
- (Directions for Windows are at the end of this file.)
- What is Freeze?
- ---------------
- Freeze make it possible to ship arbitrary Python programs to people
- who don't have Python. The shipped file (called a "frozen" version of
- your Python program) is an executable, so this only works if your
- platform is compatible with that on the receiving end (this is usually
- a matter of having the same major operating system revision and CPU
- type).
- The shipped file contains a Python interpreter and large portions of
- the Python run-time. Some measures have been taken to avoid linking
- unneeded modules, but the resulting binary is usually not small.
- The Python source code of your program (and of the library modules
- written in Python that it uses) is not included in the binary --
- instead, the compiled byte-code (the instruction stream used
- internally by the interpreter) is incorporated. This gives some
- protection of your Python source code, though not much -- a
- disassembler for Python byte-code is available in the standard Python
- library. At least someone running "strings" on your binary won't see
- the source.
- How does Freeze know which modules to include?
- ----------------------------------------------
- Previous versions of Freeze used a pretty simple-minded algorithm to
- find the modules that your program uses, essentially searching for
- lines starting with the word "import". It was pretty easy to trick it
- into making mistakes, either missing valid import statements, or
- mistaking string literals (e.g. doc strings) for import statements.
- This has been remedied: Freeze now uses the regular Python parser to
- parse the program (and all its modules) and scans the generated byte
- code for IMPORT instructions. It may still be confused -- it will not
- know about calls to the __import__ built-in function, or about import
- statements constructed on the fly and executed using the 'exec'
- statement, and it will consider import statements even when they are
- unreachable (e.g. "if 0: import foobar").
- This new version of Freeze also knows about Python's new package
- import mechanism, and uses exactly the same rules to find imported
- modules and packages. One exception: if you write 'from package
- import *', Python will look into the __all__ variable of the package
- to determine which modules are to be imported, while Freeze will do a
- directory listing.
- One tricky issue: Freeze assumes that the Python interpreter and
- environment you're using to run Freeze is the same one that would be
- used to run your program, which should also be the same whose sources
- and installed files you will learn about in the next section. In
- particular, your PYTHONPATH setting should be the same as for running
- your program locally. (Tip: if the program doesn't run when you type
- "python hello.py" there's little chance of getting the frozen version
- to run.)
- How do I use Freeze?
- --------------------
- Normally, you should be able to use it as follows:
- python freeze.py hello.py
- where hello.py is your program and freeze.py is the main file of
- Freeze (in actuality, you'll probably specify an absolute pathname
- such as /usr/joe/python/Tools/freeze/freeze.py).
- What do I do next?
- ------------------
- Freeze creates a number of files: frozen.c, config.c and Makefile,
- plus one file for each Python module that gets included named
- M_<module>.c. To produce the frozen version of your program, you can
- simply type "make". This should produce a binary file. If the
- filename argument to Freeze was "hello.py", the binary will be called
- "hello".
- Note: you can use the -o option to freeze to specify an alternative
- directory where these files are created. This makes it easier to
- clean up after you've shipped the frozen binary. You should invoke
- "make" in the given directory.
- Freezing Tkinter programs
- -------------------------
- Unfortunately, it is currently not possible to freeze programs that
- use Tkinter without a Tcl/Tk installation. The best way to ship a
- frozen Tkinter program is to decide in advance where you are going
- to place the Tcl and Tk library files in the distributed setup, and
- then declare these directories in your frozen Python program using
- the TCL_LIBRARY, TK_LIBRARY and TIX_LIBRARY environment variables.
- For example, assume you will ship your frozen program in the directory
- <root>/bin/windows-x86 and will place your Tcl library files
- in <root>/lib/tcl8.2 and your Tk library files in <root>/lib/tk8.2. Then
- placing the following lines in your frozen Python script before importing
- Tkinter or Tix would set the environment correctly for Tcl/Tk/Tix:
- import os
- import os.path
- RootDir = os.path.dirname(os.path.dirname(os.getcwd()))
- import sys
- if sys.platform == "win32":
- sys.path = ['', '..\\..\\lib\\python-2.0']
- os.environ['TCL_LIBRARY'] = RootDir + '\\lib\\tcl8.2'
- os.environ['TK_LIBRARY'] = RootDir + '\\lib\\tk8.2'
- os.environ['TIX_LIBRARY'] = RootDir + '\\lib\\tix8.1'
- elif sys.platform == "linux2":
- sys.path = ['', '../../lib/python-2.0']
- os.environ['TCL_LIBRARY'] = RootDir + '/lib/tcl8.2'
- os.environ['TK_LIBRARY'] = RootDir + '/lib/tk8.2'
- os.environ['TIX_LIBRARY'] = RootDir + '/lib/tix8.1'
- elif sys.platform == "solaris":
- sys.path = ['', '../../lib/python-2.0']
- os.environ['TCL_LIBRARY'] = RootDir + '/lib/tcl8.2'
- os.environ['TK_LIBRARY'] = RootDir + '/lib/tk8.2'
- os.environ['TIX_LIBRARY'] = RootDir + '/lib/tix8.1'
- This also adds <root>/lib/python-2.0 to your Python path
- for any Python files such as _tkinter.pyd you may need.
- Note that the dynamic libraries (such as tcl82.dll tk82.dll python20.dll
- under Windows, or libtcl8.2.so and libtcl8.2.so under Unix) are required
- at program load time, and are searched by the operating system loader
- before Python can be started. Under Windows, the environment
- variable PATH is consulted, and under Unix, it may be the
- environment variable LD_LIBRARY_PATH and/or the system
- shared library cache (ld.so). An additional preferred directory for
- finding the dynamic libraries is built into the .dll or .so files at
- compile time - see the LIB_RUNTIME_DIR variable in the Tcl makefile.
- The OS must find the dynamic libraries or your frozen program won't start.
- Usually I make sure that the .so or .dll files are in the same directory
- as the executable, but this may not be foolproof.
- A workaround to installing your Tcl library files with your frozen
- executable would be possible, in which the Tcl/Tk library files are
- incorporated in a frozen Python module as string literals and written
- to a temporary location when the program runs; this is currently left
- as an exercise for the reader. An easier approach is to freeze the
- Tcl/Tk/Tix code into the dynamic libraries using the Tcl ET code,
- or the Tix Stand-Alone-Module code. Of course, you can also simply
- require that Tcl/Tk is required on the target installation, but be
- careful that the version corresponds.
- There are some caveats using frozen Tkinter applications:
- Under Windows if you use the -s windows option, writing
- to stdout or stderr is an error.
- The Tcl [info nameofexecutable] will be set to where the
- program was frozen, not where it is run from.
- The global variables argc and argv do not exist.
- A warning about shared library modules
- --------------------------------------
- When your Python installation uses shared library modules such as
- _tkinter.pyd, these will not be incorporated in the frozen program.
- Again, the frozen program will work when you test it, but it won't
- work when you ship it to a site without a Python installation.
- Freeze prints a warning when this is the case at the end of the
- freezing process:
- Warning: unknown modules remain: ...
- When this occurs, the best thing to do is usually to rebuild Python
- using static linking only. Or use the approach described in the previous
- section to declare a library path using sys.path, and place the modules
- such as _tkinter.pyd there.
- Troubleshooting
- ---------------
- If you have trouble using Freeze for a large program, it's probably
- best to start playing with a really simple program first (like the file
- hello.py). If you can't get that to work there's something
- fundamentally wrong -- perhaps you haven't installed Python. To do a
- proper install, you should do "make install" in the Python root
- directory.
- Usage under Windows 95 or NT
- ----------------------------
- Under Windows 95 or NT, you *must* use the -p option and point it to
- the top of the Python source tree.
- WARNING: the resulting executable is not self-contained; it requires
- the Python DLL, currently PYTHON20.DLL (it does not require the
- standard library of .py files though). It may also require one or
- more extension modules loaded from .DLL or .PYD files; the module
- names are printed in the warning message about remaining unknown
- modules.
- The driver script generates a Makefile that works with the Microsoft
- command line C compiler (CL). To compile, run "nmake"; this will
- build a target "hello.exe" if the source was "hello.py". Only the
- files frozenmain.c and frozen.c are used; no config.c is generated or
- used, since the standard DLL is used.
- In order for this to work, you must have built Python using the VC++
- (Developer Studio) 5.0 compiler. The provided project builds
- python20.lib in the subdirectory pcbuild\Release of thje Python source
- tree, and this is where the generated Makefile expects it to be. If
- this is not the case, you can edit the Makefile or (probably better)
- winmakemakefile.py (e.g., if you are using the 4.2 compiler, the
- python20.lib file is generated in the subdirectory vc40 of the Python
- source tree).
- It is possible to create frozen programs that don't have a console
- window, by specifying the option '-s windows'. See the Usage below.
- Usage
- -----
- Here is a list of all of the options (taken from freeze.__doc__):
- usage: freeze [options...] script [module]...
- Options:
- -p prefix: This is the prefix used when you ran ``make install''
- in the Python build directory.
- (If you never ran this, freeze won't work.)
- The default is whatever sys.prefix evaluates to.
- It can also be the top directory of the Python source
- tree; then -P must point to the build tree.
- -P exec_prefix: Like -p but this is the 'exec_prefix', used to
- install objects etc. The default is whatever sys.exec_prefix
- evaluates to, or the -p argument if given.
- If -p points to the Python source tree, -P must point
- to the build tree, if different.
- -e extension: A directory containing additional .o files that
- may be used to resolve modules. This directory
- should also have a Setup file describing the .o files.
- On Windows, the name of a .INI file describing one
- or more extensions is passed.
- More than one -e option may be given.
- -o dir: Directory where the output files are created; default '.'.
- -m: Additional arguments are module names instead of filenames.
- -a package=dir: Additional directories to be added to the package's
- __path__. Used to simulate directories added by the
- package at runtime (eg, by OpenGL and win32com).
- More than one -a option may be given for each package.
- -l file: Pass the file to the linker (windows only)
- -d: Debugging mode for the module finder.
- -q: Make the module finder totally quiet.
- -h: Print this help message.
- -x module Exclude the specified module.
- -i filename: Include a file with additional command line options. Used
- to prevent command lines growing beyond the capabilities of
- the shell/OS. All arguments specified in filename
- are read and the -i option replaced with the parsed
- params (note - quoting args in this file is NOT supported)
- -s subsystem: Specify the subsystem (For Windows only.);
- 'console' (default), 'windows', 'service' or 'com_dll'
-
- -w: Toggle Windows (NT or 95) behavior.
- (For debugging only -- on a win32 platform, win32 behavior
- is automatic.)
- Arguments:
- script: The Python script to be executed by the resulting binary.
- module ...: Additional Python modules (referenced by pathname)
- that will be included in the resulting binary. These
- may be .py or .pyc files. If -m is specified, these are
- module names that are search in the path instead.
- --Guido van Rossum (home page: http://www.python.org/~guido/)