home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Source Code / C / Applications / Python 1.3 / source code / Tools / freeze / README < prev   
Encoding:
Text File  |  1995-12-17  |  6.3 KB  |  171 lines  |  [TEXT/R*ch]
  1. THE FREEZE SCRIPT
  2. =================
  3.  
  4.  
  5. What is Freeze?
  6. ---------------
  7.  
  8. Freeze make it possible to ship arbitrary Python programs to people
  9. who don't have Python.  The shipped file (called a "frozen" version of
  10. your Python program) is an executable, so this only works if your
  11. platform is compatible with that on the receiving end (this is usually
  12. a matter of having the same major operating system revision and CPU
  13. type).
  14.  
  15. The shipped file contains a Python interpreter and large portions of
  16. the Python run-time.  Some measures have been taken to avoid linking
  17. unneeded modules, but the resulting binary is usually not small.
  18.  
  19. The Python source code of your program (and of the library modules
  20. written in Python that it uses) is not included in the binary --
  21. instead, the compiled byte-code (the instruction stream used
  22. internally by the interpreter) is incorporated.  This gives some
  23. protection of your Python source code, though not much -- a
  24. disassembler for Python byte-code is available in the standard Python
  25. library.  At least someone running "strings" on your binary won't see
  26. the source.
  27.  
  28.  
  29. How does Freeze know which modules to include?
  30. ----------------------------------------------
  31.  
  32. Freeze uses a pretty simple-minded algorithm to find the modules that
  33. your program uses: given a file containing Python source code, it
  34. scans for lines beginning with the word "import" or "from" (possibly
  35. preceded by whitespace) and then it knows where to find the module
  36. name(s) in those lines.  It then recursively scans the source for
  37. those modules (if found, and not already processed) in the same way.
  38.  
  39. Freeze will not see import statements hidden behind another statement,
  40. like this:
  41.  
  42.     if some_test: import M  # M not seen
  43.  
  44. or like this:
  45.  
  46.     import A; import B; import C  # B and C not seen
  47.  
  48. nor will it see import statements constructed using string
  49. operations and passed to 'exec', like this:
  50.  
  51.     exec "import %s" % "M"  # M not seen
  52.  
  53. On the other hand, Freeze will think you are importing a module even
  54. if the import statement it sees will never be executed, like this:
  55.  
  56.     if 0:
  57.         import M  # M is seen
  58.  
  59. One tricky issue: Freeze assumes that the Python interpreter and
  60. environment you're using to run Freeze is the same one that would be
  61. used to run your program, which should also be the same whose sources
  62. and installed files you will learn about in the next section.  In
  63. particular, your PYTHONPATH setting should be the same as for running
  64. your program locally.  (Tip: if the program doesn't run when you type
  65. "python hello.py" there's little chance of getting the frozen version
  66. to run.)
  67.  
  68.  
  69. How do I use Freeze?
  70. --------------------
  71.  
  72. Ideally, you should be able to use it as follows:
  73.  
  74.     python freeze.py hello.py
  75.  
  76. where hello.py is your program and freeze.py is the main file of
  77. Freeze (in actuality, you'll probably specify an absolute pathname
  78. such as /ufs/guido/src/python/Tools/freeze/freeze.py).
  79.  
  80. Unfortunately, this doesn't work.  Well, it might, but somehow it's
  81. extremely unlikely that it'll work on the first try.  (If it does,
  82. skip to the next section.)  Most likely you'll get this error message:
  83.  
  84.     needed directory /usr/local/lib/python/lib not found
  85.  
  86. The reason is that Freeze require that some files that are normally
  87. kept inside the Python build tree are installed, and it searches for
  88. it in the default install location.  (The default install prefix is
  89. /usr/local; these particular files are installed at lib/python/lib
  90. under the install prefix.)
  91.  
  92. The particular set of files needed is installed only if you run "make
  93. libainstall" (note: "liba", not "lib") in the Python build tree (which
  94. is the tree where you build Python -- often, but not necessarily, this
  95. is also the Python source tree).  If you have in fact done a "make
  96. libainstall" but used a different prefix, all you need to do is pass
  97. that same prefix to Freeze with the -p option:
  98.  
  99.     python freeze.py -p your-prefix hello.py
  100.  
  101. If you haven't run "make libainstall" yet, you should do it now
  102. (perhaps figuring out first *where* you want everything to be
  103. installed).
  104.  
  105.  
  106. How do I configure Freeze?
  107. --------------------------
  108.  
  109. It's a good idea to change the first line marked with XXX in freeze.py
  110. (an assignment to variable PACK) to point to the absolute pathname of
  111. the directory where Freeze lives (Tools/freeze in the Python source
  112. tree.)  This makes it possible to call Freeze from other directories.
  113.  
  114. You can also edit the assignment to variable PREFIX (also marked with
  115. XXX) -- this saves a lot of -p options.
  116.  
  117.  
  118. How do I use Freeze with extensions modules?
  119. --------------------------------------------
  120.  
  121. XXX to be written.  (In short: pass -e extensionbuilddir.)
  122.  
  123.  
  124. How do I use Freeze with dynamically loaded extension modules?
  125. --------------------------------------------------------------
  126.  
  127. XXX to be written.  (In short: pass -e modulebuilddir -- this even
  128. works if you built the modules in Python's own Modules directory.)
  129.  
  130.  
  131. What do I do next?
  132. ------------------
  133.  
  134. Freeze creates three files: frozen.c, config.c and Makefile.  To
  135. produce the frozen version of your program, you can simply type
  136. "make".  This should produce a binary file.  If the filename argument
  137. to Freeze was "hello.py", the binary will be called "hello".  On the
  138. other hand, if the argument was "hello", the binary will be called
  139. "hello.bin".  If you passed any other filename, all bets are off. :-)
  140. In any case, the name of the file will be printed as the last message
  141. from Freeze.
  142.  
  143.  
  144. Troubleshooting
  145. ---------------
  146.  
  147. If you have trouble using Freeze for a large program, it's probably
  148. best to start playing with a really simple program first (like the
  149. file hello.py).  If you can't get that to work there's something
  150. fundamentally wrong -- read the text above to find out how to install
  151. relevant parts of Python properly and how to configure Freeze to find
  152. them.
  153.  
  154. A common problem is having installed an old version -- rerunning "make
  155. libainstall" often clears up problems with missing modules or
  156. libraries at link time.
  157.  
  158.  
  159. What is nfreeze.py?
  160. -------------------
  161.  
  162. The script nfreeze.py is an unsupported variant on freeze.py which
  163. creates all files in a temporary directory and runs "make" there.  It
  164. has the advantage that it doesn't overwrite files in the current
  165. directory, but the disadvantage is that it removes all files when it
  166. is finished.
  167.  
  168.  
  169. --Guido van Rossum, CWI, Amsterdam <mailto:Guido.van.Rossum@cwi.nl>
  170. <http://www.cwi.nl/cwi/people/Guido.van.Rossum.html>
  171.