diff options
| author | Jack Jansen <jack.jansen@cwi.nl> | 2000-04-22 21:48:56 (GMT) |
|---|---|---|
| committer | Jack Jansen <jack.jansen@cwi.nl> | 2000-04-22 21:48:56 (GMT) |
| commit | 968cde98fcac0ca911bc39e3b1d2c2945a8d0447 (patch) | |
| tree | 031a2f940c2819a93af3bd90e24be710c9cae1cc | |
| parent | 3af07e9a78b9b4b5a4776dd8db01928a39c08784 (diff) | |
| download | cpython-968cde98fcac0ca911bc39e3b1d2c2945a8d0447.zip cpython-968cde98fcac0ca911bc39e3b1d2c2945a8d0447.tar.gz cpython-968cde98fcac0ca911bc39e3b1d2c2945a8d0447.tar.bz2 | |
Added Corran Webster's explanation of how to write extensions in MPW and a pointer to his W documentation.
| -rw-r--r-- | Mac/Demo/html.icons/createmake.png | bin | 0 -> 14212 bytes | |||
| -rw-r--r-- | Mac/Demo/index.html | 19 | ||||
| -rw-r--r-- | Mac/Demo/mpwextensions.html | 484 |
3 files changed, 499 insertions, 4 deletions
diff --git a/Mac/Demo/html.icons/createmake.png b/Mac/Demo/html.icons/createmake.png Binary files differnew file mode 100644 index 0000000..50d6fa5 --- /dev/null +++ b/Mac/Demo/html.icons/createmake.png diff --git a/Mac/Demo/index.html b/Mac/Demo/index.html index 9845c20..26b08cc 100644 --- a/Mac/Demo/index.html +++ b/Mac/Demo/index.html @@ -27,11 +27,17 @@ in PostScript and other forms, see the <a href="http://www.python.org/doc/">documentation</a> section on the webserver. <p> -Some of these documents were actually written a long time ago and have seen -little maintainance, so use with care. <p> +The W widget set by Just van Rossum, which is used by the Python IDE, does not +have complete documentation as of this writing, but Corran Webster has +documented most of it on his +<A HREF="http://www.nevada.edu/~cwebster/Python/">Python Page</A>. + <H2>Table of contents</H2> +<blockquote><B>Note:</B> +Some of these documents were actually written a long time ago and have seen +little maintainance, so use with care. </blockquote> <UL> <LI> <A HREF="example0.html">Using python to create Macintosh applications, @@ -71,7 +77,12 @@ WASTE, an extended TextEdit replacement. is meant for the hardcore programmer, and shows how to create an extension module in C. It also handles using Modulator to create the boilerplate for your module, and creating dynamically-loadable modules -on PowerPC Macs. +on PowerPC Macs. It assumes you use CodeWarrior for you development. + +<LI> +<A HREF="mpwextensions.html">Creating C extension modules using MPW</A> +is a companion document, written by Corran Webster, which explains how you +can develop Python extensions using Apple's free MPW compiler environment. <LI> <A HREF="applescript.html">Using Open Scripting Architecture from Python</A> explains @@ -140,5 +151,5 @@ documentation. <p> <HR> <A HREF="http://www.cwi.nl/~jack">Jack Jansen</A>, -<A HREF="mailto:jack@cwi.nl">jack@cwi.nl</A>, 26-Jun-98. +<A HREF="mailto:jack@cwi.nl">jack@cwi.nl</A>, 22-Apr-00. </BODY></HTML> diff --git a/Mac/Demo/mpwextensions.html b/Mac/Demo/mpwextensions.html new file mode 100644 index 0000000..742cbc2 --- /dev/null +++ b/Mac/Demo/mpwextensions.html @@ -0,0 +1,484 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> +<HTML> + +<HEAD> + +<TITLE>HOWTO: Compiling Python Modules with MPW</TITLE> + +</HEAD> + +<BODY> + +<H1>HOWTO: Compiling Python Modules with MPW</H1> + +<blockquote> +This HOWTO is a slightly reformatted version of an original by +<A HREF="mailto:cwebster@nevada.edu">Corran Webster</A>, whose +<A HREF="http://www.nevada.edu/~cwebster/Python/">Python page</A> +may contain a more up-to-date version. +</blockquote> +<HR> + +<P> +The <A HREF="http://www.cwi.nl/~jack/macpython.html">Macintosh version</A> +of the <A HREF="http://www.python.org/">Python programming language</A> is +usually compiled with <A HREF="http://www.metrowerks.com/">Metrowerks +CodeWarrior</A>. As a result, C extension modules are also usually +compiled with CodeWarrior, and the documentation and sample code reflects +this. CodeWarrior is a commercial product, and may be beyond the budgets +of hobbyist hackers, making them dependent on others to compile C extension +modules. At the present time, many standard C extension modules compile +"out of the box" on the Macintosh, but in only a few cases is the plugin +for the Macintosh included in the distribution. +</P> + +<P> +The <A HREF="http://developer.apple.com/tools/mpw-tools/">Macintosh +Programmer's Workshop</A> (MPW) is Apple's development environment, and is +freely available for <A +HREF="ftp://ftp.apple.com/developer/Tool_Chest/Core_Mac_OS_Tools/MPW_etc./">download</A> +from Apple, as well as on their Developer CDs. Since Python was originally +developed using MPW, before CodeWarrior became the dominant MacOS +development environment, most of the idiosyncrasies of MPW are already +supported, and compilation of C extension modules in MPW is possible. +</P> + +<P> +This HOWTO only deals with compiling for PowerPC Macintoshes. The process +should be similar for 68k Macintoshes using the code fragment manager, but +I have not attempted this - my old Mac is running NetBSD. +</P> + +<P> +This way of compiling modules is still experimental. Please read the +caveats section below. +</P> + +<H2><A NAME="setup">Setting Up MPW for Compiling Python Modules</A></H2> + +<P> +This assumes that you have successfully installed both MPW and Python with +the Developer's Kit on your Macintosh. +</P> + +<P> +The first step is to let MPW know where you keep Python. This step is not +strictly necessary, but will make development easier and improve +portability. Create a new file in the <CODE>Startup Items</CODE> folder of +MPW called <A HREF="Python"><CODE>Python</CODE></A>. Type the lines: +</P> + +<PRE> +set Python "Macintosh HD:Applications:Python 1.5.2c1:" +set PythonIncludes "{Python}Include" +set PythonMacIncludes "{Python}Mac:Include" +set PythonCore "{Python}PythonCore" + +export Python PythonIncludes PythonMacIncludes PythonCore +</PRE> + +<P> +where <CODE>Macintosh HD:Applications:Python 1.5.2c1:</CODE> is replaced by +the path to the directory where you keep your copy of Python, and the other +variables reflect where you keep your header files and Python core files. +The locations here are the standard for Python 1.5.2c1, but they are +different for Python 1.52b2 and earlier (most notably, the PythonCore is +kept in the Extensions folder). +</P> + +<P> +Next, you need to update the <A HREF="config.h"><CODE>config.h</CODE></A> +file for the <CODE>MrC</CODE> compiler included with MPW. This header file +is located in the <CODE>:Mac:Include</CODE> folder in the standard +distribution. You can update it by hand, by adding the lines: +</P> + +<PRE> +#ifdef __MRC__ +#define BAD_STATIC_FORWARD +#endif +</PRE> + +<P> +at the after the similar defines for <CODE>__MWERKS__</CODE> and +<CODE>__SC__</CODE> in the file. This step is critical: many modules, +including ones in the standard distribution, will not compile properly +without this modification (see common problems below). +</P> + +<P> +Copies of both the <A HREF="Python"><CODE>Python</CODE></A> startup item +for MPW and the <A HREF="config.h"><CODE>config.h</CODE></A> are included +here for your convenience. +</P> + +<P> +If you are porting Unix modules to the mac, you may find it useful to +install <A +HREF="http://www.iis.ee.ethz.ch/~neeri/macintosh/gusi-qa.html">GUSI</A> for +your copy of MPW. GUSI provides some amount of POSIX compatibility, and is +used by Python itself for this purpose - at the very least having it's +header files available may be useful. Also of note for people porting Unix +modules, the most recent alpha version (4.1a8) of <CODE>MrC</CODE> and +<CODE>MrCpp</CODE> at this writing permits using unix-style pathnames for +includes via the <CODE>-includes unix</CODE> command line option. I have +not experimented heavily with this, but will be doing so in the future and +report my findings. +</P> + +<P> +You now have MPW and Python set up to allow compilation of modules. +</P> + +<H2><A NAME="compiling">Compiling a Module</A></H2> + +<P> +This assumes that you have a C extension module ready to compile. For +instructions on how to write a module, see the Python documentation. +</P> + +<P> +There are three approaches you can take to compiling in MPW: using the +command line interface, using the MPW <CODE>CreateMake</CODE> command +(available as the "Create build commands..." menu item, and writing a +Makefile by hand. +</P> + +<P> +Before you start any of these, you'll need to know: +</P> + +<UL> + <LI>The names and locations of the C source files. In the examples, this + is the file <A HREF="xxmodule.c"><CODE>xxmodule.c</CODE></A>, and is in + MPW's current working directory. + <LI>The name that Python expects to import your module under. In the + examples, this is <CODE>xx</CODE>, so the shared library file will be + called <CODE>xx.ppc.slb</CODE>. + <LI>The location of any additional header files use by the C source. The + example does not use any additional header files. + <LI>The location of any additional shared libraries which the module needs + to link to. The example does not link to any other shared libraries. + <LI>The name of the entry point to your module. This is usually the last + function in the main C source file, and the name usually starts with + <CODE>init</CODE>. In the examples, this is <CODE>initxx</CODE>. +</UL> + +<H3>Using the Command Line</H3> + +<P> +For simple modules consisting of one or two C files, it's often convenient +to simply use commands in a MPW Worksheet. Usually you will want to set +MPW's working directory to the directory containing the C source code. The +following commands compile and link the standard Python test module <A +HREF="xxmodule.c"><CODE>xxmodule.c</CODE></A>: +</P> + +<PRE> +MrC "xxmodule.c" -o "xx.c.x" -w off -d HAVE_CONFIG_H ∂ + -i "{PythonMacIncludes}" ∂ + -i "{PythonIncludes}" +PPCLink ∂ + -o "xx.ppc.slb" ∂ + "xx.c.x" ∂ + -t 'shlb' ∂ + -c 'Pyth' ∂ + -xm s ∂ + -d ∂ + "{PythonCore}" ∂ + "{SharedLibraries}InterfaceLib" ∂ + "{SharedLibraries}MathLib" ∂ + "{SharedLibraries}StdCLib" ∂ + "{PPCLibraries}StdCRuntime.o" ∂ + "{PPCLibraries}PPCCRuntime.o" ∂ + "{PPCLibraries}PPCToolLibs.o" ∂ + -export initxx +</PRE> + +<P> +(Note: The last character on each line should appear as "partial +derivative" symbol, which you type as <KBD>option-d</KBD> and which is +MPW's line continuation symbol.) +</P> + +<P> +Any additional header files should be specified by adding their directories +as extra <CODE>-i</CODE> options to the <CODE>MrC</CODE> command. Any +additional shared libraries should be added before the PythonCore library +in the <CODE>PPCLink</CODE> command. +</P> + +<P> +If there is more than one source file, you will need to duplicate the +compile command for each source file, and you will need to include all the +object files in the place where <CODE>"xx.c.x"</CODE> appears in the +<CODE>PPCLink</CODE> command. +</P> + +<H3>Using CreateMake</H3> + +<P> +For more complex modules, or modules that you are writing yourself, you +will probably want to use a makefile. Unfortunately MPW's makefiles are +incompatible with the standard Unix makefiles, so you will not be able to +use any makefiles which come with a C module. +</P> + +<P> +Usually, you will want the makefile to reside in the same directory as the +C source code, so you should set MPW's working directory to that directory +before proceeding. +</P> + +<P> +To create a makefile for the standard Python test module <A +HREF="xxmodule.c"><CODE>xxmodule.c</CODE></A>: +</P> + +<UL> + <LI>Select "Create build commands..." from the "Build" Menu. + <LI>Type <KBD>xx.ppc.slb</KBD> for the Program Name. + <LI>Select "Shared Library" for the Program Type. + <LI>Select "PowerPC Only" for the Target. + <LI>Click on the "Source Files..." button, and add your module's C source + files to the list. + <LI>Click on the "Other Options..." button and change the creator type to + "Pyth". If you are using additional header files, you can also add their + directories at this stage. Click on "Continue" once you have done this. + <LI>Click on the "Exported Symbols..." button and type <KBD>initxx</KBD> + into the entry field. Click on "Continue" once you have done this. + <LI>At this stage, your CreateMake window should look like this: <IMG + SRC="html.icons/createmake.png" ALT="[picture of commando window for CreateMake]"> + <LI>Click on the "CreateMake" button. +</UL> + +<P> +You will now need to edit the makefile that was just created. Open the +file "xx.ppc.slb.make" in the current directory and make the following +changes: +</P> + +<UL> + <LI>Change the line + + <PRE> +Includes = +</PRE> + + <P> + to read + </P> + + <PRE> +Includes = -i "{PythonIncludes}" -i "{PythonMacIncludes}" +</PRE> + + <P> + If you have any additional headers than need to be included, you can add + them here as well. + <LI>Change the line + + <PRE> +PPCCOptions = {Includes} {Sym•PPC} +</PRE> + + <P> + to read + </P> + + <PRE> +PPCCOptions = -w off -d HAVE_CONFIG_H {Includes} {Sym•PPC} +</PRE> + + <P> + <LI>After the line + + <PRE> + -xm s ∂ +</PRE> + + <P> + add + </P> + + <PRE> + -d ∂ + "{PythonCore}" ∂ +</PRE> + + <P> + If you have any other shared libraries you need to link to, add each on a + line before PythonCore, terminating each line with a <CODE>∂</CODE>. + </P> + +</UL> + +<P>Save the file. You are now ready to build. +</P> + +<P> +Go to the "Build" or "Full Build" menu items, type in +<KBD>xx.ppc.slb</KBD>, and MPW should take things from there. Any time you +need to rebuild the shared library, you can simply do another "Build" or +"Full Build". +</P> + +<H3>Writing a Makefile by Hand</H3> + +<P> +For modules which have complex interdependencies between files, you will +likely need a more sophisticated makefile than the one created by +<CODE>CreateMake</CODE>. You will need to be familiar with the MPW +makefile format, but you can get a start by either using +<CODE>CreateMake</CODE> to get a simple starting point, or taking another +MPW makefile as a starting point. +</P> + +<P> +It is beyond the scope of this HOWTO to go into the generalities of MPW +makefiles. Documentation on MPW's <CODE>Make</CODE> command can be found +with the MPW distribution, in particular the documents <A +HREF="http://developer.apple.com/tools/mpw-tools/books.html#Building">Building +and Maintaining Programs with MPW (2nd Edition)</A> and the <A +HREF="http://developer.apple.com/tools/mpw-tools/books.html#CommandRef">MPW +Command Reference</A>. +</P> + +<P> +There are a couple of important points to keep in mind when writing a +makefile by hand:</P> + +<UL> + <LI>When there are multiple symbols with the same name in object files or + shared libraries, <CODE>PPCLink</CODE> used the symbol from the file which + appears first in arguments of the <CODE>PPCLink</CODE> command. For this + reason, you will usually want the PythonCore and any other shared libraries + which are not part of the standard MPW runtime environment to appear before + the standard runtime libraries. This is particularly the case with + StdCLib. The "-d" option turns off the (often copious) warnings about + multiply defined symbols. + <LI>You will want to make sure that the <CODE>HAVE_CONFIG_H</CODE> + preprocessor symbol is defined for most C source files using the <CODE>-d + HAVE_CONFIG_H</CODE> option to <CODE>MrC</CODE>. +</UL> + +<P> +The file <A HREF="xx.ppc.slb.make.sit.hqx"><CODE>xx.ppc.slb.make</CODE></A> +is included here for you to use as a starting point. +</P> + +<H2><A NAME="using">Using the Extension Module</A></H2> + +<P> +Once you have compiled your extension module, you will need to let Python +know where it is. You can either move it into a place on Python's search +path - such as the <CODE>:Mac:Plugins</CODE> folder - or modify the path to +include the location of your new module using the +<CODE>EditPythonPrefs</CODE> applet. +</P> + +<P> +Your work may not be completely done, as many extension modules have a +Python wrapper around them. If the Python was not written with portability +in mind, you may need to do some more work to get that up and running. +Indeed, if the Python part uses OS-specific features, like pipes, you may +have to completely rewrite it if you can make it work at all. +</P> + +<H2><A NAME="problems">Common Problems</A></H2> + +<P> +There are a couple of common problems which occur when porting a module +from another platform. Fortunately, they are often easy to fix. +</P> + +<H3>Static Forward Definitions</H3> + +<P> +If you get a compiler error which looks something like: +</P> + +<PRE> +File "xxmodule.c"; line 135 #Error: 'Xxo_Type' is already defined +</PRE> + +<P> +then most likely either you have not set up <CODE>config.h</CODE> correctly +to handle static forward definitions, or the module author has not adhered +to the standard python conventions. If the second is the case, find where +the variable is first defined, and replace the <CODE>static</CODE> with +<CODE>staticforward</CODE>. Then find the second place it is defined +(usually the line where the compiler complained) and replace +<CODE>static</CODE> with <CODE>statichere</CODE>. +</P> + +<P> +If you have set up things correctly, you should now be able to compile. +</P> + +<H3>Automatic Type Conversion</H3> + +<P> +<CODE>MrC</CODE> seems to be a little pickier about automatically +converting from one type to another than some other C compilers. These can +often be fixed by simply adding an explicit cast to the desired type. +</P> + +<P> +XXX There may be a compiler option which relaxes this. That would be a +better solution. +</P> + +<H2><A NAME="caveats">Caveats</A></H2> + +<P> +As Jack Jansen pointed out on the Mac Python mailing list, there could +potentially be conflicts between the MetroWerks C runtime which the Python +core and standard modules was compiled with, and the MPW C runtime which +your extension module is compiled with. While things seem to work fine in +everyday use, it is possible that there are bugs which have not been +discovered yet. Most likely these world take the form of standard C +functions (most likely I/O functions due to conflicts between the SIOUX +libraries and the SIOW libraries) not working as they are supposed to, or +memory leaks caused by improper malloc/free. +</P> + +<P> +Some such problems have been demonstrated by compiling modules with +PythonCore linked after StdCLib - printf does not work properly in this +setup, and I suspect that there will also be malloc/free problems in +situations where the module allocates memory which is later disposed of by +Python, or vice-versa. Compiling with PythonCore taking precedence over +StdCLib seems to give the correct behaviour. +</P> + +<P> +This method of compiling should be considered experimental for the time +being. <STRONG>Use it at your own risk.</STRONG> +</P> + +<P> +If you notice any quirks in modules compiled this way, or have insight into +what may go wrong or right with this situation, <A +HREF="mailto:cwebster@nevada.edu">please contact me</A> so that I can add +it to the HOWTO. +</P> + +<P> +The ideal solution to this problem would be to get Python to compile using +MPW (and a Python MPW Tool would be very neat indeed). However, that does +seem to be a major project. +</P> + +<DIV class=footer> +<HR> +<BR> +©<A HREF="mailto:cwebster@nevada.edu">Corran Webster</A>, 1999. <BR> +<!-- #LASTMODIFIED TEXT="Last modified" FORM="SHORT,TIME" --> +Last modified 14/12/99 12:17 PM +<!-- /#LASTMODIFIED --> +</DIV> + +</BODY> + +</HTML> |
