/Tools/freeze/README

http://unladen-swallow.googlecode.com/ · #! · 296 lines · 226 code · 70 blank · 0 comment · 0 complexity · e8fb88d17e06b1049fab99b3f747bf0e MD5 · raw file

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