| Jack Jansen | 8f2d802 | 1996-08-05 15:34:45 +0000 | [diff] [blame^] | 1 | <HTML> |
| 2 | <HEAD> |
| 3 | <TITLE>Building Mac Python from source</TITLE> |
| 4 | </HEAD> |
| 5 | <BODY> |
| 6 | <H1>Building Mac Python from source</H1> |
| 7 | <HR> |
| 8 | This document explains how to build MacPython from source. This is necessary if |
| 9 | you want to write extension modules for 68K Python, and currently also |
| 10 | probably the easiest way to build PPC extension modules. Building Python |
| 11 | is not something to be undertaken lightly, the process is not very streamlined |
| 12 | so you need a reasonable working knowledge of the CodeWarrior development |
| 13 | environment, a good net connection and probably quite some time too. <p> |
| 14 | |
| 15 | The information density in this file is high, so you should probably print it and |
| 16 | read it at your leasure. Most things are explained only once (and probably in the |
| 17 | wrong place:-). <p> |
| 18 | |
| 19 | I am very interested in feedback on this document, contact me at |
| 20 | <A HREF="mailto:jack@cwi.nl"><jack@cwi.nl></A> or send your comments to the |
| 21 | <A HREF="http://www.python.org/sigs/pythonmac-sig/">Mac Python Special Interest Group</A>. |
| 22 | |
| 23 | <H2>What you need.</H2> |
| 24 | |
| 25 | The following things you definitely need: |
| 26 | |
| 27 | <UL> |
| 28 | <LI> |
| 29 | You need a MacPython source distribution, of course. You can obtain one from |
| 30 | <A HREF="ftp://ftp.cwi.nl/pub/jack/python/mac">ftp://ftp.cwi.nl/pub/jack/python/mac</A>, |
| 31 | and possibly also from the standard |
| 32 | <A HREF="ftp://ftp.python.org/pub/python/mac">python.org ftp site</A>. Everything you |
| 33 | need is also included in the standard Python source distribution, but the organization |
| 34 | is different. Look in directory <code>Mac/mwerks/projects</code> for the project files and related |
| 35 | stuff. |
| 36 | |
| 37 | <LI> |
| 38 | You need MetroWerks CodeWarrior. The current distribution has been built with version 9 |
| 39 | of CodeWarrior. Ordering information is available on the |
| 40 | <A HREF="http://www.metrowerks.com/">MetroWerks homepage</A>. You might still be |
| 41 | able to build Python with MPW or Think/Symantec C but you are basically on your own. |
| 42 | |
| 43 | <LI> |
| 44 | You need GUSI, the Grand Unified Socket Interface, by Matthias Neeracher. The |
| 45 | current distribution has been built with CWGUSI 1.6.4, obtainable from |
| 46 | <A HREF="ftp://ftp.switch.ch/software/mac/src/mw_c">ftp://ftp.switch.ch/software/mac/src/mw_c</A>. |
| 47 | It is possible to build a non-GUSI Python, see below. The correct version of CWGUSI is |
| 48 | also included in the Tcl/Tk distribution, by the way. |
| 49 | </UL> |
| 50 | |
| 51 | <A NAME="optional">The MacPython project files are configured to include a plethora of optional modules</A>, and |
| 52 | these modules need a number extra packages. To use the project files as-is you have to |
| 53 | download these packages too. PPC Python has all such modules as dynamically loaded modules, |
| 54 | so if you don't need a certain package it suffices to just refrain from builing the |
| 55 | extension module. For 68K Python things are a bit more complicated: you have to edit the |
| 56 | interpreter project file to remove the reference to the module (and the libraries it uses). |
| 57 | Here are the locations for the various things you need: |
| 58 | |
| 59 | <UL> |
| 60 | <LI> |
| 61 | Tcl and Tk can be obtained from |
| 62 | <A HREF="ftp://ftp.smli.com/pub/tcl/mac/">ftp://ftp.smli.com/pub/tcl/mac/</A>. |
| 63 | The current distributions, Tcl 7.5 and Tk 4.1, were packaged in a hurry |
| 64 | and need a bit |
| 65 | of work, see the section on <A HREF="#tcltk">building Tcl/Tk Python</A> below. Get the "full source" |
| 66 | distribution, which includes CWGUSI (which Python also needs) and MoreFiles. |
| 67 | |
| 68 | <LI> |
| 69 | Waste, a TextEdit replacement written by Marco Piovanelli, |
| 70 | <A HREF="mailto:piovanel@kagi.com"><piovanel@kagi.com></A>. |
| 71 | Python was built using version 1.2a5, which you can obtain from |
| 72 | <A HREF="ftp://ftp.dsi.unimi.it/DSI/piovanel/waste"><ftp://ftp.dsi.unimi.it/DSI/piovanel/waste></A>. |
| 73 | |
| 74 | <LI> |
| 75 | JPEG library by the Independent JPEG Group. Python is still built using an archaic version |
| 76 | of the library, version 4. It can be obtained from the <A HREF="ftp://ftp.cwi.nl/pub/jack/python/mac"> |
| 77 | ftp://ftp.cwi.nl/pub/jack/python/mac</A> directory, complete with CW8 projects. If someone manages |
| 78 | to build Python with the version 6 library I would be grateful if they sent me the changes needed. |
| 79 | The most recent JPEG library can always be obtained from |
| 80 | <A HREF="ftp://ftp.uu.net/graphics/jpeg/">ftp://ftp.uu.net/graphics/jpeg/</A>. |
| 81 | |
| 82 | <LI> |
| 83 | The netpbm/pbmplus and libtiff libraries. The netpbm distribution (which includes libtiff) is generally |
| 84 | available on Internet ftp servers. For Python pbmplus, an older incarnation of netpbm, is functionally |
| 85 | identical to netpbm, since Python only uses the library and not the complete applications. A |
| 86 | distribution with correct projects and library source only is available from, you guessed it, |
| 87 | <A HREF="ftp://ftp.cwi.nl/pub/jack/python/mac">ftp://ftp.cwi.nl/pub/jack/python/mac</A>. |
| 88 | </UL> |
| 89 | |
| 90 | <H2>Setting Up</H2> |
| 91 | |
| 92 | Now that you have collected everything you should start with building the various parts. Everything |
| 93 | is independent, with the single exception that Tcl and Tk depend on CWGUSI. If you don't want to |
| 94 | fix access paths try to set things up as follows: |
| 95 | <PRE> |
| 96 | Top-level-folder: |
| 97 | CWGUSI 1.6.4 |
| 98 | imglibs |
| 99 | libjpeg |
| 100 | pbmplus |
| 101 | libtiff |
| 102 | MoreFiles 1.4.1 (not needed by Python, only by tcl/tk) |
| 103 | Python |
| 104 | Tcl 7.5 |
| 105 | Tk 4.1 |
| 106 | </PRE> |
| 107 | |
| 108 | Now build all the libraries. In <code>CWGUSI</code> you build the projects |
| 109 | <code>GUSI.68K.µ</code> and <code>GUSI.PPC.µ</code>, in <code>MoreFiles</code>, |
| 110 | <code>libjpeg</code>, <code>pbmplus</code> and<code>libtiff</code> you build all |
| 111 | projects. Tcl/tk is a special case, see below. Of course, if you are only |
| 112 | interested in 68K you can skip building the PPC libraries and vice versa. |
| 113 | |
| 114 | <H2><A NAME="tcltk">Building Tcl/Tk</H2> |
| 115 | |
| 116 | You need to make a minor organizational change to the Tcl/Tk distribution. The current instructions |
| 117 | are for the <code>tcl7.5</code> and <code>tk4.1</code> distribution: |
| 118 | <UL> |
| 119 | <LI> Rename the <code>compat</code> folders to <code>(compat)</code> in both the Tcl and Tk folders. |
| 120 | |
| 121 | <LI> In the Tcl folder, move <code>strncasecmp.c</code> from <code>(compat)</code> to the |
| 122 | main Tcl folder. |
| 123 | |
| 124 | <LI> Fix the Tk and Tcl library project access paths: they refer to |
| 125 | <code>MoreFiles 1.4.2</code>, change this to <code>MoreFiles 1.4.1</code>. |
| 126 | Alternatively you could get the real MoreFiles 1.4.2, but there seem to be problems with |
| 127 | this too (undefined references). |
| 128 | |
| 129 | <LI> Fix the Tk and Tcl library project header file: it is set to |
| 130 | <code>MacHeaders.h</code> but should be set to <code>MW_TkHeader.h</code> |
| 131 | and <code>MW_TclHeader.h</code> respectively. |
| 132 | |
| 133 | <LI> You are <em>strongly</em> advised to make a fix to <code>tcl.h</code>. As distributed, |
| 134 | tcl and tk assume that malloc calls always succeed and use the resulting pointer without |
| 135 | checking for <code>NULL</code> values. Needless to say, this wreaks havoc on a Macintosh. |
| 136 | Fortunately a checking malloc is included and easy to enable: look for the |
| 137 | <code>#define</code>'s for ckalloc, ckfree and ckrealloc and replace them by the |
| 138 | following code: |
| 139 | <pre><code> |
| 140 | # define ckalloc(x) Tcl_Ckalloc(x) |
| 141 | # define ckfree(x) Tcl_Ckfree(x) |
| 142 | # define ckrealloc(x,y) Tcl_Ckrealloc(x,y) |
| 143 | </code></pre> |
| 144 | With this fix, out-of-memory situations will still cause a hard abort of the python |
| 145 | interpreter, but at least they will not crash your system. |
| 146 | |
| 147 | <LI> If you want to build <code>SimpleTcl</code> and <code>SimpleTk</code> |
| 148 | to make sure that the distributions are working you should make the previous |
| 149 | changes in those projects too. Moreover, you have to replace the MoreFiles |
| 150 | library reference by the correct one <code>MoreFiles 1.4.1:Libraries:MoreFiles.PPC</code> |
| 151 | (or 68K). |
| 152 | </UL> |
| 153 | |
| 154 | Build first the GUSI and MoreFiles libraries, then the Tcl library, then SimpleTcl |
| 155 | (test it by typing <code>ls -l</code> in the window you get) then the Tk library, then SimpleTk |
| 156 | (which can again be tested with <code>ls -l</code>). If this all worked you are all set to try |
| 157 | building Python. |
| 158 | |
| 159 | <H2>The organization of the Python source tree</H2> |
| 160 | |
| 161 | Time for a short break, while we have a look at the organization of the Python source tree. |
| 162 | At the top level, we find the following folders: |
| 163 | |
| 164 | <DL> |
| 165 | <DT> build.mac68k.stand |
| 166 | <DD> This is where you will build 68K interpreters. |
| 167 | |
| 168 | <DT> build.macppc.shared |
| 169 | <DD> This is where you build the PPC shared library, interpreter and applet framework. |
| 170 | |
| 171 | <DT> build.macppc.stand |
| 172 | <DD> This is where you build a nonshared PPC interpreter (optional). |
| 173 | |
| 174 | <DT> Demo |
| 175 | <DD> Demo programs that are not Mac-specific. Some of these may not work, the file |
| 176 | <code>README-Mac</code> has some details. |
| 177 | |
| 178 | <DT> Extensions |
| 179 | <DD> Extensions to the interpreter that are not Mac-specific. Contains only the <code>img</code> |
| 180 | extension in this distribution. Extensions are <em>not</em> built here, as they are on Unix, |
| 181 | but incorporated in the core interpreter or built as plugin modules. |
| 182 | |
| 183 | <DT> Grammar |
| 184 | <DD> The Python grammar. Included for reference only, you cannot build the parser on a Mac. |
| 185 | |
| 186 | <DT> Include |
| 187 | <DD> Machine-independent header files. |
| 188 | |
| 189 | <DT> Modules |
| 190 | <DD> Machine-independent optional modules. Not all of these will work on the Mac. |
| 191 | |
| 192 | <DT> Objects |
| 193 | <DD> Machine-independent code for various objects. Most of these are not really optional: the |
| 194 | interpreter will not function without them. |
| 195 | |
| 196 | <DT> Parser |
| 197 | <DD> The Python parser (machine-independent). |
| 198 | |
| 199 | <DT> PlugIns |
| 200 | <DD> This is where you build the PPC dynamically-loaded plugin modules. |
| 201 | |
| 202 | <DT> Python |
| 203 | <DD> The core interpreter. Most files are machine-independent, some are unix-specific |
| 204 | and not used on the Mac. |
| 205 | |
| 206 | <DT> Tools |
| 207 | <DD> Tools for python developers. Contains <code>modulator</code> which builds skeleton |
| 208 | C extension modules and <code>bgen</code> which generates complete interface modules from |
| 209 | information in C header files. There are some readme files, but more documentation is |
| 210 | sorely needed. |
| 211 | </DL> |
| 212 | |
| 213 | All the mac-specific stuff lives in the <code>Mac</code> folder: |
| 214 | <DL> |
| 215 | |
| 216 | <DT> Compat |
| 217 | <DD> Unix-compatability routines. Some of these are not used anymore, since CWGUSI provides |
| 218 | a rather complete emulation, but you may need these if you are trying to build a non-GUSI |
| 219 | python. |
| 220 | |
| 221 | <DT> Demo |
| 222 | <DD> Mac-specific demo programs, some of them annotated. |
| 223 | |
| 224 | <DT> Include |
| 225 | <DD> Mac-specific but compiler-independent include files. |
| 226 | |
| 227 | <DT> Lib |
| 228 | <DD> Mac-specific standard modules. The <code>toolbox</code> folder contains modules |
| 229 | specifically needed with various MacOS toolbox interface modules. |
| 230 | |
| 231 | <DT> Modules |
| 232 | <DD> Mac-specific builtin modules. Theoretically these are all optional, but some are |
| 233 | rather essential (like <code>macmodule</code>). A lot of these modules are generated |
| 234 | with <code>bgen</code>, in which case the bgen input files are included so you can attempt to |
| 235 | regenerate them or extend them. |
| 236 | |
| 237 | <DT> MPW |
| 238 | <DD> MPW-specific files. These have not been used or kept up-to-date for a long time, so |
| 239 | use at your own risk. |
| 240 | |
| 241 | <DT> mwerks |
| 242 | <DD> Mwerks-specific sources and headers. Contains glue code for Pythons shared-library |
| 243 | architecture, a replacement for <code>malloc</code> and a directory with various projects |
| 244 | for building variations on the Python interpreter. The <code>mwerks_*.h</code> files here |
| 245 | are the option-setting files for the various interpreters and such, comparable to the unix |
| 246 | command-line <code>-D</code> options to the compiler. Each project uses the correct option file |
| 247 | as its "prefix file" in the "C/C++ language" settings. Disabling optional modules (for the 68K |
| 248 | interpreter), building non-GUSI interpreters and various other things are accomplished by |
| 249 | modifying these files (and possibly changing the list of files included in the project window, of course). |
| 250 | |
| 251 | <DT> Python |
| 252 | <DD> Mac-specific parts of the core interpreter. |
| 253 | |
| 254 | <DT> Resources |
| 255 | <DD> Resource files needed to build the interpreter. |
| 256 | |
| 257 | <DT> Scripts |
| 258 | <DD> A collection of various mac-specific Python scripts. Some are essential, some are useful but few |
| 259 | are documented, so you will have to use your imagination to work them out. |
| 260 | |
| 261 | <DT> Unsupported |
| 262 | <DD> Modules that are not supported any longer but may still work with a little effort. |
| 263 | </DL> |
| 264 | |
| 265 | <H2>Building the 68K interpreter</H2> |
| 266 | |
| 267 | If you have all the optional libraries mentioned <A HREF="#optional">above</A> loaded buildin Python |
| 268 | for 68K macs is a breeze: open the project in the folder <code>build.mac68k.stand</code> and build it. |
| 269 | Do <em>not</em> run it yet, this will possibly result in a garbled preferences file. <p> |
| 270 | |
| 271 | First remove the <code>Python preferences</code> file |
| 272 | from your preference folder, only if you had an older version of Python installed. |
| 273 | (this is also what you do if you did not heed the last sentence of the |
| 274 | preceeding paragraph). Next, move the interpreter to the main Python folder (up one level) and run it |
| 275 | there. This will create a correct initial preferences file. You are now all set, and your tree |
| 276 | should be completely compatible with a binary-only distribution. Read the release notes |
| 277 | (<code>Relnotes-somethingorother</code>) and <code>ReadMeOrSuffer</code> in the <code>Mac</code> folder. |
| 278 | |
| 279 | <H2>Building the PPC interpreter</H2> |
| 280 | |
| 281 | First you build the interpreter, core library and applet skeleton in folder <code>build.macppc.stand</code>. |
| 282 | The order to build things is the following: |
| 283 | |
| 284 | <DL> |
| 285 | <DT> PythonCoreRuntime |
| 286 | <DD> A modified version of the MetroWerks runtime library that is suitable for Pythons' shared library |
| 287 | architecture. The sources all come from the MW distribution. |
| 288 | |
| 289 | <DT> PythonCore |
| 290 | <DD> The shared library that contains the bulk of the interpreter and its resources. It is a good idea to |
| 291 | immedeately put an alias to this shared library in the <code>Extensions</code> folder of your system folder. |
| 292 | Do exactly that: put an <em>alias</em> there, copying or moving the file will cause you grief later. |
| 293 | |
| 294 | <DT> PythonPPC |
| 295 | <DD> The interpreter. This is basically a routine to call out to the shared library. Because of the |
| 296 | organization of GUSI it also contains the Gusi settings resource (together with a ResEdit template, |
| 297 | so you can change the gusi settings should you feel like doing so). |
| 298 | Do <em>not</em> run it yet, this will possibly result in a garbled preferences file. <p> |
| 299 | |
| 300 | <DT> PythonApplet |
| 301 | <DD> The applet skeleton application. Very similar to <code>PythonPPC</code>, but it calls to a different |
| 302 | entrypoint in the core library. The <code>mkapplet</code> script will copy this complete file, and add |
| 303 | a <code>'PYC '</code> with the module to generate an applet. <p> |
| 304 | </DL> |
| 305 | |
| 306 | After creating the alias to <code>PythonCore</code> you should move <code>PythonPPC</code> to the main |
| 307 | Python folder. Next you remove any old <code>Python Preferences</code> file from the <code>Preferences</code> |
| 308 | folder (if you had python installed on your system before) and run the interpreter once to create the |
| 309 | correct preferences file. You should also make an alias to <code>PythonApplet</code> in the main Python |
| 310 | folder. (again: making an alias is preferrable to copying or moving the file, since this will cause the |
| 311 | correct file to be used if you ever rebuild PythonApplet). <p> |
| 312 | |
| 313 | Next, you have to build the extension modules in the <code>PlugIns</code> folder. Open each project and |
| 314 | build it. After all the dynamically loaded modules are built you have to create a number of aliases: some |
| 315 | modules live together in a single dynamic library. Copy or move the <code>MkPluginAliases.py</code> script |
| 316 | from <code>Mac:scripts</code> to the main python folder and run it. <p> |
| 317 | |
| 318 | Finally, you must build the standard applets: <code>EditPythonPrefs</code>, <code>mkapplet</code>, etc. This |
| 319 | is easiest done with the <code>fullbuild</code> script from <code>Mac:scripts</code>. Answer <em>no</em> to |
| 320 | all questions except when it asks whether to build the applets. <p> |
| 321 | |
| 322 | <BLOCKQUOTE> |
| 323 | Actually, the <code>fullbuild</code> script can be used to build everything, but you need a fully-functional |
| 324 | interpreter before you can use it (and one that isn't rebuilt in the process: you cannot rebuild a running |
| 325 | program). You could copy the 68K interpreter to a different place and use that to run fullbuild, or use the |
| 326 | standalone PPC python for this. I tend to keep a standalone interpreter in a safe place for this use only. |
| 327 | </BLOCKQUOTE> |
| 328 | |
| 329 | You are all set now, and should read the release notes and <code>ReadMeOrSuffer</code> file from |
| 330 | the <code>Mac</code> folder. |
| 331 | |
| 332 | <H2>Odds and ends</H2> |
| 333 | |
| 334 | Some remarks that I could not fit in elsewhere: |
| 335 | |
| 336 | <UL> |
| 337 | <LI> |
| 338 | It may be possible to use the <code>PythonCore</code> shared library to embed Python in |
| 339 | another program, if your program can live with using GUSI for I/O. Use PythonCore in stead of |
| 340 | your C library (or, at the very least, link it before the normal C library). Let me know whether this |
| 341 | works. |
| 342 | |
| 343 | <LI> |
| 344 | It is possible to build PPC extension modules without building a complete Python. Take the binary distribution, |
| 345 | add folders <code>Include</code>, <code>Mac:Include</code> and <code>Mac:mwerks</code> from the source |
| 346 | distribution and you should be all set. A template for a dynamic module can be found in <code>xxmodule.µ</code>. |
| 347 | |
| 348 | |
| 349 | <UL> |
| 350 | </BODY> |
| 351 | </HTML> |