diff options
| -rw-r--r-- | Tools/freeze/README | 110 |
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/) |