Updated to the current state of things (long overdue).

Mac/Demo/building.html

@@ -6,12 +6,6 @@
 <H1>Building Mac Python from source</H1>
 <HR>
 
-<B>Note</B>: This document is mostly still for Python 2.0, so
-it is not correct. See the <a href="http://www.cwi.nl/~jack/macpython.html">
-MacPython homepage</a> for an updated version, and if none is available
-complain bitterly to me and work on it should progress faster.
-<p>
-
 This document explains how to build MacPython from source. This is
 necessary if you want to make modifications to the Python core. Building
 Python is not something to be undertaken lightly, you need a reasonable
@@ -41,9 +35,7 @@ The following things you definitely need:
 <UL>
 
 <LI> You need a MacPython source distribution, of course. You can
-obtain one from <A HREF="ftp://ftp.cwi.nl/pub/jack/python/mac">
-ftp://ftp.cwi.nl/pub/jack/python/mac</A> or from the companion webpage
-at <A HREF="http://www.cwi.nl/~jack/macpython.html">
+obtain one via <A HREF="http://www.cwi.nl/~jack/macpython.html">
 http://www.cwi.nl/~jack/macpython.html</A>  (which has up-to-date links
 to the other packages needed too) and possibly also from the standard
 <A HREF="ftp://ftp.python.org/pub/python/mac">python.org ftp
@@ -57,8 +49,8 @@ repository use</a> below.
 <LI> You need MetroWerks CodeWarrior. The current distribution has
 been built with CodeWarrior Pro 6.1. Ordering information is
 available on the <A HREF="http://www.metrowerks.com/">MetroWerks
-homepage</A>. Building Python with MPW or Think/Symantec C is
-probably impossible without major surgery.
+homepage</A>. Building Python with MPW, Think/Symantec C or the OSX
+developer tools is impossible without major surgery.
 
 <LI> You need GUSI version 2, the Grand Unified Socket Interface, by
 Matthias Neeracher. The original GUSI is obtainable from <A
@@ -68,11 +60,7 @@ the moment Python is built with a slightly modified version of GUSI
 2.1.1, so it may be better to check the <A
 HREF="http://www.cwi.nl/~jack/macpython.html">MacPython homepage</A>
 for a GUSI that is most easily used for building Python. 
-<br>
 
-If nothing is listed there (yet) you will have problems building a
-Carbon Python. Complaining loudly on the pythonmac-sig@python.org mailing
-list will make me work faster towards distributing Carbon-GUSI:-).
 </UL>
 
 <A NAME="optional">The MacPython project files are configured to
@@ -96,20 +84,18 @@ below.
 HREF="mailto:piovanel@kagi.com">&lt;piovanel@kagi.com&gt;</A>.  Python
 was built using version 2.0, which is included in the CodeWarrior
 package. You can also obtain it from <A
-HREF="http://www.boingo.com/waste">&lt;http://www.boingo.com/waste&gt;</A>
+HREF="http://www.merzwaren.com/waste">&lt;http://www.merzwaren.com/waste&gt;</A>
 and various other places.
 
 <LI> Gdbm library for the Mac. Available from Jack's Mac software page at
 <A HREF="http://www.cwi.nl/~jack/macsoftware.html">
 http://www.cwi.nl/~jack/macsoftware.html</A> and <A HREF="ftp://ftp.cwi.nl/pub/jack/mac">
-ftp://ftp.cwi.nl/pub/jack/mac</A>. Also in the MacPython cvs repository at
-<code>lib-src/gdbm</code>.
+ftp://ftp.cwi.nl/pub/jack/mac</A>. 
 
 <LI> JPEG library by the Independent JPEG Group. A version including
 Mac projects can be found at Jack's page mentioned above. 
 The most recent JPEG library can always be obtained from <A
-HREF="ftp://ftp.uu.net/graphics/jpeg/">ftp://ftp.uu.net/graphics/jpeg/</A>. Again,
-also in the MacPython cvs repository at <code>lib-src/jpeg</code>.
+HREF="ftp://ftp.uu.net/graphics/jpeg/">ftp://ftp.uu.net/graphics/jpeg/</A>. 
 
 <LI> The netpbm/pbmplus, libtiff, zlib and png libraries. The netpbm distribution
 (which includes libtiff) is generally available on Internet ftp
@@ -117,9 +103,7 @@ servers. For Python pbmplus, an older incarnation of netpbm, is
 functionally identical to netpbm, since Python only uses the library
 and not the complete applications. A distribution with correct
 projects and library source only is available from, you guessed it, Jack's Mac software
-page mentioned above. And, guessed it again, in the MacPython cvs repository
-at <code>lib-src/netpbm</code>, etc. The only gotcha is that libtiff lives in
-<code>lib-src/netpbm/libtiff</code>, for historical reasons.
+page mentioned above. 
 
 </UL>
 
@@ -279,7 +263,7 @@ interface modules.
 <DT> Modules
 <DD> Mac-specific builtin modules. Theoretically these are all
 optional, but some are rather essential (like
-<code>macmodule</code>). A lot of these modules are generated with
+<code>macosmodule</code>). A lot of these modules are generated with
 <code>bgen</code>, in which case the bgen input files are included so
 you can attempt to regenerate them or extend them.
 
@@ -327,40 +311,36 @@ but for more control over the freezing process you can run the main script here.
 <DD> Modules that are not supported any longer but may still work with a little effort.
 </DL>
 
-<H2>Building the 68K interpreter</H2>
-
-68K Python is no longer supported, and the projects are not included in the
-source distribution anymore. If you really want to build Python for the 68K
-your best bet is to check the sources out of the CVS repository. The latest
-projects (in :Mac:build:) that support 68K development are tagged as such,
-and are dated around August 2000. If you plan on doing this announce it on
-the SIG, please. <p>
-
 <H2>Building the PPC interpreter</H2>
 <em>This is different under 2.1. You are best off using the fullbuild.py
-script. </em><p>
+script, see <a href="#fullbuild">below</a>. </em><p>
+
 First you optionally build the external libraries with buildlibs.prj. Next, 
 the projects for
-interpreter, core library and applet skeleton  are all linked together, so
-building the PythonInterpreter target in <code>PythonEngine.prj</code> 
-will result in everything being built. The
-resulting applications and fat shared library are deposited in the main
-Python folder. Finally, you build all the plugins with the plugins.prj project.
+interpreter and core library are linked together, so
+building the PythonInterpreterClassic and/or PythonInterpreterCarbon target
+in <code>PythonInterpreter.prj</code> 
+will result in everything being built. The result, however, is an "Application
+template", (filetype Atmp). If you don't use fullbuild you can manually
+turn either of these into an interpreter by copying it to PythonInterpreter
+and setting the filetype to APPL (with ResEdit or some such). <p>
+
+Fullbuild does this for you, and the Atmp files is also how ConfigurePythonCarbon
+and ConfigurePythonClassic work their magic. <p>
 
 For completeness sake here is a breakdown of the projects:
 
 <DL>
 
-<DT> PythonCore (with subproject PythonCorePPC)
+<DT> PythonCore
 <DD> The shared library that contains the bulk of the interpreter and
-its resources. It is a good idea to immedeately put an alias to this
+its resources. It has targets for PythonCore and PythonCoreCarbon.
+It is a good idea to immedeately put an alias to this
 shared library in the <code>Extensions</code> folder of your system
 folder.  Do exactly that: put an <em>alias</em> there, copying or
 moving the file will cause you grief later if you rebuild the library and
-forget to copy it to the extensions folder again. The InstallPython applet
-will also do this, along with creating the plugin aliases. <br>
-Note that the subproject looks a bit silly nowadays (with no more CFM68K
-support) but you will have to live with that for this release.
+forget to copy it to the extensions folder again. The ConfigurePythonXXX applets
+will also do this. <br>
 
 <DT> PythonInterpeter
 <DD> The interpreter. This is basically a routine to call out to the
@@ -368,28 +348,28 @@ shared library. Unlike in previous releases the same program is used for
 creating applets (for which formerly PythonApplet was used). <p>
 
 <DT> Plugin projects
-<DD> Each plugin module has a separate project. The <code>Plugins.prj</code>
-project tries to build them all, but is known to be flakey. See <code>fullbuild</code>
-below for a better way to build everything.
+<DD> Each plugin module has a separate project, and these can be rebuilt on
+the fly. Fullbuild (or actually it's little helper genpluginprojects) takes
+care of this.
 </DL>
 
 After creating the alias to <code>PythonCore</code> you remove any old
-<code>Python 2.0b1 Preferences</code> file from the <code>Preferences</code> folder
+<code>Python XXXX Preferences</code> file from the <code>Preferences</code> folder
 (if you had python installed on your system before) and run the interpreter once
 to create the correct preferences file.  <p>
 
 Next, you have to build the extension modules.
-The <code>PlugIns.ppc</code> project has all the
-other projects as subprojects and builds everything (but see the gotcha above).
+If you don't use fullbuild simply open each project and build it.
 <p>
 
 Finally, you must build the standard applets:
-<code>EditPythonPrefs</code>, <code>BuildApplet</code>, etc. This is
-easiest done with the <code>fullbuild</code> script from
-<code>Mac:scripts</code>. <p>
+<code>EditPythonPrefs</code>, <code>BuildApplet</code>, etc. For the N-th time:
+fullbuild does this for you, but you can also manually drag/drop them onto
+BuildApplet. <p>
 
 <BLOCKQUOTE>
-Actually, the <code>fullbuild</code> script can be used to build
+<a name="fullbuild"></a>
+The <code>fullbuild</code> script can be used to build
 everything, but you need a fully-functional interpreter before you can
 use it (and one that isn't rebuilt in the process: you cannot rebuild
 a running program). You could copy the interpreter to a different
@@ -409,14 +389,17 @@ file, a file that controls which symbols are exported by your PythonCore
 shared library. Rebuild it if you get unexpected undefined symbols when you
 are building a plugin module. <p>
 
-Rebuilding the .exp file is done by first removing the file and removing the
-reference to it in the project (in the "config" section). Next, build PythonCore.
-This will create a new .exp file. Edit this file to remove the references to
+Rebuilding the .exp file is done by first both removing the file and removing the
+reference to it in the project (in the "config" section). Next, build PythonCore or
+PythonCoreCarbon.
+This will create a new .exp file, with the name <code>PythonCore.mcp.exp</code>.
+Rename this file to either <code>PythonCore.exp</code> or <code>PythonCoreCarbon.exp</code>
+and add this file back to the project. Next, edit ot to remove the references to
 the symbols <code>__initialize</code>, <code>__terminate</code>, <code>setjmp</code>,
-<code>longjmp</code>, <code>vec_longjmp</code>, <code>main</code> and (for PPC) <code>__ptmf_null</code> or (for
-CFM68K) <code>__start</code> and <code>dummy_init_routine</code>.
-Next, add the .exp file to the project
-again and rebuild PythonCore. <p>
+<code>longjmp</code>, <code>vec_longjmp</code>, <code>main</code> and <code>__ptmf_null</code>.
+They are all close together about halfway the file.
+
+Finally rebuild again. <p>
 
 This rather convoluted procedure is needed to ensure that plugin modules don't
 accidentally link with those entrypoints from PythonCore, which will not work because
@@ -424,9 +407,6 @@ those routines have to be in the same code fragment as they are used from.
 
 <H2><a name="cvs">Using the CVS source archive</a></H2>
 
-<em>Please check the MacPython homepage to see whether this information is
-still current: MacPython should move to sourceforge shortly. </em><p>
-
 It is possible (and probably best) to access the Python sources through remote CVS. The
 advantage of this is that you get the very latest sources, so any bug
 fixed or new features will be immedeately available. This is also the
@@ -441,41 +421,31 @@ also set (in the "binary files" section) "use mac encoding:
 applesingle" and (in the "text files" section) "use ISO latin 1
 conversion". <p>
 
-It is also a good idea to disable Quicktime Exchange in the Quicktime
+<blockquote>
+There is one group of people for whom MacCVS is not the best choice: people with
+checkin rights to the Python repository. You will have to use MacCVS Pro
+(completely unrelated) from www.maccvs.org, because it has working SSH support.
+</blockquote>
+
+It is a good idea to disable Quicktime Exchange in the Quicktime
 control panel. Quicktime Exchange will magically map some extensions to
 filetypes, and this can seriously hinder you if, for instance, <code>.bmp</code>
 is not a Windows bitmap file. <p>
 
-The machine-independent Python sources are checked out from the main
+The Python sources are checked out from the main
 Python CVS archive on sourceforge.net, see the <a
 href="http://www.python.org/download/cvs.html">Source access via
 CVS</a> page for details. When you check the sources out you will get
 something like <code>Python:dist:src</code>, and under that the
-<code>Modules</code>, <code>Lib</code>, etc hierarchy. The
-<code>src</code> folder should be renamed to <code>Python</code>, and
+<code>Modules</code>, <code>Lib</code>, <code>Mac</code> etc hierarchy. The
+<code>src</code> folder can be renamed to <code>Python</code>, and
 is what this document refers to as the "toplevel Python folder". <P>
 
-Next, <em>in a separate folder</em>, you check out the
-mac-specific sources. You then move the <code>Mac</code> folder from this
-checkout (the only folder with anything in it) to the Python source folder.
-Note that the checking out in a separate folder and moving is necessary,
-due to the way cvs works.
-
-The CVS path to use for the mac stuff can be found
-at the <a href="http://www.cwi.nl/~jack/macpython.html">MacPython
-homepage</a>. Finally, you check out the external libraries needed in
-the parent of the toplevel Python folder. The CVS path for these libraries is
-also mentioned at the MacPython homepage. <p>
-
-
-You should end up with a folder structure as described at the top of this
-document. <p>
-
-Note that while the Mac folder is now a subfolder of your toplevel Python
-folder this does not mean that they "act as one" as far as CVS is concerned.
-To update all your sources you have to do a "cvs update" in the toplevel
-Python folder and another one in the Mac folder. This is again a cvs problem:
-it cannot deal with subpackages coming from different repositories. <p>
+The CVS repository does not contain all the projects for the plugin modules,
+these are built with <code>fullbuild.py</code> normally. For this reason
+it is probably a good idea to first build <code>PythonStandSmall.prj</code>,
+which builds a fairly minimal interpreter, and then follow the
+<a href="#fullbuild">fullbuild instructions</a>.
 
 <H2>Odds and ends</H2>