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

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