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

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