THE FREEZE SCRIPT
=================
-(Directions for Windows NT are at the end of this file.)
+(Directions for Windows are at the end of this file.)
What is Freeze?
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
+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
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.
+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
directory.
-Usage under Windows NT
-----------------------
+Usage under Windows 95 or NT
+----------------------------
-Under Windows NT, you *must* use the -p option and point it to the top
-of the Python source tree.
+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 PYTHON15.DLL (it does not require the
-standard library of .py files though).
+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
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.
+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/)
projects / python / commitdiff