mirror of https://github.com/python/cpython
298 lines
12 KiB
Plaintext
298 lines
12 KiB
Plaintext
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 without a Tcl/Tk installation. The best way to ship a
|
|
frozen Tkinter program is to decide in advance where you are going
|
|
to place the Tcl and Tk library files in the distributed setup, and
|
|
then declare these directories in your frozen Python program using
|
|
the TCL_LIBRARY and TK_LIBRARY environment variables.
|
|
|
|
For example, assume you will ship your frozen program in the directory
|
|
<root>/bin/windows-x86 and will place your Tcl library files
|
|
in <root>/lib/tcl8.2 and your Tk library files in <root>/lib/tk8.2. Then
|
|
placing the following lines in your frozen Python script before importing
|
|
tkinter would set the environment correctly for Tcl/Tk:
|
|
|
|
import os
|
|
import os.path
|
|
RootDir = os.path.dirname(os.path.dirname(os.getcwd()))
|
|
|
|
import sys
|
|
if sys.platform == "win32":
|
|
sys.path = ['', '..\\..\\lib\\python-2.0']
|
|
os.environ['TCL_LIBRARY'] = RootDir + '\\lib\\tcl8.2'
|
|
os.environ['TK_LIBRARY'] = RootDir + '\\lib\\tk8.2'
|
|
elif sys.platform == "linux2":
|
|
sys.path = ['', '../../lib/python-2.0']
|
|
os.environ['TCL_LIBRARY'] = RootDir + '/lib/tcl8.2'
|
|
os.environ['TK_LIBRARY'] = RootDir + '/lib/tk8.2'
|
|
elif sys.platform == "solaris":
|
|
sys.path = ['', '../../lib/python-2.0']
|
|
os.environ['TCL_LIBRARY'] = RootDir + '/lib/tcl8.2'
|
|
os.environ['TK_LIBRARY'] = RootDir + '/lib/tk8.2'
|
|
|
|
This also adds <root>/lib/python-2.0 to your Python path
|
|
for any Python files such as _tkinter.pyd you may need.
|
|
|
|
Note that the dynamic libraries (such as tcl82.dll tk82.dll python20.dll
|
|
under Windows, or libtcl8.2.so and libtcl8.2.so under Unix) are required
|
|
at program load time, and are searched by the operating system loader
|
|
before Python can be started. Under Windows, the environment
|
|
variable PATH is consulted, and under Unix, it may be the
|
|
environment variable LD_LIBRARY_PATH and/or the system
|
|
shared library cache (ld.so). An additional preferred directory for
|
|
finding the dynamic libraries is built into the .dll or .so files at
|
|
compile time - see the LIB_RUNTIME_DIR variable in the Tcl makefile.
|
|
The OS must find the dynamic libraries or your frozen program won't start.
|
|
Usually I make sure that the .so or .dll files are in the same directory
|
|
as the executable, but this may not be foolproof.
|
|
|
|
A workaround to installing your Tcl library files with your frozen
|
|
executable 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. An easier approach is to freeze the
|
|
Tcl/Tk code into the dynamic libraries using the Tcl ET code.
|
|
Of course, you can also simply require that Tcl/Tk is required on the
|
|
target installation, but be careful that the version corresponds.
|
|
|
|
There are some caveats using frozen Tkinter applications:
|
|
Under Windows if you use the -s windows option, writing
|
|
to stdout or stderr is an error.
|
|
The Tcl [info nameofexecutable] will be set to where the
|
|
program was frozen, not where it is run from.
|
|
The global variables argc and argv do not exist.
|
|
|
|
|
|
A warning about shared library modules
|
|
--------------------------------------
|
|
|
|
When your Python installation uses shared library modules such as
|
|
_tkinter.pyd, 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. Or use the approach described in the previous
|
|
section to declare a library path using sys.path, and place the modules
|
|
such as _tkinter.pyd there.
|
|
|
|
|
|
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).
|
|
|
|
It is possible to create frozen programs that don't have a console
|
|
window, by specifying the option '-s windows'. See the Usage below.
|
|
|
|
Usage under macOS
|
|
-----------------
|
|
|
|
On macOS the freeze tool is not supported for framework builds.
|
|
|
|
Usage
|
|
-----
|
|
|
|
Here is a list of all of the options (taken from freeze.__doc__):
|
|
|
|
usage: freeze [options...] script [module]...
|
|
|
|
Options:
|
|
-p prefix: This is the prefix used when you ran ``make install''
|
|
in the Python build directory.
|
|
(If you never ran this, freeze won't work.)
|
|
The default is whatever sys.prefix evaluates to.
|
|
It can also be the top directory of the Python source
|
|
tree; then -P must point to the build tree.
|
|
|
|
-P exec_prefix: Like -p but this is the 'exec_prefix', used to
|
|
install objects etc. The default is whatever sys.exec_prefix
|
|
evaluates to, or the -p argument if given.
|
|
If -p points to the Python source tree, -P must point
|
|
to the build tree, if different.
|
|
|
|
-e extension: A directory containing additional .o files that
|
|
may be used to resolve modules. This directory
|
|
should also have a Setup file describing the .o files.
|
|
On Windows, the name of a .INI file describing one
|
|
or more extensions is passed.
|
|
More than one -e option may be given.
|
|
|
|
-o dir: Directory where the output files are created; default '.'.
|
|
|
|
-m: Additional arguments are module names instead of filenames.
|
|
|
|
-a package=dir: Additional directories to be added to the package's
|
|
__path__. Used to simulate directories added by the
|
|
package at runtime (eg, by OpenGL and win32com).
|
|
More than one -a option may be given for each package.
|
|
|
|
-l file: Pass the file to the linker (windows only)
|
|
|
|
-d: Debugging mode for the module finder.
|
|
|
|
-q: Make the module finder totally quiet.
|
|
|
|
-h: Print this help message.
|
|
|
|
-x module Exclude the specified module.
|
|
|
|
-i filename: Include a file with additional command line options. Used
|
|
to prevent command lines growing beyond the capabilities of
|
|
the shell/OS. All arguments specified in filename
|
|
are read and the -i option replaced with the parsed
|
|
params (note - quoting args in this file is NOT supported)
|
|
|
|
-s subsystem: Specify the subsystem (For Windows only.);
|
|
'console' (default), 'windows', 'service' or 'com_dll'
|
|
|
|
-w: Toggle Windows (NT or 95) behavior.
|
|
(For debugging only -- on a win32 platform, win32 behavior
|
|
is automatic.)
|
|
|
|
Arguments:
|
|
|
|
script: The Python script to be executed by the resulting binary.
|
|
|
|
module ...: Additional Python modules (referenced by pathname)
|
|
that will be included in the resulting binary. These
|
|
may be .py or .pyc files. If -m is specified, these are
|
|
module names that are search in the path instead.
|
|
|
|
|
|
|
|
--Guido van Rossum (home page: https://www.python.org/~guido/)
|