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

blob: 556eddd79546b14364b85ea3c22e7ae00dfea82d [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	c1218bc	2001-04-25 22:11:24 +0000	[diff] [blame^]	9	<B>Note</B>: This document is mostly still for Python 2.0, so
				10	it is not correct. See the <a href="http://www.cwi.nl/~jack/macpython.html">
				11	MacPython homepage</a> for an updated version, and if none is available
				12	complain bitterly to me and work on it should progress faster.
Jack Jansen	0eb5f2d	2001-02-17 22:04:13 +0000	[diff] [blame]	13	<p>
				14
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	15	This document explains how to build MacPython from source. This is
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	16	necessary if you want to make modifications to the Python core. Building
				17	Python is not something to be undertaken lightly, you need a reasonable
				18	working knowledge of the CodeWarrior development environment, a good net
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	19	connection and probably quite some time too. <p>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	20
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	21	The information density in this file is high, so you should probably
				22	print it and read it at your leasure. Most things are explained only
				23	once (and probably in the wrong place:-). <p>
				24
Jack Jansen	90cf491	2000-02-11 23:14:46 +0000	[diff] [blame]	25	<blockquote>
				26	First a warning: this information may become outdated if a new CodeWarrior is
				27	released after MacPython. The
				28	<a href="http://www.cwi.nl/~jack/macpython.html">MacPython homepage</a> will
				29	hopefully have updated instructions in that case.
				30	</blockquote>
				31
Jack Jansen	c256ece	1999-02-03 13:09:27 +0000	[diff] [blame]	32	I am very interested in feedback on this document, send your
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	33	comments to the <A
				34	HREF="http://www.python.org/sigs/pythonmac-sig/">Mac Python Special
				35	Interest Group</A>.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	36
				37	<H2>What you need.</H2>
				38
				39	The following things you definitely need:
				40
				41	<UL>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	42
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	43	<LI> You need a MacPython source distribution, of course. You can
Jack Jansen	9537586	1999-03-10 15:51:56 +0000	[diff] [blame]	44	obtain one from <A HREF="ftp://ftp.cwi.nl/pub/jack/python/mac">
				45	ftp://ftp.cwi.nl/pub/jack/python/mac</A> or from the companion webpage
				46	at <A HREF="http://www.cwi.nl/~jack/macpython.html">
				47	http://www.cwi.nl/~jack/macpython.html</A> (which has up-to-date links
				48	to the other packages needed too) and possibly also from the standard
				49	<A HREF="ftp://ftp.python.org/pub/python/mac">python.org ftp
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	50	site</A>. <BR>
Jack Jansen	c256ece	1999-02-03 13:09:27 +0000	[diff] [blame]	51
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	52	A better alternative is to check the sources straight out of the CVS
Jack Jansen	9537586	1999-03-10 15:51:56 +0000	[diff] [blame]	53	repository, see below. Most of the packages mentioned here are also
				54	available through CVS. Check the section on <a href="#cvs">CVS
				55	repository use</a> below.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	56
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	57	<LI> You need MetroWerks CodeWarrior. The current distribution has
Jack Jansen	c1218bc	2001-04-25 22:11:24 +0000	[diff] [blame^]	58	been built with CodeWarrior Pro 6.1. Ordering information is
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	59	available on the <A HREF="http://www.metrowerks.com/">MetroWerks
Jack Jansen	a2139fe	1998-02-25 15:40:35 +0000	[diff] [blame]	60	homepage</A>. Building Python with MPW or Think/Symantec C is
				61	probably impossible without major surgery.
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	62
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	63	<LI> You need GUSI version 2, the Grand Unified Socket Interface, by
				64	Matthias Neeracher. The original GUSI is obtainable from <A
Jack Jansen	5f884c0	2000-12-12 22:14:14 +0000	[diff] [blame]	65	HREF="ftp://gusi.sourceforge.net/pub/gusi/">
				66	ftp://gusi.sourceforge.net/pub/gusi/</A>. At
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	67	the moment Python is built with a slightly modified version of GUSI
				68	2.1.1, so it may be better to check the <A
				69	HREF="http://www.cwi.nl/~jack/macpython.html">MacPython homepage</A>
				70	for a GUSI that is most easily used for building Python.
				71	<br>
Jack Jansen	a598bc4	1999-02-10 23:08:24 +0000	[diff] [blame]	72
Jack Jansen	c1218bc	2001-04-25 22:11:24 +0000	[diff] [blame^]	73	If nothing is listed there (yet) you will have problems building a
				74	Carbon Python. Complaining loudly on the pythonmac-sig@python.org mailing
				75	list will make me work faster towards distributing Carbon-GUSI:-).
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	76	</UL>
				77
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	78	<A NAME="optional">The MacPython project files are configured to
				79	include a plethora of optional modules</A>, and these modules need a
Jack Jansen	a2139fe	1998-02-25 15:40:35 +0000	[diff] [blame]	80	number of extra packages. To use the project files as-is you have to
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	81	download these packages too. Python has all such modules as
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	82	dynamically loaded modules, so if you don't need a certain package it
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	83	suffices to just refrain from builing the extension module.
				84	Here are the locations for the various things
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	85	you need:
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	86
				87	<UL>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	88
Jack Jansen	8b41d53	2000-05-07 22:08:42 +0000	[diff] [blame]	89	<LI> Tcl and Tk are in a sad state on the Mac, the standard source distributions
				90	simply don't compile, so I have created a distribution especially for use
				91	with MacPython.
				92	See the section on <A HREF="#tcltk">building Tcl/Tk Python</A>
				93	below.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	94
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	95	<LI> Waste, a TextEdit replacement written by Marco Piovanelli, <A
				96	HREF="mailto:piovanel@kagi.com"><piovanel@kagi.com></A>. Python
Jack Jansen	c1218bc	2001-04-25 22:11:24 +0000	[diff] [blame^]	97	was built using version 2.0, which is included in the CodeWarrior
				98	package. You can also obtain it from <A
Jack Jansen	a2139fe	1998-02-25 15:40:35 +0000	[diff] [blame]	99	HREF="http://www.boingo.com/waste"><http://www.boingo.com/waste></A>
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	100	and various other places.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	101
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame]	102	<LI> Gdbm library for the Mac. Available from Jack's Mac software page at
				103	<A HREF="http://www.cwi.nl/~jack/macsoftware.html">
				104	http://www.cwi.nl/~jack/macsoftware.html</A> and <A HREF="ftp://ftp.cwi.nl/pub/jack/mac">
Jack Jansen	a598bc4	1999-02-10 23:08:24 +0000	[diff] [blame]	105	ftp://ftp.cwi.nl/pub/jack/mac</A>. Also in the MacPython cvs repository at
				106	<code>lib-src/gdbm</code>.
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame]	107
				108	<LI> JPEG library by the Independent JPEG Group. A version including
				109	Mac projects can be found at Jack's page mentioned above.
				110	The most recent JPEG library can always be obtained from <A
Jack Jansen	a598bc4	1999-02-10 23:08:24 +0000	[diff] [blame]	111	HREF="ftp://ftp.uu.net/graphics/jpeg/">ftp://ftp.uu.net/graphics/jpeg/</A>. Again,
				112	also in the MacPython cvs repository at <code>lib-src/jpeg</code>.
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	113
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame]	114	<LI> The netpbm/pbmplus, libtiff, zlib and png libraries. The netpbm distribution
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	115	(which includes libtiff) is generally available on Internet ftp
				116	servers. For Python pbmplus, an older incarnation of netpbm, is
				117	functionally identical to netpbm, since Python only uses the library
				118	and not the complete applications. A distribution with correct
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame]	119	projects and library source only is available from, you guessed it, Jack's Mac software
Jack Jansen	a598bc4	1999-02-10 23:08:24 +0000	[diff] [blame]	120	page mentioned above. And, guessed it again, in the MacPython cvs repository
				121	at <code>lib-src/netpbm</code>, etc. The only gotcha is that libtiff lives in
				122	<code>lib-src/netpbm/libtiff</code>, for historical reasons.
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	123
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	124	</UL>
				125
				126	<H2>Setting Up</H2>
				127
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	128	Now that you have collected everything you should start with building
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame]	129	the various parts. If you don't want to fix
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	130	access paths try to set things up as follows:
				131
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	132	<PRE>
				133	Top-level-folder:
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	134	GUSI2
Jack Jansen	c1218bc	2001-04-25 22:11:24 +0000	[diff] [blame^]	135	GUSI2Carbon
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	136	imglibs
Jack Jansen	de57030	1998-08-27 13:39:01 +0000	[diff] [blame]	137	jpeg
				138	netpbm
				139	libtiff
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame]	140	zlib
Jack Jansen	de57030	1998-08-27 13:39:01 +0000	[diff] [blame]	141	png
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame]	142	gdbm
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	143	Python
Jack Jansen	90cf491	2000-02-11 23:14:46 +0000	[diff] [blame]	144	Modules
				145	...
				146	Mac
				147	Modules
				148	Build
				149	...
Jack Jansen	3261719	1997-08-19 14:01:16 +0000	[diff] [blame]	150	Tcl/Tk Folder
				151	tcl8.0
				152	tk8.0
Jack Jansen	a2139fe	1998-02-25 15:40:35 +0000	[diff] [blame]	153	MoreFiles 1.4.3
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	154	</PRE>
				155
Jack Jansen	de57030	1998-08-27 13:39:01 +0000	[diff] [blame]	156	If your setup of the libraries is exactly the same as mine (which is
				157	not very likely, unless you happen to work from the same CVS
				158	repository) you can use the project <code>buildlibs.prj</code> in the
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	159	<code>:Mac:Build</code> folder to build all needed libraries in one
Jack Jansen	de57030	1998-08-27 13:39:01 +0000	[diff] [blame]	160	fell swoop, otherwise you will have to build the libraries one by
				161	one. <p>
				162
Jack Jansen	c1218bc	2001-04-25 22:11:24 +0000	[diff] [blame^]	163	First build GUSI, both the norla one and the Carbon variant.
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	164	<p>
Jack Jansen	9537586	1999-03-10 15:51:56 +0000	[diff] [blame]	165
Jack Jansen	16e99c0	1996-09-07 17:11:26 +0000	[diff] [blame]	166	Next, in
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	167	<code>libjpeg</code>, <code>pbmplus</code>,
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame]	168	<code>zlib</code>, <code>libpng</code>, <code>gdbm</code>,
Jack Jansen	a2139fe	1998-02-25 15:40:35 +0000	[diff] [blame]	169	and<code>libtiff</code> you build all projects. Usually the projects are in "mac"
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame]	170	subfolders, sometimes they are in the main folder. Tcl/tk is a special
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	171	case, see below.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	172
				173	<H2><A NAME="tcltk">Building Tcl/Tk</H2>
				174
Jack Jansen	8b41d53	2000-05-07 22:08:42 +0000	[diff] [blame]	175	The Tcl/Tk 8.3.0 source distribution does not work on the Mac. I have created
				176	an archive of the sources that I used to build _tkinter for MacPython,
				177	you can obtain this from <a
				178	href="ftp://ftp.cwi.nl/pub/jack/python/mac/tcltk830src-for-python.sit">
				179	ftp://ftp.cwi.nl/pub/jack/python/mac/tcltk830src-for-python.sit</a>. Only the
				180	libraries needed to build _tkinter for PPC have been fixed. <P>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	181
Jack Jansen	8b41d53	2000-05-07 22:08:42 +0000	[diff] [blame]	182	Note that if you use a different release of Tcl and Tk than the ones
Jack Jansen	f3dd5aa	1996-12-23 17:29:51 +0000	[diff] [blame]	183	I have used you may have to adapt the Python <code>tkresources.rsrc</code> file.
				184	This is easiest done by building <code>SimpleTk</code> and copying the TEXT, ICON
				185	and CRSR resources from it to <code>tkresources.rsrc</code>. This allows
				186	the <code>_tkinter</code> module to work without an installed Tk/Tcl on your
Jack Jansen	8b41d53	2000-05-07 22:08:42 +0000	[diff] [blame]	187	machine. <P>
				188
				189	Also note that the <code>_tkinter.ppc.slb</code> that is normally distributed
				190	in the <code>PlugIns</code> folder is the one from the Imaging extension,
				191	which has some extra features needed by PIL (and which features should not
				192	hinder normal operation).
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	193
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	194	</UL>
				195
Jack Jansen	f3dd5aa	1996-12-23 17:29:51 +0000	[diff] [blame]	196	Build first the Tcl library, then
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	197	SimpleTcl (test it by typing <code>ls -l</code> in the window you get)
				198	then the Tk library, then SimpleTk (which can again be tested with
				199	<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]	200	building Python.
				201
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	202	<H2>Building Waste</H2>
				203
				204	You do not need to build the Waste libraries, as Python includes the
Jack Jansen	a2139fe	1998-02-25 15:40:35 +0000	[diff] [blame]	205	source modules themselves.
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	206
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	207	<H2>The organization of the Python source tree</H2>
				208
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	209	Time for a short break, while we have a look at the organization of
				210	the Python source tree. At the top level, we find the following
				211	folders:
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	212
				213	<DL>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	214	<DT> Demo
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	215	<DD> Demo programs that are not Mac-specific. Some of these may not
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	216	work.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	217
				218	<DT> Extensions
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	219	<DD> Extensions to the interpreter that are not Mac-specific. Contains
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	220	the <code>img</code>, <code>Imaging</code> and <code>Numerical</code> extensions
				221	in this distribution.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	222
				223	<DT> Grammar
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	224	<DD> The Python grammar. Included for reference only, you cannot build
				225	the parser on a Mac.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	226
				227	<DT> Include
				228	<DD> Machine-independent header files.
				229
				230	<DT> Modules
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	231	<DD> Machine-independent optional modules. Not all of these will work
				232	on the Mac.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	233
				234	<DT> Objects
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	235	<DD> Machine-independent code for various object types. Most of these are
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	236	not really optional: the interpreter will not function without them.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	237
				238	<DT> Parser
				239	<DD> The Python parser (machine-independent).
				240
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	241	<DT> Python
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	242	<DD> The core interpreter. Most files are machine-independent, some
				243	are unix-specific and not used on the Mac.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	244
				245	<DT> Tools
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	246	<DD> Tools for python developers. Contains <code>modulator</code> which
				247	builds skeleton C extension modules, <code>bgen</code> which generates
				248	complete interface modules from information in C header files and
				249	<code>freeze</code> which is used to turn Python scripts into real
				250	applications (used by MacFreeze and BuildApplication) There are some
				251	readme files, but more documentation is sorely needed.
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	252
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	253	</DL>
				254
				255	All the mac-specific stuff lives in the <code>Mac</code> folder:
				256	<DL>
Jack Jansen	c256ece	1999-02-03 13:09:27 +0000	[diff] [blame]	257	<DT> Build
				258	<DD> This is where the project files live and where you build the
				259	libraries, shared libraries, executables and plugin modules. All the
				260	resulting binaries, except for intermedeate results, are deposited in
Jack Jansen	a598bc4	1999-02-10 23:08:24 +0000	[diff] [blame]	261	the toplevel folder or the Mac:PlugIns folder (for plugin modules).
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	262
				263	<DT> Compat
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	264	<DD> Unix-compatability routines. Most of these are not used anymore,
				265	since GUSI provides a rather complete emulation, but you may need
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	266	these if you are trying to build a non-GUSI python.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	267
				268	<DT> Demo
				269	<DD> Mac-specific demo programs, some of them annotated.
				270
				271	<DT> Include
				272	<DD> Mac-specific but compiler-independent include files.
				273
				274	<DT> Lib
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	275	<DD> Mac-specific standard modules. The <code>toolbox</code> folder
				276	contains modules specifically needed with various MacOS toolbox
				277	interface modules.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	278
				279	<DT> Modules
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	280	<DD> Mac-specific builtin modules. Theoretically these are all
				281	optional, but some are rather essential (like
				282	<code>macmodule</code>). A lot of these modules are generated with
				283	<code>bgen</code>, in which case the bgen input files are included so
				284	you can attempt to regenerate them or extend them.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	285
				286	<DT> MPW
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	287	<DD> MPW-specific files. These have not been used or kept up-to-date
				288	for a long time, so use at your own risk.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	289
				290	<DT> mwerks
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	291	<DD> Mwerks-specific sources and headers. Contains glue code for
				292	Pythons shared-library architecture, a replacement for
				293	<code>malloc</code> and a directory with various projects for building
				294	variations on the Python interpreter. The <code>mwerks_*.h</code>
				295	files here are the option-setting files for the various interpreters
				296	and such, comparable to the unix command-line <code>-D</code> options
				297	to the compiler. Each project uses the correct option file as its
				298	"prefix file" in the "C/C++ language" settings. Disabling optional
				299	modules (for the 68K interpreter), building non-GUSI interpreters and
				300	various other things are accomplished by modifying these files (and
				301	possibly changing the list of files included in the project window, of
				302	course).
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	303
Jack Jansen	c256ece	1999-02-03 13:09:27 +0000	[diff] [blame]	304	<DT> PlugIns
Jack Jansen	c1218bc	2001-04-25 22:11:24 +0000	[diff] [blame^]	305	<DD> This is where the Classic and Carbon dynamically-loaded plugin modules live.
Jack Jansen	c256ece	1999-02-03 13:09:27 +0000	[diff] [blame]	306
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	307	<DT> Python
				308	<DD> Mac-specific parts of the core interpreter.
				309
				310	<DT> Resources
				311	<DD> Resource files needed to build the interpreter.
				312
				313	<DT> Scripts
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	314	<DD> A collection of various mac-specific Python scripts. Some are
				315	essential, some are useful but few are documented, so you will have to
				316	use your imagination to work them out.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	317
Jack Jansen	c256ece	1999-02-03 13:09:27 +0000	[diff] [blame]	318	<DT> Tools
				319	<DD> A collection of tools, usually bigger than those in the scripts
				320	folder. The important ones here are the IDE and macfreeze. The IDE is built
				321	with the buildIDE.py script, which puts the resulting applet in the toplevel
				322	folder. Macfreeze is usually invoked through the BuildApplication script,
				323	but for more control over the freezing process you can run the main script here.
				324
				325
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	326	<DT> Unsupported
				327	<DD> Modules that are not supported any longer but may still work with a little effort.
				328	</DL>
				329
				330	<H2>Building the 68K interpreter</H2>
				331
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	332	68K Python is no longer supported, and the projects are not included in the
Jack Jansen	c1218bc	2001-04-25 22:11:24 +0000	[diff] [blame^]	333	source distribution anymore. If you really want to build Python for the 68K
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	334	your best bet is to check the sources out of the CVS repository. The latest
				335	projects (in :Mac:build:) that support 68K development are tagged as such,
				336	and are dated around August 2000. If you plan on doing this announce it on
				337	the SIG, please. <p>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	338
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	339	<H2>Building the PPC interpreter</H2>
Jack Jansen	c1218bc	2001-04-25 22:11:24 +0000	[diff] [blame^]	340	<em>This is different under 2.1. You are best off using the fullbuild.py
				341	script. </em><p>
Jack Jansen	c256ece	1999-02-03 13:09:27 +0000	[diff] [blame]	342	First you optionally build the external libraries with buildlibs.prj. Next,
				343	the projects for
				344	interpreter, core library and applet skeleton are all linked together, so
Jack Jansen	c1218bc	2001-04-25 22:11:24 +0000	[diff] [blame^]	345	building the PythonInterpreter target in <code>PythonEngine.prj</code>
Jack Jansen	3b80526	1999-02-14 23:12:06 +0000	[diff] [blame]	346	will result in everything being built. The
Jack Jansen	3412c5d	1997-08-27 14:08:22 +0000	[diff] [blame]	347	resulting applications and fat shared library are deposited in the main
Jack Jansen	c256ece	1999-02-03 13:09:27 +0000	[diff] [blame]	348	Python folder. Finally, you build all the plugins with the plugins.prj project.
				349
				350	For completeness sake here is a breakdown of the projects:
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	351
				352	<DL>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	353
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	354	<DT> PythonCore (with subproject PythonCorePPC)
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	355	<DD> The shared library that contains the bulk of the interpreter and
				356	its resources. It is a good idea to immedeately put an alias to this
				357	shared library in the <code>Extensions</code> folder of your system
				358	folder. Do exactly that: put an <em>alias</em> there, copying or
Jack Jansen	3412c5d	1997-08-27 14:08:22 +0000	[diff] [blame]	359	moving the file will cause you grief later if you rebuild the library and
Jack Jansen	c256ece	1999-02-03 13:09:27 +0000	[diff] [blame]	360	forget to copy it to the extensions folder again. The InstallPython applet
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	361	will also do this, along with creating the plugin aliases. <br>
				362	Note that the subproject looks a bit silly nowadays (with no more CFM68K
				363	support) but you will have to live with that for this release.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	364
Jack Jansen	3b80526	1999-02-14 23:12:06 +0000	[diff] [blame]	365	<DT> PythonInterpeter
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	366	<DD> The interpreter. This is basically a routine to call out to the
Jack Jansen	3b80526	1999-02-14 23:12:06 +0000	[diff] [blame]	367	shared library. Unlike in previous releases the same program is used for
				368	creating applets (for which formerly PythonApplet was used). <p>
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	369
Jack Jansen	c256ece	1999-02-03 13:09:27 +0000	[diff] [blame]	370	<DT> Plugin projects
Jack Jansen	a598bc4	1999-02-10 23:08:24 +0000	[diff] [blame]	371	<DD> Each plugin module has a separate project. The <code>Plugins.prj</code>
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	372	project tries to build them all, but is known to be flakey. See <code>fullbuild</code>
				373	below for a better way to build everything.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	374	</DL>
				375
Jack Jansen	3412c5d	1997-08-27 14:08:22 +0000	[diff] [blame]	376	After creating the alias to <code>PythonCore</code> you remove any old
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	377	<code>Python 2.0b1 Preferences</code> file from the <code>Preferences</code> folder
Jack Jansen	061ac50	1996-10-22 15:27:56 +0000	[diff] [blame]	378	(if you had python installed on your system before) and run the interpreter once
Jack Jansen	3412c5d	1997-08-27 14:08:22 +0000	[diff] [blame]	379	to create the correct preferences file. <p>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	380
Jack Jansen	c256ece	1999-02-03 13:09:27 +0000	[diff] [blame]	381	Next, you have to build the extension modules.
				382	The <code>PlugIns.ppc</code> project has all the
Jack Jansen	a598bc4	1999-02-10 23:08:24 +0000	[diff] [blame]	383	other projects as subprojects and builds everything (but see the gotcha above).
				384	<p>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	385
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	386	Finally, you must build the standard applets:
Jack Jansen	3412c5d	1997-08-27 14:08:22 +0000	[diff] [blame]	387	<code>EditPythonPrefs</code>, <code>BuildApplet</code>, etc. This is
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	388	easiest done with the <code>fullbuild</code> script from
Jack Jansen	3412c5d	1997-08-27 14:08:22 +0000	[diff] [blame]	389	<code>Mac:scripts</code>. <p>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	390
				391	<BLOCKQUOTE>
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	392	Actually, the <code>fullbuild</code> script can be used to build
				393	everything, but you need a fully-functional interpreter before you can
				394	use it (and one that isn't rebuilt in the process: you cannot rebuild
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	395	a running program). You could copy the interpreter to a different
				396	place and use that to run fullbuild. The <code>PythonStandSmall.prj</code>
				397	project builds an interpreter that is suited to this, and it can also come
				398	in handy if you need to debug things (which is easier in a static program). <p>
Jack Jansen	e66b8c8	1997-05-29 14:57:07 +0000	[diff] [blame]	399
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	400	</BLOCKQUOTE>
				401
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	402	You are all set now, and should read the release notes and
Jack Jansen	3412c5d	1997-08-27 14:08:22 +0000	[diff] [blame]	403	<code>ReadMe</code> file from the <code>Mac</code> folder.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	404
Jack Jansen	c1218bc	2001-04-25 22:11:24 +0000	[diff] [blame^]	405	<H2>Rebuilding <code>.exp</code> files</H2>
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	406
				407	Occasionally it may be necessary to rebuild your PythonCore <code>.exp</code>
				408	file, a file that controls which symbols are exported by your PythonCore
				409	shared library. Rebuild it if you get unexpected undefined symbols when you
				410	are building a plugin module. <p>
				411
				412	Rebuilding the .exp file is done by first removing the file and removing the
				413	reference to it in the project (in the "config" section). Next, build PythonCore.
				414	This will create a new .exp file. Edit this file to remove the references to
				415	the symbols <code>__initialize</code>, <code>__terminate</code>, <code>setjmp</code>,
Jack Jansen	2afc2c7	1999-09-30 19:48:49 +0000	[diff] [blame]	416	<code>longjmp</code>, <code>vec_longjmp</code>, <code>main</code> and (for PPC) <code>__ptmf_null</code> or (for
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame]	417	CFM68K) <code>__start</code> and <code>dummy_init_routine</code>.
				418	Next, add the .exp file to the project
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	419	again and rebuild PythonCore. <p>
				420
				421	This rather convoluted procedure is needed to ensure that plugin modules don't
				422	accidentally link with those entrypoints from PythonCore, which will not work because
				423	those routines have to be in the same code fragment as they are used from.
				424
Jack Jansen	9537586	1999-03-10 15:51:56 +0000	[diff] [blame]	425	<H2><a name="cvs">Using the CVS source archive</a></H2>
Jack Jansen	c256ece	1999-02-03 13:09:27 +0000	[diff] [blame]	426
Jack Jansen	c1218bc	2001-04-25 22:11:24 +0000	[diff] [blame^]	427	<em>Please check the MacPython homepage to see whether this information is
				428	still current: MacPython should move to sourceforge shortly. </em><p>
				429
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	430	It is possible (and probably best) to access the Python sources through remote CVS. The
Jack Jansen	65f685b	1999-04-12 09:25:23 +0000	[diff] [blame]	431	advantage of this is that you get the very latest sources, so any bug
				432	fixed or new features will be immedeately available. This is also the
				433	disadvantage, of course: as this is the same tree as is used for
				434	development it may sometimes be a little less stable. <p>
Jack Jansen	c256ece	1999-02-03 13:09:27 +0000	[diff] [blame]	435
				436	The CVS client of choice is Alexandre Parenteau's MacCVS. It can be
Jack Jansen	65f685b	1999-04-12 09:25:23 +0000	[diff] [blame]	437	obtained through the <a href="http://www.wincvs.org">WinCVS
				438	homepage</a>. MacCVS uses Internet Config to set file types correctly
				439	based on the filename extension. In the maccvs preferences you should
				440	also set (in the "binary files" section) "use mac encoding:
				441	applesingle" and (in the "text files" section) "use ISO latin 1
Jack Jansen	c256ece	1999-02-03 13:09:27 +0000	[diff] [blame]	442	conversion". <p>
				443
Jack Jansen	8b41d53	2000-05-07 22:08:42 +0000	[diff] [blame]	444	It is also a good idea to disable Quicktime Exchange in the Quicktime
				445	control panel. Quicktime Exchange will magically map some extensions to
				446	filetypes, and this can seriously hinder you if, for instance, <code>.bmp</code>
				447	is not a Windows bitmap file. <p>
				448
Jack Jansen	9537586	1999-03-10 15:51:56 +0000	[diff] [blame]	449	The machine-independent Python sources are checked out from the main
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	450	Python CVS archive on sourceforge.net, see the <a
Jack Jansen	65f685b	1999-04-12 09:25:23 +0000	[diff] [blame]	451	href="http://www.python.org/download/cvs.html">Source access via
				452	CVS</a> page for details. When you check the sources out you will get
Jack Jansen	9537586	1999-03-10 15:51:56 +0000	[diff] [blame]	453	something like <code>Python:dist:src</code>, and under that the
				454	<code>Modules</code>, <code>Lib</code>, etc hierarchy. The
				455	<code>src</code> folder should be renamed to <code>Python</code>, and
				456	is what this document refers to as the "toplevel Python folder". <P>
Jack Jansen	c256ece	1999-02-03 13:09:27 +0000	[diff] [blame]	457
Jack Jansen	90cf491	2000-02-11 23:14:46 +0000	[diff] [blame]	458	Next, <em>in a separate folder</em>, you check out the
				459	mac-specific sources. You then move the <code>Mac</code> folder from this
				460	checkout (the only folder with anything in it) to the Python source folder.
				461	Note that the checking out in a separate folder and moving is necessary,
				462	due to the way cvs works.
				463
				464	The CVS path to use for the mac stuff can be found
Jack Jansen	9537586	1999-03-10 15:51:56 +0000	[diff] [blame]	465	at the <a href="http://www.cwi.nl/~jack/macpython.html">MacPython
				466	homepage</a>. Finally, you check out the external libraries needed in
Jack Jansen	90cf491	2000-02-11 23:14:46 +0000	[diff] [blame]	467	the parent of the toplevel Python folder. The CVS path for these libraries is
Jack Jansen	9537586	1999-03-10 15:51:56 +0000	[diff] [blame]	468	also mentioned at the MacPython homepage. <p>
Jack Jansen	c256ece	1999-02-03 13:09:27 +0000	[diff] [blame]	469
Jack Jansen	c256ece	1999-02-03 13:09:27 +0000	[diff] [blame]	470
Jack Jansen	90cf491	2000-02-11 23:14:46 +0000	[diff] [blame]	471	You should end up with a folder structure as described at the top of this
				472	document. <p>
				473
Jack Jansen	dae108c	2000-02-11 23:17:14 +0000	[diff] [blame]	474	Note that while the Mac folder is now a subfolder of your toplevel Python
				475	folder this does not mean that they "act as one" as far as CVS is concerned.
				476	To update all your sources you have to do a "cvs update" in the toplevel
				477	Python folder and another one in the Mac folder. This is again a cvs problem:
				478	it cannot deal with subpackages coming from different repositories. <p>
				479
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	480	<H2>Odds and ends</H2>
				481
				482	Some remarks that I could not fit in elsewhere:
				483
				484	<UL>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	485
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	486	<LI> It may be possible to use the <code>PythonCore</code> shared
				487	library to embed Python in another program, if your program can live
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame]	488	with using GUSI for I/O. Use PythonCore in stead of your MSL C library
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	489	(or, at the very least, link it before the normal C library).
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	490
				491	<LI> It is possible to build PPC extension modules without building a
Jack Jansen	c256ece	1999-02-03 13:09:27 +0000	[diff] [blame]	492	complete Python. The binary distribution installer can optionally install
Jack Jansen	8a6cdcc	2000-09-10 12:02:28 +0000	[diff] [blame]	493	all the needed folders (the develop option). A template for a dynamic module can be found in
Jack Jansen	3412c5d	1997-08-27 14:08:22 +0000	[diff] [blame]	494	<code>xx.prj</code>.
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	495
				496	<LI> The Python shared library architecture is a variant of the architecture
				497	described as "application with shared libraries and dropins" in the MetroWerks
				498	"Targeting MacOS" documentation. The Python Application and applet-template use
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame]	499	the <code>MSL AppRuntime.Lib</code> runtime library (with properly set CFM
				500	initialization and termination routines). PythonCore uses <code>MSL Runtime.Lib</code>,
				501	which is really intended for standalone programs but which we fool into working by
				502	providing a dummy main program.
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	503	It is linked statically into PythonCore (and exported to the applications and plugins)
				504	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]	505	<code>MSL ShlibRuntime.Lib</code> (not the dropin runtime: modules are never unloaded)
				506	and obtain the rest from PythonCore. PythonCore uses a
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	507	non-standard initialization entry point, <code>__initialize_with_resources</code>, to
Jack Jansen	1473af7	1997-05-07 15:43:38 +0000	[diff] [blame]	508	be able to obtain resources from the library file later on. Plugins can do the same
				509	(_tkinter does) or use the standard <code>__initialize</code> entry point.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	510
				511
Jack Jansen	6ad8d13	1997-01-15 16:53:37 +0000	[diff] [blame]	512	</UL>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	513	</BODY>
				514	</HTML>