Mac/Demo/building.html - platform/external/python/cpython2 - Gitiles

 <HTML>
 <HEAD>
 <TITLE>Building Mac Python from source</TITLE>
 </HEAD>
 <BODY>
 <H1>Building Mac Python from source</H1>
 <HR>

 This document explains how to build MacPython from source. This is
 necessary if you want to write extension modules for 68K Python, and
 currently also probably the easiest way to build PPC extension
 modules. Building Python is not something to be undertaken lightly,
 the process is not very streamlined so you need a reasonable working
 knowledge of the CodeWarrior development environment, a good net
 connection and probably quite some time too. <p>

 The information density in this file is high, so you should probably
 print it and read it at your leasure. Most things are explained only
 once (and probably in the wrong place:-). <p>

 I am very interested in feedback on this document, contact me at <A
 HREF="mailto:jack@cwi.nl">&lt;jack@cwi.nl&gt;</A> or send your
 comments to the <A
 HREF="http://www.python.org/sigs/pythonmac-sig/">Mac Python Special
 Interest Group</A>.

 <H2>What you need.</H2>

 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">
 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
 site</A>. Everything you need is also included in the standard Python
 source distribution, but the organization is different. Look in
 directory <code>Mac/mwerks/projects</code> for the project files and
 related stuff.

 <LI> You need MetroWerks CodeWarrior. The current distribution has
 been built with version 11 of CodeWarrior. Ordering information is
 available on the <A HREF="http://www.metrowerks.com/">MetroWerks
 homepage</A>. You might still be able to build Python with MPW or
 Think/Symantec C but you are basically on your own.

 <LI> You need GUSI, the Grand Unified Socket Interface, by Matthias
 Neeracher. The original CWGUSI is
 obtainable from <A
 HREF="ftp://sunsite.cnlab-switch.ch/software/platform/macos/src">
 ftp://sunsite.cnlab-switch.ch/software/platform/macos/src</A>.
 At the moment Python is built with a rather hacked-up version of GUSI,
 these modifications are available in folder <code>Python:Mac:GUSI-mods</code>.

 </UL>

 <A NAME="optional">The MacPython project files are configured to
 include a plethora of optional modules</A>, and these modules need a
 number extra packages. To use the project files as-is you have to
 download these packages too. PPC and CFM68K Python have all such modules as
 dynamically loaded modules, so if you don't need a certain package it
 suffices to just refrain from builing the extension module. For static 68K
 Python things are a bit more complicated: you have to edit the
 interpreter project file to remove the reference to the module (and
 the libraries it uses), and edit the <code>Mac:mwerks:mwerks_nonshared_config.h</code>
 file to remove the <code>USE_...</code> line.  Here are the locations for the various things
 you need:

 <UL>

 <LI> Tcl and Tk can be obtained from <A
 HREF="ftp://ftp.smli.com/pub/tcl/mac/">ftp://ftp.smli.com/pub/tcl/mac/</A>.
 The current distributions, Tcl 7.6 and Tk 4.2 need a bit of work,
 see the section on <A HREF="#tcltk">building Tcl/Tk Python</A>
 below. Get the "full source" distribution, which includes MoreFiles.

 <LI> Waste, a TextEdit replacement written by Marco Piovanelli, <A
 HREF="mailto:piovanel@kagi.com">&lt;piovanel@kagi.com&gt;</A>.  Python
 was built using version 1.2, which you can obtain from <A
 HREF="ftp://rhino.harvard.edu/pub/dan/WASTE">&lt;ftp://rhino.harvard.edu/pub/dan/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>.

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

 <LI> The netpbm/pbmplus, libtiff, zlib and png libraries. The netpbm distribution
 (which includes libtiff) is generally available on Internet ftp
 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.

 </UL>

 <H2>Setting Up</H2>

 Now that you have collected everything you should start with building
 the various parts.  If you don't want to fix
 access paths try to set things up as follows:

 <PRE>
 Top-level-folder:
 	CWGUSI
 	imglibs
 		libjpeg
 		pbmplus
 		libtiff
 		zlib
 		libpng
 	gdbm
 	MoreFiles 1.4.3 (not needed by Python, only by tcl/tk)
 	Python
 	Tcl 7.6
 	Tk 4.2
 	Waste 1.2 distribution (if you want waste)
 </PRE>

 First build GUSI. If you didn't get the python-specific GUSI you have to
 move the files from the "CWGUSI-mods" to the right
 place in the CWGUSI distribution folder. Build the
 projects <code>MSLGUSI.68K.µ</code>, <code>MSLGUSI.CFM68K.µ</code> and
 <code>MSLGUSI.PPC.µ</code>. <p>

 If you have a CWGUSI version more recent than
 1.8 it could be that the fixes are already included, check it.
 Next, in
 <code>MoreFiles</code>, <code>libjpeg</code>, <code>pbmplus</code>,
 <code>zlib</code>, <code>libpng</code>, <code>gdbm</code>,
 and<code>libtiff</code> you build all projects. Sometimes the projects are in "mac"
 subfolders, sometimes they are in the main folder. Tcl/tk is a special
 case, see below. Of course, if you are only interested in one of
 static 68K, CFM68K or PPC you can skip building the other libraries.

 <H2><A NAME="tcltk">Building Tcl/Tk</H2>

 You need to make some minor changes to the Tcl/Tk
 distribution. The current instructions are for the
 <code>tcl7.6</code> and <code>tk4.2</code> distribution:

 <UL>

 <LI> You have to change the access path setting and such to use the MSL
 libraries (this tcl/tk ditribution predates MSL).

 <LI> Rename the <code>compat</code> folders to <code>(compat)</code>
 in both the Tcl and Tk folders.

 <LI> In the Tcl folder, move <code>strncasecmp.c</code> and
 <code>tclErrno.h</code> from <code>(compat)</code> to the main Tcl
 folder.

 <LI> Fix <code>dnr.c</code> as provided by MetroWerks by inserting
 <pre><code> #pragma ANSI_strict off </code></pre> at the
 beginning. The tcl library is built with strict ANSI on, and this file
 uses C++ style comments.

 <LI> If you want to build <code>SimpleTcl</code> and
 <code>SimpleTk</code> you may  have to remove the references
 to <code>libmoto</code> from the project, not everyone has this library.

 <LI> If you want to build for CFM68K you have to create the projects
 for the libraries yourself. Take the 68K library projects, set the C++ header
 file to "MW_TclHeaderCFM68K", the project type to "cfm68K library" and the
 filename to "Tcl-CFM68K.Lib" (and similarly for Tk).
 You may also have to modify <code>TclMacNotify.c</code>
 because there is an error in the Apple Universal headers (sic!). Read the
 comments at the beginning of <code>Mac:Python:macglue.c</code> and copy the
 code to <code>TclMacNotify.c</code>. If you get linker errors on <code>GetEvQHdr</code>
 you have not done this correctly. <em>XXXX Is this still needed?</em>

 <LI> Note that if you use a different release of Tcl and Tk than the ones
 I have used you may have to adapt the Python <code>tkresources.rsrc</code> file.
 This is easiest done by building <code>SimpleTk</code> and copying the TEXT, ICON
 and CRSR resources from it to <code>tkresources.rsrc</code>. This allows
 the <code>_tkinter</code> module to work without an installed Tk/Tcl on your
 machine.

 </UL>

 Build first the Tcl library, then
 SimpleTcl (test it by typing <code>ls -l</code> in the window you get)
 then the Tk library, then SimpleTk (which can again be tested with
 <code>ls -l</code>). If this all worked you are all set to try
 building Python.

 <H2>Building Waste</H2>

 You do not need to build the Waste libraries, as Python includes the
 source modules themselves. You have to make one modification,
 though. In file <code>ICCFMGlue.c</code> in folder <code>Minimal IC
 APIs</code>, add the following lines:

 <blockquote><pre><code>
 #include <Gestalt.h>
 #include <Errors.h>
 </code></pre></blockquote>

 <H2>The organization of the Python source tree</H2>

 Time for a short break, while we have a look at the organization of
 the Python source tree.  At the top level, we find the following
 folders:

 <DL>
 <DT> build.mac68k.stand
 <DD> This is where you build static 68K interpreters.

 <DT> build.mac68k.shared
 <DD> This is where you build the CFM68K shared library, interpreter
 and applet framework.

 <DT> build.macppc.shared
 <DD> This is where you build the PPC shared library, interpreter and
 applet framework. You can also build the fat applet framework here.

 <DT> build.macppc.stand
 <DD> This is where you build a nonshared PPC interpreter (optional).

 <DT> Demo
 <DD> Demo programs that are not Mac-specific. Some of these may not
 work, the file <code>README-Mac</code> has some details.

 <DT> Extensions
 <DD> Extensions to the interpreter that are not Mac-specific. Contains
 only the <code>img</code> extension in this distribution. Extensions
 are <em>not</em> built here, as they are on Unix, but incorporated in
 the core interpreter or built as plugin modules.

 <DT> Grammar
 <DD> The Python grammar. Included for reference only, you cannot build
 the parser on a Mac.

 <DT> Include
 <DD> Machine-independent header files.

 <DT> Modules
 <DD> Machine-independent optional modules. Not all of these will work
 on the Mac.

 <DT> Objects
 <DD> Machine-independent code for various objects. Most of these are
 not really optional: the interpreter will not function without them.

 <DT> Parser
 <DD> The Python parser (machine-independent).

 <DT> PlugIns
 <DD> This is where you build the PPC and CFM68K dynamically-loaded plugin modules.

 <DT> Python
 <DD> The core interpreter. Most files are machine-independent, some
 are unix-specific and not used on the Mac.

 <DT> Tools
 <DD> Tools for python developers. Contains <code>modulator</code>
 which builds skeleton C extension modules and <code>bgen</code> which
 generates complete interface modules from information in C header
 files. There are some readme files, but more documentation is sorely
 needed.

 </DL>

 All the mac-specific stuff lives in the <code>Mac</code> folder:
 <DL>

 <DT> Compat
 <DD> Unix-compatability routines. Some of these are not used anymore,
 since CWGUSI provides a rather complete emulation, but you may need
 these if you are trying to build a non-GUSI python.

 <DT> Demo
 <DD> Mac-specific demo programs, some of them annotated.

 <DT> Include
 <DD> Mac-specific but compiler-independent include files.

 <DT> Lib
 <DD> Mac-specific standard modules. The <code>toolbox</code> folder
 contains modules specifically needed with various MacOS toolbox
 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>bgen</code>, in which case the bgen input files are included so
 you can attempt to regenerate them or extend them.

 <DT> MPW
 <DD> MPW-specific files. These have not been used or kept up-to-date
 for a long time, so use at your own risk.

 <DT> mwerks
 <DD> Mwerks-specific sources and headers. Contains glue code for
 Pythons shared-library architecture, a replacement for
 <code>malloc</code> and a directory with various projects for building
 variations on the Python interpreter. The <code>mwerks_*.h</code>
 files here are the option-setting files for the various interpreters
 and such, comparable to the unix command-line <code>-D</code> options
 to the compiler. Each project uses the correct option file as its
 "prefix file" in the "C/C++ language" settings. Disabling optional
 modules (for the 68K interpreter), building non-GUSI interpreters and
 various other things are accomplished by modifying these files (and
 possibly changing the list of files included in the project window, of
 course).

 <DT> Python
 <DD> Mac-specific parts of the core interpreter.

 <DT> Resources
 <DD> Resource files needed to build the interpreter.

 <DT> Scripts
 <DD> A collection of various mac-specific Python scripts. Some are
 essential, some are useful but few are documented, so you will have to
 use your imagination to work them out.

 <DT> Unsupported
 <DD> Modules that are not supported any longer but may still work with a little effort.
 </DL>

 <H2>Building the 68K interpreter</H2>

 If you have all the optional libraries mentioned <A
 HREF="#optional">above</A> loaded buildin Python for 68K macs is a
 breeze: open the project in the folder <code>build.mac68k.stand</code>
 and build it.  Do <em>not</em> run it yet, this will possibly result
 in a garbled preferences file. <p>

 First remove the <code>Python preferences</code> file from your
 preference folder, only if you had an older version of Python
 installed.  (this is also what you do if you did not heed the last
 sentence of the preceeding paragraph). Next, move the interpreter to
 the main Python folder (up one level) and run it there. This will
 create a correct initial preferences file. You are now all set, and
 your tree should be completely compatible with a binary-only
 distribution. Read the release notes
 (<code>Relnotes-somethingorother</code>) and
 <code>ReadMeOrSuffer</code> in the <code>Mac</code> folder.

 <H2>Building the CFM68K interpreter</H2>

 Building the CFM68K interpreter is as almost exactly the same as building
 the PPC interpreter, with the exception that you should read "CFM68K"
 for "PPC" every time. Continue reading with the next section.

 <H2>Building the PPC interpreter</H2>

 First you build the interpreter, core library and applet skeleton in
 folder <code>build.macppc.stand</code>.  The order to build things is
 the following:

 <DL>

 <DT> PythonCorePPC
 <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
 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.

 <DT> PythonPPC
 <DD> The interpreter. This is basically a routine to call out to the
 shared library. Do
 <em>not</em> run it yet, this will possibly result in a garbled
 preferences file. See the section below on rebuilding .exp files if you
 get funny linker errors. <p>

 <DT> PythonAppletPPC
 <DD> The applet skeleton application. Very similar to
 <code>PythonPPC</code>, but it calls to a different entrypoint in the
 core library. The <code>mkapplet</code> script will copy this complete
 file, and add a <code>'PYC '</code> with the module to generate an
 applet. <p>

 </DL>

 After creating the alias to <code>PythonCorePPC</code> you should move
 <code>PythonPPC</code> to the main Python folder. Next you remove any old
 <code>Python XXX 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. You should also make an alias
 <code>PythonApplet</code> pointing to <code>PythonAppletPPC</code> in the main
 Python folder. (again: making an alias is preferrable to copying or moving the
 file, since this will cause the correct file to be used if you ever rebuild
 PythonAppletPPC). <p>

 Next, you have to build the extension modules in the
 <code>PlugIns</code> folder. Open each project with <code>.ppc</code> in the
 name and build it. After all
 the dynamically loaded modules are built you have to create a number
 of aliases: some modules live together in a single dynamic
 library. Run the <code>MkPluginAliases.py</code> script from
 <code>Mac:scripts</code> to create the aliases. <p>

 Finally, you must build the standard applets:
 <code>EditPythonPrefs</code>, <code>mkapplet</code>, etc. This is
 easiest done with the <code>fullbuild</code> script from
 <code>Mac:scripts</code>. Answer <em>no</em> to all questions except
 when it asks whether to build the applets. <p>

 <BLOCKQUOTE>
 Actually, 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 68K interpreter to a different
 place and use that to run fullbuild, or use the standalone PPC python
 for this. I tend to keep a standalone interpreter in a safe place for
 this use only. <p>

 Using fullbuild is also the only easy way to buid the fat application and applet.
 See the fullbuild source for details on how to build the fat binaries "by hand".

 </BLOCKQUOTE>

 You are all set now, and should read the release notes and
 <code>ReadMeOrSuffer</code> file from the <code>Mac</code> folder.

 <H2>Rebuilding <code>.exp</code> files for PPC and CFM68K</H2>

 Occasionally it may be necessary to rebuild your PythonCore <code>.exp</code>
 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
 the symbols <code>__initialize</code>, <code>__terminate</code>, <code>setjmp</code>,
 <code>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>

 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
 those routines have to be in the same code fragment as they are used from.

 <H2>Odds and ends</H2>

 Some remarks that I could not fit in elsewhere:

 <UL>

 <LI> It may be possible to use the <code>PythonCore</code> shared
 library to embed Python in another program, if your program can live
 with using GUSI for I/O. Use PythonCore in stead of your MSL C library
 (or, at the very least, link it before the normal C library). Let me
 know whether this works.

 <LI> It is possible to build PPC extension modules without building a
 complete Python. Take the binary distribution, add folders
 <code>Include</code>, <code>Mac:Include</code> and
 <code>Mac:mwerks</code> from the source distribution and you should be
 all set. A template for a dynamic module can be found in
 <code>xx.ppc.µ</code> or <code>xx.CFM68K.µ</code>.

 <LI> The Python shared library architecture is a variant of the architecture
 described as "application with shared libraries and dropins" in the MetroWerks
 "Targeting MacOS" documentation. The Python Application and applet-template use
 the <code>MSL AppRuntime.Lib</code> runtime library (with properly set CFM
 initialization and termination routines). PythonCore uses <code>MSL Runtime.Lib</code>,
 which is really intended for standalone programs but which we fool into working by
 providing a dummy main program.
 It is linked statically into PythonCore (and exported to the applications and plugins)
 so we do not have to distribute yet another shared library. Plugin modules use
 <code>MSL ShlibRuntime.Lib</code> (not the dropin runtime: modules are never unloaded)
 and obtain the rest from PythonCore. PythonCore uses a
 non-standard initialization entry point, <code>__initialize_with_resources</code>, to
 be able to obtain resources from the library file later on. Plugins can do the same
 (_tkinter does) or use the standard <code>__initialize</code> entry point.


 </UL>
 </BODY>
 </HTML>
	<HTML>
	<HEAD>
	<TITLE>Building Mac Python from source</TITLE>
	</HEAD>
	<BODY>
	<H1>Building Mac Python from source</H1>
	<HR>

	This document explains how to build MacPython from source. This is
	necessary if you want to write extension modules for 68K Python, and
	currently also probably the easiest way to build PPC extension
	modules. Building Python is not something to be undertaken lightly,
	the process is not very streamlined so you need a reasonable working
	knowledge of the CodeWarrior development environment, a good net
	connection and probably quite some time too. <p>

	The information density in this file is high, so you should probably
	print it and read it at your leasure. Most things are explained only
	once (and probably in the wrong place:-). <p>

	I am very interested in feedback on this document, contact me at <A
	HREF="mailto:jack@cwi.nl"><jack@cwi.nl></A> or send your
	comments to the <A
	HREF="http://www.python.org/sigs/pythonmac-sig/">Mac Python Special
	Interest Group</A>.

	<H2>What you need.</H2>

	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">
	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
	site</A>. Everything you need is also included in the standard Python
	source distribution, but the organization is different. Look in
	directory <code>Mac/mwerks/projects</code> for the project files and
	related stuff.

	<LI> You need MetroWerks CodeWarrior. The current distribution has
	been built with version 11 of CodeWarrior. Ordering information is
	available on the <A HREF="http://www.metrowerks.com/">MetroWerks
	homepage</A>. You might still be able to build Python with MPW or
	Think/Symantec C but you are basically on your own.

	<LI> You need GUSI, the Grand Unified Socket Interface, by Matthias
	Neeracher. The original CWGUSI is
	obtainable from <A
	HREF="ftp://sunsite.cnlab-switch.ch/software/platform/macos/src">
	ftp://sunsite.cnlab-switch.ch/software/platform/macos/src</A>.
	At the moment Python is built with a rather hacked-up version of GUSI,
	these modifications are available in folder <code>Python:Mac:GUSI-mods</code>.

	</UL>

	<A NAME="optional">The MacPython project files are configured to
	include a plethora of optional modules</A>, and these modules need a
	number extra packages. To use the project files as-is you have to
	download these packages too. PPC and CFM68K Python have all such modules as
	dynamically loaded modules, so if you don't need a certain package it
	suffices to just refrain from builing the extension module. For static 68K
	Python things are a bit more complicated: you have to edit the
	interpreter project file to remove the reference to the module (and
	the libraries it uses), and edit the <code>Mac:mwerks:mwerks_nonshared_config.h</code>
	file to remove the <code>USE_...</code> line. Here are the locations for the various things
	you need:

	<UL>

	<LI> Tcl and Tk can be obtained from <A
	HREF="ftp://ftp.smli.com/pub/tcl/mac/">ftp://ftp.smli.com/pub/tcl/mac/</A>.
	The current distributions, Tcl 7.6 and Tk 4.2 need a bit of work,
	see the section on <A HREF="#tcltk">building Tcl/Tk Python</A>
	below. Get the "full source" distribution, which includes MoreFiles.

	<LI> Waste, a TextEdit replacement written by Marco Piovanelli, <A
	HREF="mailto:piovanel@kagi.com"><piovanel@kagi.com></A>. Python
	was built using version 1.2, which you can obtain from <A
	HREF="ftp://rhino.harvard.edu/pub/dan/WASTE"><ftp://rhino.harvard.edu/pub/dan/WASTE></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>.

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

	<LI> The netpbm/pbmplus, libtiff, zlib and png libraries. The netpbm distribution
	(which includes libtiff) is generally available on Internet ftp
	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.

	</UL>

	<H2>Setting Up</H2>

	Now that you have collected everything you should start with building
	the various parts. If you don't want to fix
	access paths try to set things up as follows:

	<PRE>
	Top-level-folder:
	CWGUSI
	imglibs
	libjpeg
	pbmplus
	libtiff
	zlib
	libpng
	gdbm
	MoreFiles 1.4.3 (not needed by Python, only by tcl/tk)
	Python
	Tcl 7.6
	Tk 4.2
	Waste 1.2 distribution (if you want waste)
	</PRE>

	First build GUSI. If you didn't get the python-specific GUSI you have to
	move the files from the "CWGUSI-mods" to the right
	place in the CWGUSI distribution folder. Build the
	projects <code>MSLGUSI.68K.µ</code>, <code>MSLGUSI.CFM68K.µ</code> and
	<code>MSLGUSI.PPC.µ</code>. <p>

	If you have a CWGUSI version more recent than
	1.8 it could be that the fixes are already included, check it.
	Next, in
	<code>MoreFiles</code>, <code>libjpeg</code>, <code>pbmplus</code>,
	<code>zlib</code>, <code>libpng</code>, <code>gdbm</code>,
	and<code>libtiff</code> you build all projects. Sometimes the projects are in "mac"
	subfolders, sometimes they are in the main folder. Tcl/tk is a special
	case, see below. Of course, if you are only interested in one of
	static 68K, CFM68K or PPC you can skip building the other libraries.

	<H2><A NAME="tcltk">Building Tcl/Tk</H2>

	You need to make some minor changes to the Tcl/Tk
	distribution. The current instructions are for the
	<code>tcl7.6</code> and <code>tk4.2</code> distribution:

	<UL>

	<LI> You have to change the access path setting and such to use the MSL
	libraries (this tcl/tk ditribution predates MSL).

	<LI> Rename the <code>compat</code> folders to <code>(compat)</code>
	in both the Tcl and Tk folders.

	<LI> In the Tcl folder, move <code>strncasecmp.c</code> and
	<code>tclErrno.h</code> from <code>(compat)</code> to the main Tcl
	folder.

	<LI> Fix <code>dnr.c</code> as provided by MetroWerks by inserting
	<pre><code> #pragma ANSI_strict off </code></pre> at the
	beginning. The tcl library is built with strict ANSI on, and this file
	uses C++ style comments.

	<LI> If you want to build <code>SimpleTcl</code> and
	<code>SimpleTk</code> you may have to remove the references
	to <code>libmoto</code> from the project, not everyone has this library.

	<LI> If you want to build for CFM68K you have to create the projects
	for the libraries yourself. Take the 68K library projects, set the C++ header
	file to "MW_TclHeaderCFM68K", the project type to "cfm68K library" and the
	filename to "Tcl-CFM68K.Lib" (and similarly for Tk).
	You may also have to modify <code>TclMacNotify.c</code>
	because there is an error in the Apple Universal headers (sic!). Read the
	comments at the beginning of <code>Mac:Python:macglue.c</code> and copy the
	code to <code>TclMacNotify.c</code>. If you get linker errors on <code>GetEvQHdr</code>
	you have not done this correctly. <em>XXXX Is this still needed?</em>

	<LI> Note that if you use a different release of Tcl and Tk than the ones
	I have used you may have to adapt the Python <code>tkresources.rsrc</code> file.
	This is easiest done by building <code>SimpleTk</code> and copying the TEXT, ICON
	and CRSR resources from it to <code>tkresources.rsrc</code>. This allows
	the <code>_tkinter</code> module to work without an installed Tk/Tcl on your
	machine.

	</UL>

	Build first the Tcl library, then
	SimpleTcl (test it by typing <code>ls -l</code> in the window you get)
	then the Tk library, then SimpleTk (which can again be tested with
	<code>ls -l</code>). If this all worked you are all set to try
	building Python.

	<H2>Building Waste</H2>

	You do not need to build the Waste libraries, as Python includes the
	source modules themselves. You have to make one modification,
	though. In file <code>ICCFMGlue.c</code> in folder <code>Minimal IC
	APIs</code>, add the following lines:

	<blockquote><pre><code>
	#include <Gestalt.h>
	#include <Errors.h>
	</code></pre></blockquote>

	<H2>The organization of the Python source tree</H2>

	Time for a short break, while we have a look at the organization of
	the Python source tree. At the top level, we find the following
	folders:

	<DL>
	<DT> build.mac68k.stand
	<DD> This is where you build static 68K interpreters.

	<DT> build.mac68k.shared
	<DD> This is where you build the CFM68K shared library, interpreter
	and applet framework.

	<DT> build.macppc.shared
	<DD> This is where you build the PPC shared library, interpreter and
	applet framework. You can also build the fat applet framework here.

	<DT> build.macppc.stand
	<DD> This is where you build a nonshared PPC interpreter (optional).

	<DT> Demo
	<DD> Demo programs that are not Mac-specific. Some of these may not
	work, the file <code>README-Mac</code> has some details.

	<DT> Extensions
	<DD> Extensions to the interpreter that are not Mac-specific. Contains
	only the <code>img</code> extension in this distribution. Extensions
	are <em>not</em> built here, as they are on Unix, but incorporated in
	the core interpreter or built as plugin modules.

	<DT> Grammar
	<DD> The Python grammar. Included for reference only, you cannot build
	the parser on a Mac.

	<DT> Include
	<DD> Machine-independent header files.

	<DT> Modules
	<DD> Machine-independent optional modules. Not all of these will work
	on the Mac.

	<DT> Objects
	<DD> Machine-independent code for various objects. Most of these are
	not really optional: the interpreter will not function without them.

	<DT> Parser
	<DD> The Python parser (machine-independent).

	<DT> PlugIns
	<DD> This is where you build the PPC and CFM68K dynamically-loaded plugin modules.

	<DT> Python
	<DD> The core interpreter. Most files are machine-independent, some
	are unix-specific and not used on the Mac.

	<DT> Tools
	<DD> Tools for python developers. Contains <code>modulator</code>
	which builds skeleton C extension modules and <code>bgen</code> which
	generates complete interface modules from information in C header
	files. There are some readme files, but more documentation is sorely
	needed.

	</DL>

	All the mac-specific stuff lives in the <code>Mac</code> folder:
	<DL>

	<DT> Compat
	<DD> Unix-compatability routines. Some of these are not used anymore,
	since CWGUSI provides a rather complete emulation, but you may need
	these if you are trying to build a non-GUSI python.

	<DT> Demo
	<DD> Mac-specific demo programs, some of them annotated.

	<DT> Include
	<DD> Mac-specific but compiler-independent include files.

	<DT> Lib
	<DD> Mac-specific standard modules. The <code>toolbox</code> folder
	contains modules specifically needed with various MacOS toolbox
	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>bgen</code>, in which case the bgen input files are included so
	you can attempt to regenerate them or extend them.

	<DT> MPW
	<DD> MPW-specific files. These have not been used or kept up-to-date
	for a long time, so use at your own risk.

	<DT> mwerks
	<DD> Mwerks-specific sources and headers. Contains glue code for
	Pythons shared-library architecture, a replacement for
	<code>malloc</code> and a directory with various projects for building
	variations on the Python interpreter. The <code>mwerks_*.h</code>
	files here are the option-setting files for the various interpreters
	and such, comparable to the unix command-line <code>-D</code> options
	to the compiler. Each project uses the correct option file as its
	"prefix file" in the "C/C++ language" settings. Disabling optional
	modules (for the 68K interpreter), building non-GUSI interpreters and
	various other things are accomplished by modifying these files (and
	possibly changing the list of files included in the project window, of
	course).

	<DT> Python
	<DD> Mac-specific parts of the core interpreter.

	<DT> Resources
	<DD> Resource files needed to build the interpreter.

	<DT> Scripts
	<DD> A collection of various mac-specific Python scripts. Some are
	essential, some are useful but few are documented, so you will have to
	use your imagination to work them out.

	<DT> Unsupported
	<DD> Modules that are not supported any longer but may still work with a little effort.
	</DL>

	<H2>Building the 68K interpreter</H2>

	If you have all the optional libraries mentioned <A
	HREF="#optional">above</A> loaded buildin Python for 68K macs is a
	breeze: open the project in the folder <code>build.mac68k.stand</code>
	and build it. Do <em>not</em> run it yet, this will possibly result
	in a garbled preferences file. <p>

	First remove the <code>Python preferences</code> file from your
	preference folder, only if you had an older version of Python
	installed. (this is also what you do if you did not heed the last
	sentence of the preceeding paragraph). Next, move the interpreter to
	the main Python folder (up one level) and run it there. This will
	create a correct initial preferences file. You are now all set, and
	your tree should be completely compatible with a binary-only
	distribution. Read the release notes
	(<code>Relnotes-somethingorother</code>) and
	<code>ReadMeOrSuffer</code> in the <code>Mac</code> folder.

	<H2>Building the CFM68K interpreter</H2>

	Building the CFM68K interpreter is as almost exactly the same as building
	the PPC interpreter, with the exception that you should read "CFM68K"
	for "PPC" every time. Continue reading with the next section.

	<H2>Building the PPC interpreter</H2>

	First you build the interpreter, core library and applet skeleton in
	folder <code>build.macppc.stand</code>. The order to build things is
	the following:

	<DL>

	<DT> PythonCorePPC
	<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
	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.

	<DT> PythonPPC
	<DD> The interpreter. This is basically a routine to call out to the
	shared library. Do
	<em>not</em> run it yet, this will possibly result in a garbled
	preferences file. See the section below on rebuilding .exp files if you
	get funny linker errors. <p>

	<DT> PythonAppletPPC
	<DD> The applet skeleton application. Very similar to
	<code>PythonPPC</code>, but it calls to a different entrypoint in the
	core library. The <code>mkapplet</code> script will copy this complete
	file, and add a <code>'PYC '</code> with the module to generate an
	applet. <p>

	</DL>

	After creating the alias to <code>PythonCorePPC</code> you should move
	<code>PythonPPC</code> to the main Python folder. Next you remove any old
	<code>Python XXX 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. You should also make an alias
	<code>PythonApplet</code> pointing to <code>PythonAppletPPC</code> in the main
	Python folder. (again: making an alias is preferrable to copying or moving the
	file, since this will cause the correct file to be used if you ever rebuild
	PythonAppletPPC). <p>

	Next, you have to build the extension modules in the
	<code>PlugIns</code> folder. Open each project with <code>.ppc</code> in the
	name and build it. After all
	the dynamically loaded modules are built you have to create a number
	of aliases: some modules live together in a single dynamic
	library. Run the <code>MkPluginAliases.py</code> script from
	<code>Mac:scripts</code> to create the aliases. <p>

	Finally, you must build the standard applets:
	<code>EditPythonPrefs</code>, <code>mkapplet</code>, etc. This is
	easiest done with the <code>fullbuild</code> script from
	<code>Mac:scripts</code>. Answer <em>no</em> to all questions except
	when it asks whether to build the applets. <p>

	<BLOCKQUOTE>
	Actually, 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 68K interpreter to a different
	place and use that to run fullbuild, or use the standalone PPC python
	for this. I tend to keep a standalone interpreter in a safe place for
	this use only. <p>

	Using fullbuild is also the only easy way to buid the fat application and applet.
	See the fullbuild source for details on how to build the fat binaries "by hand".

	</BLOCKQUOTE>

	You are all set now, and should read the release notes and
	<code>ReadMeOrSuffer</code> file from the <code>Mac</code> folder.

	<H2>Rebuilding <code>.exp</code> files for PPC and CFM68K</H2>

	Occasionally it may be necessary to rebuild your PythonCore <code>.exp</code>
	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
	the symbols <code>__initialize</code>, <code>__terminate</code>, <code>setjmp</code>,
	<code>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>

	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
	those routines have to be in the same code fragment as they are used from.

	<H2>Odds and ends</H2>

	Some remarks that I could not fit in elsewhere:

	<UL>

	<LI> It may be possible to use the <code>PythonCore</code> shared
	library to embed Python in another program, if your program can live
	with using GUSI for I/O. Use PythonCore in stead of your MSL C library
	(or, at the very least, link it before the normal C library). Let me
	know whether this works.

	<LI> It is possible to build PPC extension modules without building a
	complete Python. Take the binary distribution, add folders
	<code>Include</code>, <code>Mac:Include</code> and
	<code>Mac:mwerks</code> from the source distribution and you should be
	all set. A template for a dynamic module can be found in
	<code>xx.ppc.µ</code> or <code>xx.CFM68K.µ</code>.

	<LI> The Python shared library architecture is a variant of the architecture
	described as "application with shared libraries and dropins" in the MetroWerks
	"Targeting MacOS" documentation. The Python Application and applet-template use
	the <code>MSL AppRuntime.Lib</code> runtime library (with properly set CFM
	initialization and termination routines). PythonCore uses <code>MSL Runtime.Lib</code>,
	which is really intended for standalone programs but which we fool into working by
	providing a dummy main program.
	It is linked statically into PythonCore (and exported to the applications and plugins)
	so we do not have to distribute yet another shared library. Plugin modules use
	<code>MSL ShlibRuntime.Lib</code> (not the dropin runtime: modules are never unloaded)
	and obtain the rest from PythonCore. PythonCore uses a
	non-standard initialization entry point, <code>__initialize_with_resources</code>, to
	be able to obtain resources from the library file later on. Plugins can do the same
	(_tkinter does) or use the standard <code>__initialize</code> entry point.


	</UL>
	</BODY>
	</HTML>