Blame - Mac/Demo/building.html - platform/external/python/cpython3

blob: 7021537640092a4fa5e0f0f4fd33b6d6b1391b6f [file] [log] [blame]

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>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	8
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	9	This document explains how to build MacPython from source. This is
				10	necessary if you want to write extension modules for 68K Python, and
				11	currently also probably the easiest way to build PPC extension
				12	modules. Building Python is not something to be undertaken lightly,
				13	the process is not very streamlined so you need a reasonable working
				14	knowledge of the CodeWarrior development environment, a good net
				15	connection and probably quite some time too. <p>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	16
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	17	The information density in this file is high, so you should probably
				18	print it and read it at your leasure. Most things are explained only
				19	once (and probably in the wrong place:-). <p>
				20
				21	I am very interested in feedback on this document, contact me at <A
				22	HREF="mailto:jack@cwi.nl"><jack@cwi.nl></A> or send your
				23	comments to the <A
				24	HREF="http://www.python.org/sigs/pythonmac-sig/">Mac Python Special
				25	Interest Group</A>.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	26
				27	<H2>What you need.</H2>
				28
				29	The following things you definitely need:
				30
				31	<UL>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	32
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	33	<LI> You need a MacPython source distribution, of course. You can
				34	obtain one from <A
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame^]	35	HREF="ftp://ftp.cwi.nl/pub/jack/python/mac">ftp://ftp.cwi.nl/pub/jack/python/mac</A>
				36	or from the companion webpage at <A HREF="http://www.cwi.nl/~jack/macpython.html">
				37	http://www.cwi.nl/~jack/macpython.html</A> (which has up-to-date links to the other
				38	packages needed too)
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	39	and possibly also from the standard <A
				40	HREF="ftp://ftp.python.org/pub/python/mac">python.org ftp
				41	site</A>. Everything you need is also included in the standard Python
				42	source distribution, but the organization is different. Look in
				43	directory <code>Mac/mwerks/projects</code> for the project files and
				44	related stuff.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	45
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	46	<LI> You need MetroWerks CodeWarrior. The current distribution has
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame^]	47	been built with version 11 of CodeWarrior. Ordering information is
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	48	available on the <A HREF="http://www.metrowerks.com/">MetroWerks
				49	homepage</A>. You might still be able to build Python with MPW or
				50	Think/Symantec C but you are basically on your own.
				51
				52	<LI> You need GUSI, the Grand Unified Socket Interface, by Matthias
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame^]	53	Neeracher. The original CWGUSI is
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	54	obtainable from <A
Jack Jansen	f3dd5aa	1996-12-23 17:29:51 +0000	[diff] [blame]	55	HREF="ftp://sunsite.cnlab-switch.ch/software/platform/macos/src">
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame^]	56	ftp://sunsite.cnlab-switch.ch/software/platform/macos/src</A>,
				57	but at the moment Python is built with a rather hacked-up version of GUSI,
				58	available from Jack's Python webpage and ftp-directory referenced above.
				59	It is also possible to build a non-GUSI Python, see below.
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	60
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	61	</UL>
				62
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	63	<A NAME="optional">The MacPython project files are configured to
				64	include a plethora of optional modules</A>, and these modules need a
				65	number extra packages. To use the project files as-is you have to
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	66	download these packages too. PPC and CFM68K Python have all such modules as
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	67	dynamically loaded modules, so if you don't need a certain package it
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	68	suffices to just refrain from builing the extension module. For static 68K
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	69	Python things are a bit more complicated: you have to edit the
				70	interpreter project file to remove the reference to the module (and
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	71	the libraries it uses), and edit the <code>Mac:mwerks:mwerks_nonshared_config.h</code>
				72	file to remove the <code>USE_...</code> line. Here are the locations for the various things
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	73	you need:
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	74
				75	<UL>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	76
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	77	<LI> Tcl and Tk can be obtained from <A
				78	HREF="ftp://ftp.smli.com/pub/tcl/mac/">ftp://ftp.smli.com/pub/tcl/mac/</A>.
Jack Jansen	f3dd5aa	1996-12-23 17:29:51 +0000	[diff] [blame]	79	The current distributions, Tcl 7.6 and Tk 4.2 need a bit of work,
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	80	see the section on <A HREF="#tcltk">building Tcl/Tk Python</A>
				81	below. Get the "full source" distribution, which includes MoreFiles.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	82
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	83	<LI> Waste, a TextEdit replacement written by Marco Piovanelli, <A
				84	HREF="mailto:piovanel@kagi.com"><piovanel@kagi.com></A>. Python
				85	was built using version 1.2, which you can obtain from <A
				86	HREF="ftp://rhino.harvard.edu/pub/dan/WASTE"><ftp://rhino.harvard.edu/pub/dan/WASTE></A>
				87	and various other places.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	88
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame^]	89	<LI> Gdbm library for the Mac. Available from Jack's Mac software page at
				90	<A HREF="http://www.cwi.nl/~jack/macsoftware.html">
				91	http://www.cwi.nl/~jack/macsoftware.html</A> and <A HREF="ftp://ftp.cwi.nl/pub/jack/mac">
				92	ftp://ftp.cwi.nl/pub/jack/mac</A>.
				93
				94	<LI> JPEG library by the Independent JPEG Group. A version including
				95	Mac projects can be found at Jack's page mentioned above.
				96	The most recent JPEG library can always be obtained from <A
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	97	HREF="ftp://ftp.uu.net/graphics/jpeg/">ftp://ftp.uu.net/graphics/jpeg/</A>.
				98
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame^]	99	<LI> The netpbm/pbmplus, libtiff, zlib and png libraries. The netpbm distribution
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	100	(which includes libtiff) is generally available on Internet ftp
				101	servers. For Python pbmplus, an older incarnation of netpbm, is
				102	functionally identical to netpbm, since Python only uses the library
				103	and not the complete applications. A distribution with correct
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame^]	104	projects and library source only is available from, you guessed it, Jack's Mac software
				105	page mentioned above.
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	106
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	107	</UL>
				108
				109	<H2>Setting Up</H2>
				110
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	111	Now that you have collected everything you should start with building
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame^]	112	the various parts. If you don't want to fix
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	113	access paths try to set things up as follows:
				114
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	115	<PRE>
				116	Top-level-folder:
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	117	CWGUSI
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	118	imglibs
				119	libjpeg
				120	pbmplus
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame^]	121	libtiff
				122	zlib
				123	libpng
				124	gdbm
Jack Jansen	f3dd5aa	1996-12-23 17:29:51 +0000	[diff] [blame]	125	MoreFiles 1.4.3 (not needed by Python, only by tcl/tk)
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	126	Python
Jack Jansen	f3dd5aa	1996-12-23 17:29:51 +0000	[diff] [blame]	127	Tcl 7.6
				128	Tk 4.2
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	129	Waste 1.2 distribution (if you want waste)
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	130	</PRE>
				131
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame^]	132	First build GUSI. If you didn't get the python-specific GUSI you have to
				133	move the files from the "CWGUSI-mods" to the right
Jack Jansen	16e99c0	1996-09-07 17:11:26 +0000	[diff] [blame]	134	place in the CWGUSI distribution folder, and build the
Jack Jansen	abc2db7	1996-11-09 18:48:49 +0000	[diff] [blame]	135	projects <code>GUSI.68K.µ</code>, <code>GUSI.CFM68K.µ</code> and
				136	<code>GUSI.PPC.µ</code>.
				137	Two notes:
				138	<ul>
				139	<li> The projects as distributed have a slightly incorrect access path, due
				140	to which they cannot find their <code>GUSICWFile.???</code> files. Change
				141	the access path to <code>{project folder}::</code> to fix this.
				142	<li> The Gusi CFM68K project is
				143	distributed without "far data": you should set this option before building.
				144	</ul>
Jack Jansen	319f1a2	1996-10-16 15:28:30 +0000	[diff] [blame]	145	If you have a CWGUSI version more recent than
Jack Jansen	abc2db7	1996-11-09 18:48:49 +0000	[diff] [blame]	146	1.8 it could be that the fixes are already included, check it. Alternatively,
Jack Jansen	16e99c0	1996-09-07 17:11:26 +0000	[diff] [blame]	147	you can forget about the fixes and remove the one reference to GUSILoadPreferences
				148	in the Python sources. This will disable the "default file creator/type" and
				149	"Delay Sioux window" preferences in Python.
				150
				151	Next, in
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame^]	152	<code>MoreFiles</code>, <code>libjpeg</code>, <code>pbmplus</code>,
				153	<code>zlib</code>, <code>libpng</code>, <code>gdbm</code>,
				154	and<code>libtiff</code> you build all projects. Sometimes the projects are in "mac"
				155	subfolders, sometimes they are in the main folder. Tcl/tk is a special
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	156	case, see below. Of course, if you are only interested in one of
				157	static 68K, CFM68K or PPC you can skip building the other libraries.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	158
				159	<H2><A NAME="tcltk">Building Tcl/Tk</H2>
				160
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	161	You need to make a minor organizational change to the Tcl/Tk
				162	distribution. The current instructions are for the
Jack Jansen	f3dd5aa	1996-12-23 17:29:51 +0000	[diff] [blame]	163	<code>tcl7.6</code> and <code>tk4.2</code> distribution:
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	164
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	165	<UL>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	166
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	167	<LI> Rename the <code>compat</code> folders to <code>(compat)</code>
				168	in both the Tcl and Tk folders.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	169
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	170	<LI> In the Tcl folder, move <code>strncasecmp.c</code> and
				171	<code>tclErrno.h</code> from <code>(compat)</code> to the main Tcl
				172	folder.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	173
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	174	<LI> Fix <code>dnr.c</code> as provided by MetroWerks by inserting
				175	<pre><code> #pragma ANSI_strict off </code></pre> at the
				176	beginning. The tcl library is built with strict ANSI on, and this file
				177	uses C++ style comments.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	178
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	179	<LI> If you want to build <code>SimpleTcl</code> and
Jack Jansen	f3dd5aa	1996-12-23 17:29:51 +0000	[diff] [blame]	180	<code>SimpleTk</code> you may have to remove the references
				181	to <code>libmoto</code> from the project, not everyone has this library.
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	182
Jack Jansen	f3dd5aa	1996-12-23 17:29:51 +0000	[diff] [blame]	183	<LI> If you want to build for CFM68K you have to create the projects
				184	for the libraries yourself. Take the 68K library projects, set the C++ header
				185	file to "MW_TclHeaderCFM68K", the project type to "cfm68K library" and the
				186	filename to "Tcl-CFM68K.Lib" (and similarly for Tk).
				187	You may also have to modify <code>TclMacNotify.c</code>
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	188	because there is an error in the Apple Universal headers (sic!). Read the
				189	comments at the beginning of <code>Mac:Python:macglue.c</code> and copy the
				190	code to <code>TclMacNotify.c</code>. If you get linker errors on <code>GetEvQHdr</code>
Jack Jansen	f3dd5aa	1996-12-23 17:29:51 +0000	[diff] [blame]	191	you have not done this correctly. <em>XXXX Is this still needed?</em>
				192
				193	<LI> Note that if you use a different release of Tcl and Tk than the ones
				194	I have used you may have to adapt the Python <code>tkresources.rsrc</code> file.
				195	This is easiest done by building <code>SimpleTk</code> and copying the TEXT, ICON
				196	and CRSR resources from it to <code>tkresources.rsrc</code>. This allows
				197	the <code>_tkinter</code> module to work without an installed Tk/Tcl on your
				198	machine.
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	199
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame^]	200	<LI> You have to adapt the projects to use the MSL libraries. This is important.
				201
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	202	</UL>
				203
Jack Jansen	f3dd5aa	1996-12-23 17:29:51 +0000	[diff] [blame]	204	Build first the Tcl library, then
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	205	SimpleTcl (test it by typing <code>ls -l</code> in the window you get)
				206	then the Tk library, then SimpleTk (which can again be tested with
				207	<code>ls -l</code>). If this all worked you are all set to try
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	208	building Python.
				209
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	210	<H2>Building Waste</H2>
				211
				212	You do not need to build the Waste libraries, as Python includes the
				213	source modules themselves. You have to make one modification,
				214	though. In file <code>ICCFMGlue.c</code> in folder <code>Minimal IC
				215	APIs</code>, add the following lines:
				216
				217	<blockquote><pre><code>
				218	#include <Gestalt.h>
				219	#include <Errors.h>
				220	</code></pre></blockquote>
				221
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	222	<H2>The organization of the Python source tree</H2>
				223
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	224	Time for a short break, while we have a look at the organization of
				225	the Python source tree. At the top level, we find the following
				226	folders:
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	227
				228	<DL>
				229	<DT> build.mac68k.stand
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame^]	230	<DD> This is where you build static 68K interpreters.
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	231
				232	<DT> build.mac68k.shared
				233	<DD> This is where you build the CFM68K shared library, interpreter
				234	and applet framework.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	235
				236	<DT> build.macppc.shared
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	237	<DD> This is where you build the PPC shared library, interpreter and
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	238	applet framework. You can also build the fat applet framework here.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	239
				240	<DT> build.macppc.stand
				241	<DD> This is where you build a nonshared PPC interpreter (optional).
				242
				243	<DT> Demo
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	244	<DD> Demo programs that are not Mac-specific. Some of these may not
				245	work, the file <code>README-Mac</code> has some details.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	246
				247	<DT> Extensions
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	248	<DD> Extensions to the interpreter that are not Mac-specific. Contains
				249	only the <code>img</code> extension in this distribution. Extensions
				250	are <em>not</em> built here, as they are on Unix, but incorporated in
				251	the core interpreter or built as plugin modules.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	252
				253	<DT> Grammar
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	254	<DD> The Python grammar. Included for reference only, you cannot build
				255	the parser on a Mac.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	256
				257	<DT> Include
				258	<DD> Machine-independent header files.
				259
				260	<DT> Modules
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	261	<DD> Machine-independent optional modules. Not all of these will work
				262	on the Mac.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	263
				264	<DT> Objects
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	265	<DD> Machine-independent code for various objects. Most of these are
				266	not really optional: the interpreter will not function without them.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	267
				268	<DT> Parser
				269	<DD> The Python parser (machine-independent).
				270
				271	<DT> PlugIns
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	272	<DD> This is where you build the PPC and CFM68K dynamically-loaded plugin modules.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	273
				274	<DT> Python
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	275	<DD> The core interpreter. Most files are machine-independent, some
				276	are unix-specific and not used on the Mac.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	277
				278	<DT> Tools
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	279	<DD> Tools for python developers. Contains <code>modulator</code>
				280	which builds skeleton C extension modules and <code>bgen</code> which
				281	generates complete interface modules from information in C header
				282	files. There are some readme files, but more documentation is sorely
				283	needed.
				284
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	285	</DL>
				286
				287	All the mac-specific stuff lives in the <code>Mac</code> folder:
				288	<DL>
				289
				290	<DT> Compat
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	291	<DD> Unix-compatability routines. Some of these are not used anymore,
				292	since CWGUSI provides a rather complete emulation, but you may need
				293	these if you are trying to build a non-GUSI python.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	294
				295	<DT> Demo
				296	<DD> Mac-specific demo programs, some of them annotated.
				297
				298	<DT> Include
				299	<DD> Mac-specific but compiler-independent include files.
				300
				301	<DT> Lib
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	302	<DD> Mac-specific standard modules. The <code>toolbox</code> folder
				303	contains modules specifically needed with various MacOS toolbox
				304	interface modules.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	305
				306	<DT> Modules
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	307	<DD> Mac-specific builtin modules. Theoretically these are all
				308	optional, but some are rather essential (like
				309	<code>macmodule</code>). A lot of these modules are generated with
				310	<code>bgen</code>, in which case the bgen input files are included so
				311	you can attempt to regenerate them or extend them.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	312
				313	<DT> MPW
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	314	<DD> MPW-specific files. These have not been used or kept up-to-date
				315	for a long time, so use at your own risk.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	316
				317	<DT> mwerks
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	318	<DD> Mwerks-specific sources and headers. Contains glue code for
				319	Pythons shared-library architecture, a replacement for
				320	<code>malloc</code> and a directory with various projects for building
				321	variations on the Python interpreter. The <code>mwerks_*.h</code>
				322	files here are the option-setting files for the various interpreters
				323	and such, comparable to the unix command-line <code>-D</code> options
				324	to the compiler. Each project uses the correct option file as its
				325	"prefix file" in the "C/C++ language" settings. Disabling optional
				326	modules (for the 68K interpreter), building non-GUSI interpreters and
				327	various other things are accomplished by modifying these files (and
				328	possibly changing the list of files included in the project window, of
				329	course).
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	330
				331	<DT> Python
				332	<DD> Mac-specific parts of the core interpreter.
				333
				334	<DT> Resources
				335	<DD> Resource files needed to build the interpreter.
				336
				337	<DT> Scripts
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	338	<DD> A collection of various mac-specific Python scripts. Some are
				339	essential, some are useful but few are documented, so you will have to
				340	use your imagination to work them out.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	341
				342	<DT> Unsupported
				343	<DD> Modules that are not supported any longer but may still work with a little effort.
				344	</DL>
				345
				346	<H2>Building the 68K interpreter</H2>
				347
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	348	If you have all the optional libraries mentioned <A
				349	HREF="#optional">above</A> loaded buildin Python for 68K macs is a
				350	breeze: open the project in the folder <code>build.mac68k.stand</code>
				351	and build it. Do <em>not</em> run it yet, this will possibly result
				352	in a garbled preferences file. <p>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	353
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	354	First remove the <code>Python preferences</code> file from your
				355	preference folder, only if you had an older version of Python
				356	installed. (this is also what you do if you did not heed the last
				357	sentence of the preceeding paragraph). Next, move the interpreter to
				358	the main Python folder (up one level) and run it there. This will
				359	create a correct initial preferences file. You are now all set, and
				360	your tree should be completely compatible with a binary-only
				361	distribution. Read the release notes
				362	(<code>Relnotes-somethingorother</code>) and
				363	<code>ReadMeOrSuffer</code> in the <code>Mac</code> folder.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	364
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	365	<H2>Building the CFM68K interpreter</H2>
				366
				367	Building the CFM68K interpreter is as almost exactly the same as building
				368	the PPC interpreter, with the exception that you should read "CFM68K"
				369	for "PPC" every time. Continue reading with the next section.
				370
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	371	<H2>Building the PPC interpreter</H2>
				372
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	373	First you build the interpreter, core library and applet skeleton in
				374	folder <code>build.macppc.stand</code>. The order to build things is
				375	the following:
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	376
				377	<DL>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	378
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	379	<DT> PythonCorePPC
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	380	<DD> The shared library that contains the bulk of the interpreter and
				381	its resources. It is a good idea to immedeately put an alias to this
				382	shared library in the <code>Extensions</code> folder of your system
				383	folder. Do exactly that: put an <em>alias</em> there, copying or
				384	moving the file will cause you grief later.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	385
				386	<DT> PythonPPC
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	387	<DD> The interpreter. This is basically a routine to call out to the
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame^]	388	shared library. Do
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	389	<em>not</em> run it yet, this will possibly result in a garbled
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame^]	390	preferences file. See the section below on rebuilding .exp files if you
				391	get funny linker errors. <p>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	392
Jack Jansen	061ac50	1996-10-22 15:27:56 +0000	[diff] [blame]	393	<DT> PythonAppletPPC
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	394	<DD> The applet skeleton application. Very similar to
				395	<code>PythonPPC</code>, but it calls to a different entrypoint in the
				396	core library. The <code>mkapplet</code> script will copy this complete
				397	file, and add a <code>'PYC '</code> with the module to generate an
				398	applet. <p>
				399
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	400	</DL>
				401
Jack Jansen	061ac50	1996-10-22 15:27:56 +0000	[diff] [blame]	402	After creating the alias to <code>PythonCorePPC</code> you should move
				403	<code>PythonPPC</code> to the main Python folder. Next you remove any old
				404	<code>Python XXX Preferences</code> file from the <code>Preferences</code> folder
				405	(if you had python installed on your system before) and run the interpreter once
				406	to create the correct preferences file. You should also make an alias
				407	<code>PythonApplet</code> pointing to <code>PythonAppletPPC</code> in the main
				408	Python folder. (again: making an alias is preferrable to copying or moving the
				409	file, since this will cause the correct file to be used if you ever rebuild
				410	PythonAppletPPC). <p>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	411
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	412	Next, you have to build the extension modules in the
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	413	<code>PlugIns</code> folder. Open each project with <code>.ppc</code> in the
				414	name and build it. After all
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	415	the dynamically loaded modules are built you have to create a number
				416	of aliases: some modules live together in a single dynamic
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	417	library. Run the <code>MkPluginAliases.py</code> script from
				418	<code>Mac:scripts</code> to create the aliases. <p>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	419
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	420	Finally, you must build the standard applets:
				421	<code>EditPythonPrefs</code>, <code>mkapplet</code>, etc. This is
				422	easiest done with the <code>fullbuild</code> script from
				423	<code>Mac:scripts</code>. Answer <em>no</em> to all questions except
				424	when it asks whether to build the applets. <p>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	425
				426	<BLOCKQUOTE>
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	427	Actually, the <code>fullbuild</code> script can be used to build
				428	everything, but you need a fully-functional interpreter before you can
				429	use it (and one that isn't rebuilt in the process: you cannot rebuild
				430	a running program). You could copy the 68K interpreter to a different
				431	place and use that to run fullbuild, or use the standalone PPC python
				432	for this. I tend to keep a standalone interpreter in a safe place for
				433	this use only.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	434	</BLOCKQUOTE>
				435
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	436	You are all set now, and should read the release notes and
				437	<code>ReadMeOrSuffer</code> file from the <code>Mac</code> folder.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	438
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	439	<H2>Rebuilding <code>.exp</code> files for PPC and CFM68K</H2>
				440
				441	Occasionally it may be necessary to rebuild your PythonCore <code>.exp</code>
				442	file, a file that controls which symbols are exported by your PythonCore
				443	shared library. Rebuild it if you get unexpected undefined symbols when you
				444	are building a plugin module. <p>
				445
				446	Rebuilding the .exp file is done by first removing the file and removing the
				447	reference to it in the project (in the "config" section). Next, build PythonCore.
				448	This will create a new .exp file. Edit this file to remove the references to
				449	the symbols <code>__initialize</code>, <code>__terminate</code>, <code>setjmp</code>,
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame^]	450	<code>longjmp</code>, <code>main</code> and (for PPC) <code>__ptmf_null</code> or (for
				451	CFM68K) <code>__start</code> and <code>dummy_init_routine</code>.
				452	Next, add the .exp file to the project
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	453	again and rebuild PythonCore. <p>
				454
				455	This rather convoluted procedure is needed to ensure that plugin modules don't
				456	accidentally link with those entrypoints from PythonCore, which will not work because
				457	those routines have to be in the same code fragment as they are used from.
				458
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	459	<H2>Odds and ends</H2>
				460
				461	Some remarks that I could not fit in elsewhere:
				462
				463	<UL>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	464
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	465	<LI> It may be possible to use the <code>PythonCore</code> shared
				466	library to embed Python in another program, if your program can live
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame^]	467	with using GUSI for I/O. Use PythonCore in stead of your MSL C library
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	468	(or, at the very least, link it before the normal C library). Let me
				469	know whether this works.
				470
				471	<LI> It is possible to build PPC extension modules without building a
				472	complete Python. Take the binary distribution, add folders
				473	<code>Include</code>, <code>Mac:Include</code> and
				474	<code>Mac:mwerks</code> from the source distribution and you should be
				475	all set. A template for a dynamic module can be found in
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	476	<code>xx.ppc.µ</code> or <code>xx.CFM68K.µ</code>.
				477
				478	<LI> The Python shared library architecture is a variant of the architecture
				479	described as "application with shared libraries and dropins" in the MetroWerks
				480	"Targeting MacOS" documentation. The Python Application and applet-template use
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame^]	481	the <code>MSL AppRuntime.Lib</code> runtime library (with properly set CFM
				482	initialization and termination routines). PythonCore uses <code>MSL Runtime.Lib</code>,
				483	which is really intended for standalone programs but which we fool into working by
				484	providing a dummy main program.
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	485	It is linked statically into PythonCore (and exported to the applications and plugins)
				486	so we do not have to distribute yet another shared library. Plugin modules use
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame^]	487	<code>MSL ShlibRuntime.Lib</code> (not the dropin runtime: modules are never unloaded)
				488	and obtain the rest from PythonCore. PythonCore uses a
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	489	non-standard initialization entry point, <code>__initialize_with_resources</code>, to
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame^]	490	be able to obtain resources from the library file later on. Plugins can do the same
				491	(_tkinter does) or use the standard <code>__initialize</code> entry point.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	492
				493
Jack Jansen	6ad8d13	1997-01-15 16:53:37 +0000	[diff] [blame]	494	</UL>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	495	</BODY>
				496	</HTML>