Debian Codegraph @

Tools/freeze/README

raw
1 THE FREEZE SCRIPT
2 =================
3
4 (Directions for Windows are at the end of this file.)
5
6
7 What is Freeze?
8 ---------------
9
10 Freeze make it possible to ship arbitrary Python programs to people
11 who don't have Python. The shipped file (called a "frozen" version of
12 your Python program) is an executable, so this only works if your
13 platform is compatible with that on the receiving end (this is usually
14 a matter of having the same major operating system revision and CPU
15 type).
16
17 The shipped file contains a Python interpreter and large portions of
18 the Python run-time. Some measures have been taken to avoid linking
19 unneeded modules, but the resulting binary is usually not small.
20
21 The Python source code of your program (and of the library modules
22 written in Python that it uses) is not included in the binary --
23 instead, the compiled byte-code (the instruction stream used
24 internally by the interpreter) is incorporated. This gives some
25 protection of your Python source code, though not much -- a
26 disassembler for Python byte-code is available in the standard Python
27 library. At least someone running "strings" on your binary won't see
28 the source.
29
30
31 How does Freeze know which modules to include?
32 ----------------------------------------------
33
34 Previous versions of Freeze used a pretty simple-minded algorithm to
35 find the modules that your program uses, essentially searching for
36 lines starting with the word "import". It was pretty easy to trick it
37 into making mistakes, either missing valid import statements, or
38 mistaking string literals (e.g. doc strings) for import statements.
39
40 This has been remedied: Freeze now uses the regular Python parser to
41 parse the program (and all its modules) and scans the generated byte
42 code for IMPORT instructions. It may still be confused -- it will not
43 know about calls to the __import__ built-in function, or about import
44 statements constructed on the fly and executed using the 'exec'
45 statement, and it will consider import statements even when they are
46 unreachable (e.g. "if 0: import foobar").
47
48 This new version of Freeze also knows about Python's new package
49 import mechanism, and uses exactly the same rules to find imported
50 modules and packages. One exception: if you write 'from package
51 import *', Python will look into the __all__ variable of the package
52 to determine which modules are to be imported, while Freeze will do a
53 directory listing.
54
55 One tricky issue: Freeze assumes that the Python interpreter and
56 environment you're using to run Freeze is the same one that would be
57 used to run your program, which should also be the same whose sources
58 and installed files you will learn about in the next section. In
59 particular, your PYTHONPATH setting should be the same as for running
60 your program locally. (Tip: if the program doesn't run when you type
61 "python hello.py" there's little chance of getting the frozen version
62 to run.)
63
64
65 How do I use Freeze?
66 --------------------
67
68 Normally, you should be able to use it as follows:
69
70 python freeze.py hello.py
71
72 where hello.py is your program and freeze.py is the main file of
73 Freeze (in actuality, you'll probably specify an absolute pathname
74 such as /usr/joe/python/Tools/freeze/freeze.py).
75
76
77 What do I do next?
78 ------------------
79
80 Freeze creates a number of files: frozen.c, config.c and Makefile,
81 plus one file for each Python module that gets included named
82 M_<module>.c. To produce the frozen version of your program, you can
83 simply type "make". This should produce a binary file. If the
84 filename argument to Freeze was "hello.py", the binary will be called
85 "hello".
86
87 Note: you can use the -o option to freeze to specify an alternative
88 directory where these files are created. This makes it easier to
89 clean up after you've shipped the frozen binary. You should invoke
90 "make" in the given directory.
91
92
93 Freezing Tkinter programs
94 -------------------------
95
96 Unfortunately, it is currently not possible to freeze programs that
97 use Tkinter without a Tcl/Tk installation. The best way to ship a
98 frozen Tkinter program is to decide in advance where you are going
99 to place the Tcl and Tk library files in the distributed setup, and
100 then declare these directories in your frozen Python program using
101 the TCL_LIBRARY and TK_LIBRARY environment variables.
102
103 For example, assume you will ship your frozen program in the directory
104 <root>/bin/windows-x86 and will place your Tcl library files
105 in <root>/lib/tcl8.2 and your Tk library files in <root>/lib/tk8.2. Then
106 placing the following lines in your frozen Python script before importing
107 tkinter would set the environment correctly for Tcl/Tk:
108
109 import os
110 import os.path
111 RootDir = os.path.dirname(os.path.dirname(os.getcwd()))
112
113 import sys
114 if sys.platform == "win32":
115 sys.path = ['', '..\\..\\lib\\python-2.0']
116 os.environ['TCL_LIBRARY'] = RootDir + '\\lib\\tcl8.2'
117 os.environ['TK_LIBRARY'] = RootDir + '\\lib\\tk8.2'
118 elif sys.platform == "linux2":
119 sys.path = ['', '../../lib/python-2.0']
120 os.environ['TCL_LIBRARY'] = RootDir + '/lib/tcl8.2'
121 os.environ['TK_LIBRARY'] = RootDir + '/lib/tk8.2'
122 elif sys.platform == "solaris":
123 sys.path = ['', '../../lib/python-2.0']
124 os.environ['TCL_LIBRARY'] = RootDir + '/lib/tcl8.2'
125 os.environ['TK_LIBRARY'] = RootDir + '/lib/tk8.2'
126
127 This also adds <root>/lib/python-2.0 to your Python path
128 for any Python files such as _tkinter.pyd you may need.
129
130 Note that the dynamic libraries (such as tcl82.dll tk82.dll python20.dll
131 under Windows, or libtcl8.2.so and libtcl8.2.so under Unix) are required
132 at program load time, and are searched by the operating system loader
133 before Python can be started. Under Windows, the environment
134 variable PATH is consulted, and under Unix, it may be the
135 environment variable LD_LIBRARY_PATH and/or the system
136 shared library cache (ld.so). An additional preferred directory for
137 finding the dynamic libraries is built into the .dll or .so files at
138 compile time - see the LIB_RUNTIME_DIR variable in the Tcl makefile.
139 The OS must find the dynamic libraries or your frozen program won't start.
140 Usually I make sure that the .so or .dll files are in the same directory
141 as the executable, but this may not be foolproof.
142
143 A workaround to installing your Tcl library files with your frozen
144 executable would be possible, in which the Tcl/Tk library files are
145 incorporated in a frozen Python module as string literals and written
146 to a temporary location when the program runs; this is currently left
147 as an exercise for the reader. An easier approach is to freeze the
148 Tcl/Tk code into the dynamic libraries using the Tcl ET code.
149 Of course, you can also simply require that Tcl/Tk is required on the
150 target installation, but be careful that the version corresponds.
151
152 There are some caveats using frozen Tkinter applications:
153 Under Windows if you use the -s windows option, writing
154 to stdout or stderr is an error.
155 The Tcl [info nameofexecutable] will be set to where the
156 program was frozen, not where it is run from.
157 The global variables argc and argv do not exist.
158
159
160 A warning about shared library modules
161 --------------------------------------
162
163 When your Python installation uses shared library modules such as
164 _tkinter.pyd, these will not be incorporated in the frozen program.
165 Again, the frozen program will work when you test it, but it won't
166 work when you ship it to a site without a Python installation.
167
168 Freeze prints a warning when this is the case at the end of the
169 freezing process:
170
171 Warning: unknown modules remain: ...
172
173 When this occurs, the best thing to do is usually to rebuild Python
174 using static linking only. Or use the approach described in the previous
175 section to declare a library path using sys.path, and place the modules
176 such as _tkinter.pyd there.
177
178
179 Troubleshooting
180 ---------------
181
182 If you have trouble using Freeze for a large program, it's probably
183 best to start playing with a really simple program first (like the file
184 hello.py). If you can't get that to work there's something
185 fundamentally wrong -- perhaps you haven't installed Python. To do a
186 proper install, you should do "make install" in the Python root
187 directory.
188
189
190 Usage under Windows 95 or NT
191 ----------------------------
192
193 Under Windows 95 or NT, you *must* use the -p option and point it to
194 the top of the Python source tree.
195
196 WARNING: the resulting executable is not self-contained; it requires
197 the Python DLL, currently PYTHON20.DLL (it does not require the
198 standard library of .py files though). It may also require one or
199 more extension modules loaded from .DLL or .PYD files; the module
200 names are printed in the warning message about remaining unknown
201 modules.
202
203 The driver script generates a Makefile that works with the Microsoft
204 command line C compiler (CL). To compile, run "nmake"; this will
205 build a target "hello.exe" if the source was "hello.py". Only the
206 files frozenmain.c and frozen.c are used; no config.c is generated or
207 used, since the standard DLL is used.
208
209 In order for this to work, you must have built Python using the VC++
210 (Developer Studio) 5.0 compiler. The provided project builds
211 python20.lib in the subdirectory pcbuild\Release of thje Python source
212 tree, and this is where the generated Makefile expects it to be. If
213 this is not the case, you can edit the Makefile or (probably better)
214 winmakemakefile.py (e.g., if you are using the 4.2 compiler, the
215 python20.lib file is generated in the subdirectory vc40 of the Python
216 source tree).
217
218 It is possible to create frozen programs that don't have a console
219 window, by specifying the option '-s windows'. See the Usage below.
220
221 Usage under macOS
222 -----------------
223
224 On macOS the freeze tool is not supported for framework builds.
225
226 Usage
227 -----
228
229 Here is a list of all of the options (taken from freeze.__doc__):
230
231 usage: freeze [options...] script [module]...
232
233 Options:
234 -p prefix: This is the prefix used when you ran ``make install''
235 in the Python build directory.
236 (If you never ran this, freeze won't work.)
237 The default is whatever sys.prefix evaluates to.
238 It can also be the top directory of the Python source
239 tree; then -P must point to the build tree.
240
241 -P exec_prefix: Like -p but this is the 'exec_prefix', used to
242 install objects etc. The default is whatever sys.exec_prefix
243 evaluates to, or the -p argument if given.
244 If -p points to the Python source tree, -P must point
245 to the build tree, if different.
246
247 -e extension: A directory containing additional .o files that
248 may be used to resolve modules. This directory
249 should also have a Setup file describing the .o files.
250 On Windows, the name of a .INI file describing one
251 or more extensions is passed.
252 More than one -e option may be given.
253
254 -o dir: Directory where the output files are created; default '.'.
255
256 -m: Additional arguments are module names instead of filenames.
257
258 -a package=dir: Additional directories to be added to the package's
259 __path__. Used to simulate directories added by the
260 package at runtime (eg, by OpenGL and win32com).
261 More than one -a option may be given for each package.
262
263 -l file: Pass the file to the linker (windows only)
264
265 -d: Debugging mode for the module finder.
266
267 -q: Make the module finder totally quiet.
268
269 -h: Print this help message.
270
271 -x module Exclude the specified module.
272
273 -i filename: Include a file with additional command line options. Used
274 to prevent command lines growing beyond the capabilities of
275 the shell/OS. All arguments specified in filename
276 are read and the -i option replaced with the parsed
277 params (note - quoting args in this file is NOT supported)
278
279 -s subsystem: Specify the subsystem (For Windows only.);
280 'console' (default), 'windows', 'service' or 'com_dll'
281
282 -w: Toggle Windows (NT or 95) behavior.
283 (For debugging only -- on a win32 platform, win32 behavior
284 is automatic.)
285
286 Arguments:
287
288 script: The Python script to be executed by the resulting binary.
289
290 module ...: Additional Python modules (referenced by pathname)
291 that will be included in the resulting binary. These
292 may be .py or .pyc files. If -m is specified, these are
293 module names that are search in the path instead.
294
295
296
297 --Guido van Rossum (home page: https://www.python.org/~guido/)