153 lines
7.3 KiB
HTML
153 lines
7.3 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<TITLE>Creating standalone applications with Python</TITLE>
|
|
</HEAD>
|
|
<BODY>
|
|
<H1>Creating standalone applications with Python</H1>
|
|
|
|
With <a href="example2.html#applet">BuildApplet</a> you can build a standalone
|
|
Python application that works like
|
|
any other Mac application: you can double-click it, run it while the
|
|
Python interpreter is running other scripts, drop files on it, etc. It is, however,
|
|
still dependent on the whole Python installation on your machine: the PythonCore
|
|
engine, the plugin modules and the various Lib folders.<p>
|
|
|
|
In some cases you may want to create a true application, for instance because
|
|
you want to send it off to people who may not have Python installed on their
|
|
machine, or because you the application is important and you do not want changes
|
|
in your Python installation like new versions to influence it.
|
|
|
|
<H2>The easy way</H2>
|
|
|
|
The easiest way to create an application from a Python script is simply by dropping
|
|
it on the <code>BuildApplication</code> applet in the main Python folder.
|
|
BuildApplication has a similar interface as BuildApplet: you drop a script on
|
|
it and it will process it, along with an optional <code>.rsrc</code> file.
|
|
It does ask one extra question: whether you want to build your application for
|
|
PPC macs only, 68K macs or any Mac.<P>
|
|
|
|
What BuildApplication does, however, is very different. It parses your script,
|
|
recursively looking for all modules you use, bundles the compiled code for
|
|
all these modules in PYC resources, adds the executable machine code for the
|
|
PythonCore engine, any dynamically loaded modules you use and a main program, combines
|
|
all this into a single file and adds a few preference resources (which you
|
|
can inspect with <code>EditPythonPrefs</code>, incidentally) to isolate the
|
|
new program from the existing Python installation.<P>
|
|
|
|
Usually you do not need to worry about all this, but occasionally you may have
|
|
to exercise some control over the process, for instance because your
|
|
program imports modules that don't exist (which can happen if your script
|
|
is multi-platform and those modules will never be used on the Mac). See
|
|
the section on <a href="#directives">directives</a> below for details.
|
|
If you get strange error messages about missing modules it may also be worthwhile
|
|
to run macfreeze in report mode on your program, see below.
|
|
<P>
|
|
|
|
<H2>Doing it the hard way</H2>
|
|
|
|
With the <EM>macfreeze</EM> script, for which BuildApplication is a simple
|
|
wrapper, you can go a step further and create CodeWarrior projects and
|
|
sourcefiles which can then be used to build your final application. While
|
|
BuildApplication is good enough for 90% of the use cases there are situations
|
|
where you need macfreeze itself, mainly if you want to embed your frozen Python
|
|
script into an existing C application, or when you need the extra bit of speed:
|
|
the resulting application will start up a bit quicker than one generated
|
|
with BuildApplication. <p>
|
|
|
|
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>
|
|
|
|
<h2><a name="directives">Directives</a></h2>
|
|
|
|
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.
|
|
|
|
<DT> <code>optional</code>
|
|
<DD> Include a module if it can be found, but don't complain if it can't.
|
|
|
|
</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 regenerate 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>
|
|
|
|
</BODY>
|
|
</HTML>
|