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