diff options
Diffstat (limited to 'intern/python/freeze/README')
| -rw-r--r-- | intern/python/freeze/README | 173 |
1 files changed, 173 insertions, 0 deletions
diff --git a/intern/python/freeze/README b/intern/python/freeze/README new file mode 100644 index 00000000000..fcdd67029a5 --- /dev/null +++ b/intern/python/freeze/README @@ -0,0 +1,173 @@ +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. It *seems* to work, but when you ship the frozen program +to a site without a Tcl/Tk installation, it will fail with a complaint +about missing Tcl/Tk initialization files. + +A workaround 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. (If you implement this, please post to +the Python newsgroup!) + +Of course, you can also simply require that Tcl/Tk is required on the +target installation. + + +A warning against shared library modules +---------------------------------------- + +When your Python installation uses shared library modules, 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. + + +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). + +You can freeze programs that use Tkinter, but Tcl/Tk must be installed +on the target system. + +It is possible to create frozen programs that don't have a console +window, by specifying the option '-s windows'. + +--Guido van Rossum (home page: http://www.python.org/~guido/) |