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

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