THE FREEZE SCRIPT ================= (Directions for Windows NT 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? ---------------------------------------------- Freeze uses a pretty simple-minded algorithm to find the modules that your program uses: given a file containing Python source code, it scans for lines beginning with the word "import" or "from" (possibly preceded by whitespace) and then it knows where to find the module name(s) in those lines. It then recursively scans the source for those modules (if found, and not already processed) in the same way. Freeze will not see import statements hidden behind another statement, like this: if some_test: import M # M not seen or like this: import A; import B; import C # B and C not seen nor will it see import statements constructed using string operations and passed to 'exec', like this: exec "import %s" % "M" # M not seen On the other hand, Freeze will think you are importing a module even if the import statement it sees will never be executed, like this: if 0: import M # M is seen 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 three files: frozen.c, config.c and Makefile. 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. 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 NT ---------------------- Under Windows 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 PYTHON15.DLL (it does not require the standard library of .py files though). 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 python15.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 python15.lib file is generated in the subdirectory vc40 of the Python source tree). Freezing pure GUI applications has not yet been tried; there's a new -s option to specify the subsystem, but only the default ('console') has been tested. Freezing applications using Tkinter works; note that these will require that that _tkinter.dll is available and the right version of Tcl/Tk (the one that was used to build _tkinter.dll) is installed. --Guido van Rossum (home page: http://www.python.org/~guido/)