From d969061744885195448d92b40c965d6785d91b73 Mon Sep 17 00:00:00 2001 From: Jack Jansen Date: Fri, 26 Jun 1998 15:01:52 +0000 Subject: [PATCH] Initial documentation on freezing. --- Mac/Demo/freezing.html | 124 +++++++++++++++++++++++++++++++++++++++ Mac/Demo/index.html | 13 ++-- Mac/Demo/standalone.html | 3 + 3 files changed, 134 insertions(+), 6 deletions(-) create mode 100644 Mac/Demo/freezing.html diff --git a/Mac/Demo/freezing.html b/Mac/Demo/freezing.html new file mode 100644 index 0000000000..02556d818c --- /dev/null +++ b/Mac/Demo/freezing.html @@ -0,0 +1,124 @@ + + +Creating standalone applications with Python + + +

Creating standalone applications with Python

+
+With the macfreeze script you can freeze a Python +script: create a fullblown Macintosh application that is completely +self-contained. A frozen application is similar to an applet (see Example 2 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.

+ +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 .slb 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.

+ +

Common steps

+ +The two processes have a number of steps in common. When you start +Mac:Tools:macfreeze:macfreeze.py you are asked for the +script file, and you can select which type of freeze to do. The first +time you should always choose report only, 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.

+ +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 +sys.path 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.

+ +Directives have the following form: +

+# macfreeze: command argument
+
+The trigger macfreeze: must be spelled exactly like that, +but the whitespace can be any combination of spaces and tabs. Macfreeze +understands the following directives: + +
+
path +
Prepend a folder to sys.path. 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. + +
include +
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. + +
exclude +
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. + +
+ +There is actually a fourth way that macfreeze can operate: it can be used +to generate only the resource file containing the compiled PYC +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.

+ +

Freezing with CodeWarrior

+ +To freeze with CodeWarrior you need CodeWarrior, obviously, and a full +source distribution of Python. You select the Codewarrior source and +project option. You specify an output folder, which is by default +the name of your script with .py removed and +build. 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 macfreezeconfig.c is +created which includes all builtin modules your script uses, and a +resource file frozenmodules.rsrc which contains the +PYC resources for all your Python modules.

+ +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 +frozenmodules.rsrc 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.

+ +An alternative is to leave the build folder where it is, but then you +have to adapt the search path in the project.

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

+ +You may also need to add sourcefiles if your script uses non-standard +builtin modules, like anything from the Extensions folder.

+ +The frozenbundle.rsrc resource file contains the bundle +information. It is almost identical to the bundle file used for applets, +with the exception that it sets the sys.path initialization +to $(APPLICATION) only. This means that all modules will only +be looked for in PYC resources in your application.

+ +

Freezing without CodeWarrior

+ +This does not work yet. + + diff --git a/Mac/Demo/index.html b/Mac/Demo/index.html index c122b60b4c..f073086915 100644 --- a/Mac/Demo/index.html +++ b/Mac/Demo/index.html @@ -51,6 +51,12 @@ part two turns the previous example program into a more complete mac application, using a modeless dialog, menus, etc. It also explains how to create applets, standalone applications written in Python. +
  • +Freezing Python programs 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. +
  • Using FrameWork and TextEdit shows you how to use FrameWork application framework and the @@ -85,11 +91,6 @@ how to build a PPC or 68K interpreter from a source distribution. Embedding Python on the Mac is a minimal example of how to embed Python in other Mac applications. -
  • -Building Standalone applications in Python -explains how you can create real standalone applications in Python. You do -need source (and a C development environment) for this at the moment. - The Python distribution contains a few more examples, all unexplained: @@ -136,5 +137,5 @@ documentation.

    Jack Jansen, -jack@cwi.nl, 27-Apr-98. +jack@cwi.nl, 26-Jun-98. diff --git a/Mac/Demo/standalone.html b/Mac/Demo/standalone.html index 70a2587a3c..9aebb77282 100644 --- a/Mac/Demo/standalone.html +++ b/Mac/Demo/standalone.html @@ -2,6 +2,9 @@

    Creating true standalone applications in Python

    +NOTE This document is obsolete. See Freezing Python +scripts for a more up-to-date treatise.

    + 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 -- 2.40.0