Tools/freeze/README

THE FREEZE SCRIPT
=================


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?
----------------------------------------------

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

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).

(With Python 1.4, freeze is much more likely to work "out of the box"
than before, provided Python has been installed properly.)


What do I do next?
------------------

Freeze creates three files: frozen.c, config.c and Makefile.  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.


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.


--Guido van Rossum (home page: http://www.python.org/~guido/)