Initial documentation on freezing.

author: Jack Jansen <jack.jansen@cwi.nl> 1998-06-26 15:01:52 (GMT)
committer: Jack Jansen <jack.jansen@cwi.nl> 1998-06-26 15:01:52 (GMT)
commit: d969061744885195448d92b40c965d6785d91b73 (patch)
tree: c4a2d4d9e8e8d3b4ae3d07630c4a60f01eb9c968 /Mac
parent: 1118c44369d277d883e38d3233f07d51ac9b9429 (diff)
download: cpython-d969061744885195448d92b40c965d6785d91b73.zip
cpython-d969061744885195448d92b40c965d6785d91b73.tar.gz
cpython-d969061744885195448d92b40c965d6785d91b73.tar.bz2
3 files changed, 134 insertions, 6 deletions
diff --git a/Mac/Demo/freezing.html b/Mac/Demo/freezing.html
new file mode 100644
index 0000000..02556d8
--- /dev/null
+++ b/Mac/Demo/freezing.html
@@ -0,0 +1,124 @@
+<HTML>
+<HEAD>
+<TITLE>Creating standalone applications with Python</TITLE>
+</HEAD>
+<BODY>
+<H1>Creating standalone applications with Python</H1>
+<HR>
+With the <EM>macfreeze</EM> script you can <i>freeze</i> a Python
+script: create a fullblown Macintosh application that is completely
+self-contained. A frozen application is similar to an applet (see <a
+href="example2.html">Example 2</a> for information on creating applets),
+but where an applet depends on an existing Python installation for its
+standard modules and interpreter core, a frozen program does not,
+because it incorporates everything in a single binary. This means you
+can copy a frozen program to a machine that does not have Python
+installed and it will work, which is not true for an applet. <p>
+
+There are two ways to create a frozen application: through the
+CodeWarrior development environment or without any development
+environment. The former method is more versatile and may result in
+smaller binaries, because you can better customize what is included in
+your eventual application. The latter method builds an application by
+glueing together the various <em>.slb</em> shared libraries that come
+with a binary Python installation into a single file. This method of
+freezing, which does not require you to spend money on a development
+environment, is unique to MacPython, incidentally, on other platforms
+you will always need a C compiler and linker. <p>
+
+<h2>Common steps</h2>
+
+The two processes have a number of steps in common. When you start
+<code>Mac:Tools:macfreeze:macfreeze.py</code> you are asked for the
+script file, and you can select which type of freeze to do. The first
+time you should always choose <em>report only</em>, which will produce a
+listing of modules and where they are included from in the console
+window. Macfreeze actually parses all modules, so it may crash in the
+process. If it does try again with a higher debug value, this should
+show you where it crashes. <p>
+
+For more elaborate programs you will often see that freeze includes
+modules you don't need (because they are for a different platform, for
+instance) or that it cannot find all your modules (because you modify
+<code>sys.path</code> early in your initialization). It is possible to
+include directives to tell macfreeze to add items to the search path and
+include or exclude certain modules. All your directives should be in the
+main script file. <p>
+
+Directives have the following form:
+<pre>
+# macfreeze: command argument
+</pre>
+The trigger <code>macfreeze:</code> must be spelled exactly like that,
+but the whitespace can be any combination of spaces and tabs. Macfreeze
+understands the following directives:
+
+<DL>
+<DT> <code>path</code>
+<DD> Prepend a folder to <code>sys.path</code>. The argument is a
+pathname, which should probably be relative (starting with a colon) and
+is interpreted relative to the folder where the script lives.
+
+<DT> <code>include</code>
+<DD> Include a module. The module can either be given by filename or by
+module name, in which case it is looked up through the normal method.
+
+<DT> <code>exclude</code>
+<DD> Exclude a module. The module must be given by modulename. Even when
+freeze deems the module necessary it will not be included in the
+application.
+
+</DL>
+
+There is actually a fourth way that macfreeze can operate: it can be used
+to generate only the resource file containing the compiled <code>PYC</code>
+resources. This may be useful if you have embedded Python in your own
+application. The resource file generated is the same as for the CodeWarrior
+generation process. <p>
+
+<h2>Freezing with CodeWarrior</h2>
+
+To freeze with CodeWarrior you need CodeWarrior, obviously, and a full
+source distribution of Python. You select the <em>Codewarrior source and
+project</em> option. You specify an output folder, which is by default
+the name of your script with <code>.py</code> removed and
+<code>build.</code> prepended. If the output folder does not exist yet
+it is created, and a template project file and bundle resource file are
+deposited there. Next, a source file <code>macfreezeconfig.c</code> is
+created which includes all builtin modules your script uses, and a
+resource file <code>frozenmodules.rsrc</code> which contains the
+<code>PYC</code> resources for all your Python modules. <p>
+
+The project expects to live in a folder one level below the Python root
+folder, so the next thing you should do is move the build folder there.
+It is a good idea to leave an alias with the same name in the original
+location: when you run freeze again it will regenerate the
+<code>frozenmodules.rsrc</code> file but not the project and bundle
+files. This is probably what you want: if you modify your python sources
+you have to re-freeze, but you may have changed the project and bundle
+files, so you don't want to regenrate them. <p>
+
+An alternative is to leave the build folder where it is, but then you
+have to adapt the search path in the project. <p>
+
+The project is set up to include all the standard builtin modules, but
+the CW linker is smart enough to exclude any object code that isn't
+referenced. Still, it may be worthwhile to remove any sources for
+modules that you are sure are not used to cut back on compilation time.
+You may also want to examine the various resource files (for Tcl/Tk, for
+instance): the loader has no way to know that these aren't used. <p>
+
+You may also need to add sourcefiles if your script uses non-standard
+builtin modules, like anything from the <code>Extensions</code> folder. <p>
+
+The <code>frozenbundle.rsrc</code> resource file contains the bundle
+information. It is almost identical to the bundle file used for applets,
+with the exception that it sets the <code>sys.path</code> initialization
+to <code>$(APPLICATION)</code> only. This means that all modules will only
+be looked for in PYC resources in your application. <p>
+
+<h2>Freezing without CodeWarrior</h2>
+
+This does not work yet.
+</BODY>
+</HTML>
diff --git a/Mac/Demo/index.html b/Mac/Demo/index.html
index c122b60..f073086 100644
--- a/Mac/Demo/index.html
+++ b/Mac/Demo/index.html
@@ -52,6 +52,12 @@ mac application, using a modeless dialog, menus, etc. It also explains
 how to create applets, standalone applications written in Python.
 
 <LI>
+<A HREF="freezing.html">Freezing Python programs</A> extends on this concept,
+and shows you how to create applications that can be used on machines without
+a full Python installed. This one is probably best skipped on first contact
+with MacPython.
+
+<LI>
 <A HREF="textedit.html">Using FrameWork and TextEdit</A> shows you
 how to use <code>FrameWork</code> application framework and the
 <code>TextEdit</code> toolbox to build a text editor.
@@ -85,11 +91,6 @@ how to build a PPC or 68K interpreter from a source distribution.
 <A HREF="embed.html">Embedding Python on the Mac</A> is a minimal example of
 how to embed Python in other Mac applications.
 
-<LI>
-<a href="standalone.html">Building Standalone applications in Python</a>
-explains how you can create real standalone applications in Python. You do
-need source (and a C development environment) for this at the moment.
-
 </UL>
 
 The Python distribution contains a few more examples, all unexplained:
@@ -136,5 +137,5 @@ documentation. <p>
 
 <HR>
 <A HREF="http://www.cwi.nl/~jack">Jack Jansen</A>,
-<A HREF="mailto:jack@cwi.nl">jack@cwi.nl</A>, 27-Apr-98.
+<A HREF="mailto:jack@cwi.nl">jack@cwi.nl</A>, 26-Jun-98.
 </BODY></HTML>
diff --git a/Mac/Demo/standalone.html b/Mac/Demo/standalone.html
index 70a2587..9aebb77 100644
--- a/Mac/Demo/standalone.html
+++ b/Mac/Demo/standalone.html
@@ -2,6 +2,9 @@
 <BODY>
 <H1>Creating true standalone applications in Python</H1>
 <HR>
+<EM>NOTE</EM> This document is obsolete. See <A HREF="freezing.html">Freezing Python
+scripts</A> for a more up-to-date treatise. <p>
+</HR>
 You can use Python to create true standalone macintosh applications: applications
 that you can distribute to other people as a single file, without dependencies
 on Python being installed, etc. The process is not easy, however, and at the
author	Jack Jansen <jack.jansen@cwi.nl>	1998-06-26 15:01:52 (GMT)
committer	Jack Jansen <jack.jansen@cwi.nl>	1998-06-26 15:01:52 (GMT)
commit	d969061744885195448d92b40c965d6785d91b73 (patch)
tree	c4a2d4d9e8e8d3b4ae3d07630c4a60f01eb9c968 /Mac
parent	1118c44369d277d883e38d3233f07d51ac9b9429 (diff)
download	cpython-d969061744885195448d92b40c965d6785d91b73.zip cpython-d969061744885195448d92b40c965d6785d91b73.tar.gz cpython-d969061744885195448d92b40c965d6785d91b73.tar.bz2