| Jack Jansen | d969061 | 1998-06-26 15:01:52 +0000 | [diff] [blame] | 1 | <HTML> |
| 2 | <HEAD> |
| 3 | <TITLE>Creating standalone applications with Python</TITLE> |
| 4 | </HEAD> |
| 5 | <BODY> |
| 6 | <H1>Creating standalone applications with Python</H1> |
| Jack Jansen | d969061 | 1998-06-26 15:01:52 +0000 | [diff] [blame] | 7 | |
| Jack Jansen | dd20689 | 1999-12-03 16:00:20 +0000 | [diff] [blame] | 8 | With <a href="example2.html#applet">BuildApplet</a> you can build a standalone |
| 9 | Python application that works like |
| 10 | any other Mac application: you can double-click it, run it while the |
| 11 | Python interpreter is running other scripts, drop files on it, etc. It is, however, |
| 12 | still dependent on the whole Python installation on your machine: the PythonCore |
| 13 | engine, the plugin modules and the various Lib folders.<p> |
| Jack Jansen | d969061 | 1998-06-26 15:01:52 +0000 | [diff] [blame] | 14 | |
| Jack Jansen | dd20689 | 1999-12-03 16:00:20 +0000 | [diff] [blame] | 15 | In some cases you may want to create a true application, for instance because |
| 16 | you want to send it off to people who may not have Python installed on their |
| 17 | machine, or because you the application is important and you do not want changes |
| 18 | in your Python installation like new versions to influence it. |
| Jack Jansen | d969061 | 1998-06-26 15:01:52 +0000 | [diff] [blame] | 19 | |
| Jack Jansen | dd20689 | 1999-12-03 16:00:20 +0000 | [diff] [blame] | 20 | <H2>The easy way</H2> |
| 21 | |
| 22 | The easiest way to create an application from a Python script is simply by dropping |
| 23 | it on the <code>BuildApplication</code> applet in the main Python folder. |
| 24 | BuildApplication has a similar interface as BuildApplet: you drop a script on |
| 25 | it and it will process it, along with an optional <code>.rsrc</code> file. |
| Jack Jansen | 8a6cdcc | 2000-09-10 12:02:28 +0000 | [diff] [blame] | 26 | <P> |
| Jack Jansen | dd20689 | 1999-12-03 16:00:20 +0000 | [diff] [blame] | 27 | |
| 28 | What BuildApplication does, however, is very different. It parses your script, |
| 29 | recursively looking for all modules you use, bundles the compiled code for |
| 30 | all these modules in PYC resources, adds the executable machine code for the |
| 31 | PythonCore engine, any dynamically loaded modules you use and a main program, combines |
| 32 | all this into a single file and adds a few preference resources (which you |
| 33 | can inspect with <code>EditPythonPrefs</code>, incidentally) to isolate the |
| 34 | new program from the existing Python installation.<P> |
| 35 | |
| 36 | Usually you do not need to worry about all this, but occasionally you may have |
| 37 | to exercise some control over the process, for instance because your |
| 38 | program imports modules that don't exist (which can happen if your script |
| 39 | is multi-platform and those modules will never be used on the Mac). See |
| 40 | the section on <a href="#directives">directives</a> below for details. |
| 41 | If you get strange error messages about missing modules it may also be worthwhile |
| 42 | to run macfreeze in report mode on your program, see below. |
| 43 | <P> |
| 44 | |
| 45 | <H2>Doing it the hard way</H2> |
| 46 | |
| 47 | With the <EM>macfreeze</EM> script, for which BuildApplication is a simple |
| 48 | wrapper, you can go a step further and create CodeWarrior projects and |
| 49 | sourcefiles which can then be used to build your final application. While |
| 50 | BuildApplication is good enough for 90% of the use cases there are situations |
| 51 | where you need macfreeze itself, mainly if you want to embed your frozen Python |
| 52 | script into an existing C application, or when you need the extra bit of speed: |
| 53 | the resulting application will start up a bit quicker than one generated |
| 54 | with BuildApplication. <p> |
| 55 | |
| 56 | When you start |
| Jack Jansen | d969061 | 1998-06-26 15:01:52 +0000 | [diff] [blame] | 57 | <code>Mac:Tools:macfreeze:macfreeze.py</code> you are asked for the |
| 58 | script file, and you can select which type of freeze to do. The first |
| 59 | time you should always choose <em>report only</em>, which will produce a |
| 60 | listing of modules and where they are included from in the console |
| 61 | window. Macfreeze actually parses all modules, so it may crash in the |
| 62 | process. If it does try again with a higher debug value, this should |
| 63 | show you where it crashes. <p> |
| 64 | |
| Jack Jansen | dd20689 | 1999-12-03 16:00:20 +0000 | [diff] [blame] | 65 | <h2><a name="directives">Directives</a></h2> |
| 66 | |
| Jack Jansen | d969061 | 1998-06-26 15:01:52 +0000 | [diff] [blame] | 67 | For more elaborate programs you will often see that freeze includes |
| 68 | modules you don't need (because they are for a different platform, for |
| 69 | instance) or that it cannot find all your modules (because you modify |
| 70 | <code>sys.path</code> early in your initialization). It is possible to |
| 71 | include directives to tell macfreeze to add items to the search path and |
| 72 | include or exclude certain modules. All your directives should be in the |
| 73 | main script file. <p> |
| 74 | |
| 75 | Directives have the following form: |
| 76 | <pre> |
| 77 | # macfreeze: command argument |
| 78 | </pre> |
| 79 | The trigger <code>macfreeze:</code> must be spelled exactly like that, |
| 80 | but the whitespace can be any combination of spaces and tabs. Macfreeze |
| 81 | understands the following directives: |
| 82 | |
| 83 | <DL> |
| 84 | <DT> <code>path</code> |
| 85 | <DD> Prepend a folder to <code>sys.path</code>. The argument is a |
| 86 | pathname, which should probably be relative (starting with a colon) and |
| 87 | is interpreted relative to the folder where the script lives. |
| 88 | |
| 89 | <DT> <code>include</code> |
| 90 | <DD> Include a module. The module can either be given by filename or by |
| 91 | module name, in which case it is looked up through the normal method. |
| 92 | |
| 93 | <DT> <code>exclude</code> |
| 94 | <DD> Exclude a module. The module must be given by modulename. Even when |
| 95 | freeze deems the module necessary it will not be included in the |
| 96 | application. |
| 97 | |
| Jack Jansen | dd20689 | 1999-12-03 16:00:20 +0000 | [diff] [blame] | 98 | <DT> <code>optional</code> |
| 99 | <DD> Include a module if it can be found, but don't complain if it can't. |
| 100 | |
| Jack Jansen | d969061 | 1998-06-26 15:01:52 +0000 | [diff] [blame] | 101 | </DL> |
| 102 | |
| 103 | There is actually a fourth way that macfreeze can operate: it can be used |
| 104 | to generate only the resource file containing the compiled <code>PYC</code> |
| 105 | resources. This may be useful if you have embedded Python in your own |
| 106 | application. The resource file generated is the same as for the CodeWarrior |
| 107 | generation process. <p> |
| 108 | |
| 109 | <h2>Freezing with CodeWarrior</h2> |
| 110 | |
| 111 | To freeze with CodeWarrior you need CodeWarrior, obviously, and a full |
| 112 | source distribution of Python. You select the <em>Codewarrior source and |
| 113 | project</em> option. You specify an output folder, which is by default |
| 114 | the name of your script with <code>.py</code> removed and |
| 115 | <code>build.</code> prepended. If the output folder does not exist yet |
| 116 | it is created, and a template project file and bundle resource file are |
| 117 | deposited there. Next, a source file <code>macfreezeconfig.c</code> is |
| 118 | created which includes all builtin modules your script uses, and a |
| 119 | resource file <code>frozenmodules.rsrc</code> which contains the |
| 120 | <code>PYC</code> resources for all your Python modules. <p> |
| 121 | |
| 122 | The project expects to live in a folder one level below the Python root |
| 123 | folder, so the next thing you should do is move the build folder there. |
| 124 | It is a good idea to leave an alias with the same name in the original |
| 125 | location: when you run freeze again it will regenerate the |
| 126 | <code>frozenmodules.rsrc</code> file but not the project and bundle |
| 127 | files. This is probably what you want: if you modify your python sources |
| 128 | you have to re-freeze, but you may have changed the project and bundle |
| Jack Jansen | dd20689 | 1999-12-03 16:00:20 +0000 | [diff] [blame] | 129 | files, so you don't want to regenerate them. <p> |
| Jack Jansen | d969061 | 1998-06-26 15:01:52 +0000 | [diff] [blame] | 130 | |
| 131 | An alternative is to leave the build folder where it is, but then you |
| 132 | have to adapt the search path in the project. <p> |
| 133 | |
| 134 | The project is set up to include all the standard builtin modules, but |
| 135 | the CW linker is smart enough to exclude any object code that isn't |
| 136 | referenced. Still, it may be worthwhile to remove any sources for |
| 137 | modules that you are sure are not used to cut back on compilation time. |
| 138 | You may also want to examine the various resource files (for Tcl/Tk, for |
| 139 | instance): the loader has no way to know that these aren't used. <p> |
| 140 | |
| 141 | You may also need to add sourcefiles if your script uses non-standard |
| 142 | builtin modules, like anything from the <code>Extensions</code> folder. <p> |
| 143 | |
| 144 | The <code>frozenbundle.rsrc</code> resource file contains the bundle |
| 145 | information. It is almost identical to the bundle file used for applets, |
| 146 | with the exception that it sets the <code>sys.path</code> initialization |
| 147 | to <code>$(APPLICATION)</code> only. This means that all modules will only |
| 148 | be looked for in PYC resources in your application. <p> |
| 149 | |
| Jack Jansen | d969061 | 1998-06-26 15:01:52 +0000 | [diff] [blame] | 150 | </BODY> |
| 151 | </HTML> |