Adapted to the new situation.

1 files changed, 71 insertions, 39 deletions

diff --git a/Tools/freeze/README b/Tools/freeze/README
index 1bc864b..09a05d7 100644
--- a/Tools/freeze/README
+++ b/Tools/freeze/README
@@ -1,7 +1,7 @@
 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?
@@ -31,32 +31,26 @@ 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
+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
@@ -90,7 +84,43 @@ 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.
+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
@@ -104,15 +134,18 @@ proper install, you should do "make install" in the Python root
 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
@@ -129,11 +162,10 @@ 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.
+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/)