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

blob: e1a229e5861faab29d380c3bb6125d0143cdbdcd [file] [log] [blame]

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