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

blob: 406f478e4a5aa023cf1edee786f46658807ce3e1 [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
				11	currently also probably the easiest way to build PPC extension
				12	modules. Building Python is not something to be undertaken lightly,
				13	the process is not very streamlined so you need a reasonable working
				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
				21	I am very interested in feedback on this document, contact me at <A
				22	HREF="mailto:jack@cwi.nl"><jack@cwi.nl></A> or send your
				23	comments to the <A
				24	HREF="http://www.python.org/sigs/pythonmac-sig/">Mac Python Special
				25	Interest Group</A>.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	26
				27	<H2>What you need.</H2>
				28
				29	The following things you definitely need:
				30
				31	<UL>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	32
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	33	<LI> You need a MacPython source distribution, of course. You can
				34	obtain one from <A
				35	HREF="ftp://ftp.cwi.nl/pub/jack/python/mac">ftp://ftp.cwi.nl/pub/jack/python/mac</A>,
				36	and possibly also from the standard <A
				37	HREF="ftp://ftp.python.org/pub/python/mac">python.org ftp
				38	site</A>. Everything you need is also included in the standard Python
				39	source distribution, but the organization is different. Look in
				40	directory <code>Mac/mwerks/projects</code> for the project files and
				41	related stuff.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	42
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	43	<LI> You need MetroWerks CodeWarrior. The current distribution has
				44	been built with version 9 of CodeWarrior. Ordering information is
				45	available on the <A HREF="http://www.metrowerks.com/">MetroWerks
				46	homepage</A>. You might still be able to build Python with MPW or
				47	Think/Symantec C but you are basically on your own.
				48
				49	<LI> You need GUSI, the Grand Unified Socket Interface, by Matthias
Jack Jansen	16e99c0	1996-09-07 17:11:26 +0000	[diff] [blame^]	50	Neeracher. The current distribution has been built with a modified version of
				51	CWGUSI 1.7.2. CWGUSI is
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	52	obtainable from <A
				53	HREF="ftp://ftp.switch.ch/software/mac/src/mw_c">ftp://ftp.switch.ch/software/mac/src/mw_c</A>.
				54	It is possible to build a non-GUSI Python, see below.
				55
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	56	</UL>
				57
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	58	<A NAME="optional">The MacPython project files are configured to
				59	include a plethora of optional modules</A>, and these modules need a
				60	number extra packages. To use the project files as-is you have to
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	61	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]	62	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]	63	suffices to just refrain from builing the extension module. For static 68K
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	64	Python things are a bit more complicated: you have to edit the
				65	interpreter project file to remove the reference to the module (and
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	66	the libraries it uses), and edit the <code>Mac:mwerks:mwerks_nonshared_config.h</code>
				67	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]	68	you need:
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	69
				70	<UL>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	71
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	72	<LI> Tcl and Tk can be obtained from <A
				73	HREF="ftp://ftp.smli.com/pub/tcl/mac/">ftp://ftp.smli.com/pub/tcl/mac/</A>.
				74	The current distributions, Tcl 7.5p1 and Tk 4.1p1 need a bit of work,
				75	see the section on <A HREF="#tcltk">building Tcl/Tk Python</A>
				76	below. Get the "full source" distribution, which includes MoreFiles.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	77
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	78	<LI> Waste, a TextEdit replacement written by Marco Piovanelli, <A
				79	HREF="mailto:piovanel@kagi.com"><piovanel@kagi.com></A>. Python
				80	was built using version 1.2, which you can obtain from <A
				81	HREF="ftp://rhino.harvard.edu/pub/dan/WASTE"><ftp://rhino.harvard.edu/pub/dan/WASTE></A>
				82	and various other places.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	83
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	84	<LI> JPEG library by the Independent JPEG Group. Python is still built
				85	using an archaic version of the library, version 4. It can be obtained
				86	from the <A HREF="ftp://ftp.cwi.nl/pub/jack/python/mac">
				87	ftp://ftp.cwi.nl/pub/jack/python/mac</A> directory, complete with CW8
				88	projects. If someone manages to build Python with the version 6
				89	library I would be grateful if they sent me the changes needed. The
				90	most recent JPEG library can always be obtained from <A
				91	HREF="ftp://ftp.uu.net/graphics/jpeg/">ftp://ftp.uu.net/graphics/jpeg/</A>.
				92
				93	<LI> The netpbm/pbmplus and libtiff libraries. The netpbm distribution
				94	(which includes libtiff) is generally available on Internet ftp
				95	servers. For Python pbmplus, an older incarnation of netpbm, is
				96	functionally identical to netpbm, since Python only uses the library
				97	and not the complete applications. A distribution with correct
				98	projects and library source only is available from, you guessed it, <A
				99	HREF="ftp://ftp.cwi.nl/pub/jack/python/mac">ftp://ftp.cwi.nl/pub/jack/python/mac</A>.
				100
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	101	</UL>
				102
				103	<H2>Setting Up</H2>
				104
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	105	Now that you have collected everything you should start with building
				106	the various parts. Everything is independent, with the single
				107	exception that Tcl and Tk depend on CWGUSI. If you don't want to fix
				108	access paths try to set things up as follows:
				109
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	110	<PRE>
				111	Top-level-folder:
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	112	CWGUSI
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	113	imglibs
				114	libjpeg
				115	pbmplus
				116	libtiff
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	117	MoreFiles 1.4.2 (not needed by Python, only by tcl/tk)
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	118	Python
				119	Tcl 7.5
				120	Tk 4.1
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	121	Waste 1.2 distribution (if you want waste)
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	122	</PRE>
				123
Jack Jansen	16e99c0	1996-09-07 17:11:26 +0000	[diff] [blame^]	124	First build GUSI. Move the files from the "CWGUSI-mods" to the right
				125	place in the CWGUSI distribution folder, and build the
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	126	projects <code>GUSI.68K.µ</code>, <code>GUSI.CFM68K.µ</code>
Jack Jansen	16e99c0	1996-09-07 17:11:26 +0000	[diff] [blame^]	127	and <code>GUSI.PPC.µ</code>. If you have a CWGUSI version more recent than
				128	1.7.2 it could be that the fixes are already included, check it. Alternatively,
				129	you can forget about the fixes and remove the one reference to GUSILoadPreferences
				130	in the Python sources. This will disable the "default file creator/type" and
				131	"Delay Sioux window" preferences in Python.
				132
				133	Next, in
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	134	<code>MoreFiles</code>, <code>libjpeg</code>, <code>pbmplus</code>
				135	and<code>libtiff</code> you build all projects. Tcl/tk is a special
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	136	case, see below. Of course, if you are only interested in one of
				137	static 68K, CFM68K or PPC you can skip building the other libraries.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	138
				139	<H2><A NAME="tcltk">Building Tcl/Tk</H2>
				140
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	141	You need to make a minor organizational change to the Tcl/Tk
				142	distribution. The current instructions are for the
				143	<code>tcl7.5.1</code> and <code>tk4.1.1</code> distribution:
				144
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	145	<UL>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	146
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	147	<LI> Rename the <code>compat</code> folders to <code>(compat)</code>
				148	in both the Tcl and Tk folders.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	149
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	150	<LI> In the Tcl folder, move <code>strncasecmp.c</code> and
				151	<code>tclErrno.h</code> from <code>(compat)</code> to the main Tcl
				152	folder.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	153
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	154	<LI> Fix <code>dnr.c</code> as provided by MetroWerks by inserting
				155	<pre><code> #pragma ANSI_strict off </code></pre> at the
				156	beginning. The tcl library is built with strict ANSI on, and this file
				157	uses C++ style comments.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	158
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	159	<LI> If you want to build <code>SimpleTcl</code> and
				160	<code>SimpleTk</code> you will probably have to remove the references
				161	to <code>libmoto</code> from the project.
				162
				163	<LI> You are <EM>strongly</EM> advised to add a line
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	164	<pre><code>
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	165	#define USE_TCLALLOC 1
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	166	</code></pre>
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	167	somewhere at the beginning of <code>MW_TclHeader.pch</code>.
				168	As distributed, tcl and tk assume that malloc calls always succeed and
				169	use the resulting pointer without checking for <code>NULL</code>
				170	values. Needless to say, this wreaks havoc on a Macintosh.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	171
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	172	<LI> If you want to build for CFM68K you have to modify <code>TclMacNotify.c</code>
				173	because there is an error in the Apple Universal headers (sic!). Read the
				174	comments at the beginning of <code>Mac:Python:macglue.c</code> and copy the
				175	code to <code>TclMacNotify.c</code>. If you get linker errors on <code>GetEvQHdr</code>
				176	you have not done this correctly.
				177
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	178	</UL>
				179
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	180	Build first the MoreFiles library, then the Tcl library, then
				181	SimpleTcl (test it by typing <code>ls -l</code> in the window you get)
				182	then the Tk library, then SimpleTk (which can again be tested with
				183	<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]	184	building Python.
				185
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	186	<H2>Building Waste</H2>
				187
				188	You do not need to build the Waste libraries, as Python includes the
				189	source modules themselves. You have to make one modification,
				190	though. In file <code>ICCFMGlue.c</code> in folder <code>Minimal IC
				191	APIs</code>, add the following lines:
				192
				193	<blockquote><pre><code>
				194	#include <Gestalt.h>
				195	#include <Errors.h>
				196	</code></pre></blockquote>
				197
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	198	<H2>The organization of the Python source tree</H2>
				199
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	200	Time for a short break, while we have a look at the organization of
				201	the Python source tree. At the top level, we find the following
				202	folders:
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	203
				204	<DL>
				205	<DT> build.mac68k.stand
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	206	<DD> This is where you will build static 68K interpreters.
				207
				208	<DT> build.mac68k.shared
				209	<DD> This is where you build the CFM68K shared library, interpreter
				210	and applet framework.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	211
				212	<DT> build.macppc.shared
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	213	<DD> This is where you build the PPC shared library, interpreter and
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	214	applet framework. You can also build the fat applet framework here.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	215
				216	<DT> build.macppc.stand
				217	<DD> This is where you build a nonshared PPC interpreter (optional).
				218
				219	<DT> Demo
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	220	<DD> Demo programs that are not Mac-specific. Some of these may not
				221	work, the file <code>README-Mac</code> has some details.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	222
				223	<DT> Extensions
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	224	<DD> Extensions to the interpreter that are not Mac-specific. Contains
				225	only the <code>img</code> extension in this distribution. Extensions
				226	are <em>not</em> built here, as they are on Unix, but incorporated in
				227	the core interpreter or built as plugin modules.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	228
				229	<DT> Grammar
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	230	<DD> The Python grammar. Included for reference only, you cannot build
				231	the parser on a Mac.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	232
				233	<DT> Include
				234	<DD> Machine-independent header files.
				235
				236	<DT> Modules
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	237	<DD> Machine-independent optional modules. Not all of these will work
				238	on the Mac.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	239
				240	<DT> Objects
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	241	<DD> Machine-independent code for various objects. Most of these are
				242	not really optional: the interpreter will not function without them.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	243
				244	<DT> Parser
				245	<DD> The Python parser (machine-independent).
				246
				247	<DT> PlugIns
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	248	<DD> This is where you build the PPC and CFM68K dynamically-loaded plugin modules.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	249
				250	<DT> Python
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	251	<DD> The core interpreter. Most files are machine-independent, some
				252	are unix-specific and not used on the Mac.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	253
				254	<DT> Tools
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	255	<DD> Tools for python developers. Contains <code>modulator</code>
				256	which builds skeleton C extension modules and <code>bgen</code> which
				257	generates complete interface modules from information in C header
				258	files. There are some readme files, but more documentation is sorely
				259	needed.
				260
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	261	</DL>
				262
				263	All the mac-specific stuff lives in the <code>Mac</code> folder:
				264	<DL>
				265
				266	<DT> Compat
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	267	<DD> Unix-compatability routines. Some of these are not used anymore,
				268	since CWGUSI provides a rather complete emulation, but you may need
				269	these if you are trying to build a non-GUSI python.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	270
				271	<DT> Demo
				272	<DD> Mac-specific demo programs, some of them annotated.
				273
				274	<DT> Include
				275	<DD> Mac-specific but compiler-independent include files.
				276
				277	<DT> Lib
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	278	<DD> Mac-specific standard modules. The <code>toolbox</code> folder
				279	contains modules specifically needed with various MacOS toolbox
				280	interface modules.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	281
				282	<DT> Modules
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	283	<DD> Mac-specific builtin modules. Theoretically these are all
				284	optional, but some are rather essential (like
				285	<code>macmodule</code>). A lot of these modules are generated with
				286	<code>bgen</code>, in which case the bgen input files are included so
				287	you can attempt to regenerate them or extend them.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	288
				289	<DT> MPW
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	290	<DD> MPW-specific files. These have not been used or kept up-to-date
				291	for a long time, so use at your own risk.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	292
				293	<DT> mwerks
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	294	<DD> Mwerks-specific sources and headers. Contains glue code for
				295	Pythons shared-library architecture, a replacement for
				296	<code>malloc</code> and a directory with various projects for building
				297	variations on the Python interpreter. The <code>mwerks_*.h</code>
				298	files here are the option-setting files for the various interpreters
				299	and such, comparable to the unix command-line <code>-D</code> options
				300	to the compiler. Each project uses the correct option file as its
				301	"prefix file" in the "C/C++ language" settings. Disabling optional
				302	modules (for the 68K interpreter), building non-GUSI interpreters and
				303	various other things are accomplished by modifying these files (and
				304	possibly changing the list of files included in the project window, of
				305	course).
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	306
				307	<DT> Python
				308	<DD> Mac-specific parts of the core interpreter.
				309
				310	<DT> Resources
				311	<DD> Resource files needed to build the interpreter.
				312
				313	<DT> Scripts
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	314	<DD> A collection of various mac-specific Python scripts. Some are
				315	essential, some are useful but few are documented, so you will have to
				316	use your imagination to work them out.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	317
				318	<DT> Unsupported
				319	<DD> Modules that are not supported any longer but may still work with a little effort.
				320	</DL>
				321
				322	<H2>Building the 68K interpreter</H2>
				323
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	324	If you have all the optional libraries mentioned <A
				325	HREF="#optional">above</A> loaded buildin Python for 68K macs is a
				326	breeze: open the project in the folder <code>build.mac68k.stand</code>
				327	and build it. Do <em>not</em> run it yet, this will possibly result
				328	in a garbled preferences file. <p>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	329
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	330	First remove the <code>Python preferences</code> file from your
				331	preference folder, only if you had an older version of Python
				332	installed. (this is also what you do if you did not heed the last
				333	sentence of the preceeding paragraph). Next, move the interpreter to
				334	the main Python folder (up one level) and run it there. This will
				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
				339	<code>ReadMeOrSuffer</code> in the <code>Mac</code> folder.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	340
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	341	<H2>Building the CFM68K interpreter</H2>
				342
				343	Building the CFM68K interpreter is as almost exactly the same as building
				344	the PPC interpreter, with the exception that you should read "CFM68K"
				345	for "PPC" every time. Continue reading with the next section.
				346
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	347	<H2>Building the PPC interpreter</H2>
				348
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	349	First you build the interpreter, core library and applet skeleton in
				350	folder <code>build.macppc.stand</code>. The order to build things is
				351	the following:
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	352
				353	<DL>
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	354	<DT> MWRuntimeStaticLib
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	355	<DD> A modified version of the MetroWerks runtime library that is
				356	suitable for Pythons' shared library architecture. The sources all
				357	come from the MW distribution.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	358
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	359	<DT> PythonCorePPC
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	360	<DD> The shared library that contains the bulk of the interpreter and
				361	its resources. It is a good idea to immedeately put an alias to this
				362	shared library in the <code>Extensions</code> folder of your system
				363	folder. Do exactly that: put an <em>alias</em> there, copying or
				364	moving the file will cause you grief later.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	365
				366	<DT> PythonPPC
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	367	<DD> The interpreter. This is basically a routine to call out to the
				368	shared library. Because of the organization of GUSI it also contains
				369	the Gusi settings resource (together with a ResEdit template, so you
				370	can change the gusi settings should you feel like doing so). Do
				371	<em>not</em> run it yet, this will possibly result in a garbled
				372	preferences file. <p>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	373
				374	<DT> PythonApplet
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	375	<DD> The applet skeleton application. Very similar to
				376	<code>PythonPPC</code>, but it calls to a different entrypoint in the
				377	core library. The <code>mkapplet</code> script will copy this complete
				378	file, and add a <code>'PYC '</code> with the module to generate an
				379	applet. <p>
				380
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	381	</DL>
				382
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	383	After creating the alias to <code>PythonCore</code> you should move
				384	<code>PythonPPC</code> to the main Python folder. Next you remove any
				385	old <code>Python Preferences</code> file from the
				386	<code>Preferences</code> folder (if you had python installed on your
				387	system before) and run the interpreter once to create the correct
				388	preferences file. You should also make an alias to
				389	<code>PythonApplet</code> in the main Python folder. (again: making an
				390	alias is preferrable to copying or moving the file, since this will
				391	cause the correct file to be used if you ever rebuild
				392	PythonApplet). <p>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	393
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	394	Next, you have to build the extension modules in the
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	395	<code>PlugIns</code> folder. Open each project with <code>.ppc</code> in the
				396	name and build it. After all
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	397	the dynamically loaded modules are built you have to create a number
				398	of aliases: some modules live together in a single dynamic
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	399	library. Run the <code>MkPluginAliases.py</code> script from
				400	<code>Mac:scripts</code> to create the aliases. <p>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	401
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	402	Finally, you must build the standard applets:
				403	<code>EditPythonPrefs</code>, <code>mkapplet</code>, etc. This is
				404	easiest done with the <code>fullbuild</code> script from
				405	<code>Mac:scripts</code>. Answer <em>no</em> to all questions except
				406	when it asks whether to build the applets. <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
				415	this use only.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	416	</BLOCKQUOTE>
				417
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	418	You are all set now, and should read the release notes and
				419	<code>ReadMeOrSuffer</code> file from the <code>Mac</code> folder.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	420
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	421	<H2>Rebuilding <code>.exp</code> files for PPC and CFM68K</H2>
				422
				423	Occasionally it may be necessary to rebuild your PythonCore <code>.exp</code>
				424	file, a file that controls which symbols are exported by your PythonCore
				425	shared library. Rebuild it if you get unexpected undefined symbols when you
				426	are building a plugin module. <p>
				427
				428	Rebuilding the .exp file is done by first removing the file and removing the
				429	reference to it in the project (in the "config" section). Next, build PythonCore.
				430	This will create a new .exp file. Edit this file to remove the references to
				431	the symbols <code>__initialize</code>, <code>__terminate</code>, <code>setjmp</code>,
				432	<code>longjmp</code> and <code>__ptmf_null</code>. Next, add the .exp file to the project
				433	again and rebuild PythonCore. <p>
				434
				435	This rather convoluted procedure is needed to ensure that plugin modules don't
				436	accidentally link with those entrypoints from PythonCore, which will not work because
				437	those routines have to be in the same code fragment as they are used from.
				438
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	439	<H2>Odds and ends</H2>
				440
				441	Some remarks that I could not fit in elsewhere:
				442
				443	<UL>
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	444
Jack Jansen	4c1e56c	1996-08-06 16:16:20 +0000	[diff] [blame]	445	<LI> It may be possible to use the <code>PythonCore</code> shared
				446	library to embed Python in another program, if your program can live
				447	with using GUSI for I/O. Use PythonCore in stead of your C library
				448	(or, at the very least, link it before the normal C library). Let me
				449	know whether this works.
				450
				451	<LI> It is possible to build PPC extension modules without building a
				452	complete Python. Take the binary distribution, add folders
				453	<code>Include</code>, <code>Mac:Include</code> and
				454	<code>Mac:mwerks</code> from the source distribution and you should be
				455	all set. A template for a dynamic module can be found in
Jack Jansen	27b10ec	1996-08-23 15:44:18 +0000	[diff] [blame]	456	<code>xx.ppc.µ</code> or <code>xx.CFM68K.µ</code>.
				457
				458	<LI> The Python shared library architecture is a variant of the architecture
				459	described as "application with shared libraries and dropins" in the MetroWerks
				460	"Targeting MacOS" documentation. The Python Application and applet-template use
				461	the <code>AppRuntime.Lib</code> runtime library (with properly set CFM
				462	initialization and termination routines). PythonCore uses <code>ShlibRuntime.Lib</code>
				463	and <code>MWRuntimeStaticLib.Lib</code>, which is almost identical to the MW
				464	standard <code>MWRuntimeLib</code>, but not dynamically loaded. This library contains
				465	the part of the runtime that can (or must) be shared between all modules in the program.
				466	It is linked statically into PythonCore (and exported to the applications and plugins)
				467	so we do not have to distribute yet another shared library. Plugin modules use
				468	<code>ShlibRuntime.Lib</code> and obtain the rest from PythonCore. PythonCore uses a
				469	non-standard initialization entry point, <code>__initialize_with_resources</code>, to
				470	be able to obtain resources from the library file lateron. Plugins can do the same or
				471	use the standard <code>__initialize</code> entry point.
Jack Jansen	8f2d802	1996-08-05 15:34:45 +0000	[diff] [blame]	472
				473
				474	<UL>
				475	</BODY>
				476	</HTML>