Explanations of the examples here

author: Jack Jansen <jack.jansen@cwi.nl> 1996-03-18 13:38:52 (GMT)
committer: Jack Jansen <jack.jansen@cwi.nl> 1996-03-18 13:38:52 (GMT)
commit: a6308130bb9e130ec532e05a2784e170584a5ac7 (patch)
tree: b85ff85f71045522a37067d013067082ce497b2b /Mac/Demo/plugins.html
parent: f4875af09c1c2dc2ad76329560ce4345b0fe4cd9 (diff)
download: cpython-a6308130bb9e130ec532e05a2784e170584a5ac7.zip
cpython-a6308130bb9e130ec532e05a2784e170584a5ac7.tar.gz
cpython-a6308130bb9e130ec532e05a2784e170584a5ac7.tar.bz2
1 files changed, 363 insertions, 0 deletions
diff --git a/Mac/Demo/plugins.html b/Mac/Demo/plugins.html
new file mode 100644
index 0000000..465603c
--- /dev/null
+++ b/Mac/Demo/plugins.html
@@ -0,0 +1,363 @@
+<HTML><HEAD><TITLE>Creating a C extension module on the Macintosh</TITLE></HEAD>
+<BODY>
+<H1>Creating a C extension module on the Macintosh</H1>
+<HR>
+
+This document gives a step-by-step example of how to create a new C
+extension module on the mac. For this example, we will create a module
+to interface to the programmers' API of InterSLIP, a package that
+allows you to use MacTCP (and, hence, all internet services) over a
+modem connection. <p>
+
+<H2>Prerequisites</H2>
+
+There are a few things you need to pull this off. First and foremost,
+you need a C development environment. Actually, you need a specific
+development environment, CodeWarrior by <A
+HREF="http://www.metrowerks.com/">MetroWerks</A>.  You will probably
+need the latest version. You may be able to get by with an older
+version of CodeWarrior or with another development environment (Up to
+about 1994 python was developed with THINK C, and in the dim past it
+was compiled with MPW C) assuming you have managed to get Python to
+compile under your development environment, but the step-by-step
+character of this document will be lost. <p>
+
+Next, you need a <A HREF="http://www.python.org/python/Sources.html">python
+source distribution</A>.  There is a <A
+HREF="update-to-1.3/into-PlugIns.hqx"> fixed project template</A> that
+you also need if you are going to make a dynamically loaded
+module. For PowerPC development you can actually get by without a full
+source distribution, using the PPC Development distribution (if I have
+gotten around to putting it together by the time you read
+this). You'll also need a functional python interpreter, and the
+Modulator program (which lives in <CODE>Tools:Modulator</CODE> in the
+standard source distribution). You may also find that Guido's <A
+HREF="http://www.python.org/doc/ext/ext.html">Extending and embedding
+the Python interpreter</A> is a very handy piece of documentation. I
+will skip lots of details that are handled there, like complete
+descriptions of <CODE>Py_ParseTuple</CODE> and such utility routines,
+or the general structure of extension modules. <p>
+
+<H2>InterSLIP and the C API to it</H2>
+
+InterSLIP, the utility to which we are going to create a python
+interface, is a system extension that does all the work of connecting
+to the internet over a modem connection. InterSLIP is provided
+free-of-charge by <A
+HREF="http://www.intercon.com/">InterCon</A>. First it connects to
+your modem, then it goes through the whole process of dialling,
+logging in and possibly starting the SLIP software on the remote
+computer and finally it starts with the real work: packing up IP
+packets handed to it by MacTCP and sending them to the remote side
+(and, of course, the reverse action of receiving incoming packets,
+unpacking them and handing them to MacTCP). InterSLIP is a device
+driver, and you control it using a application supplied with it,
+InterSLIP Setup. The API that InterSLIP Setup uses to talk to the
+device driver is published in the documentation and, hence, also
+useable by other applications. <p>
+
+I happened to have a C interface to the API, which is all ugly
+low-level device-driver calls by itself. The C interface is in <A
+HREF="interslip/InterslipLib.c">InterslipLib.c</A> and <A
+HREF="interslip/InterslipLib.h">InterslipLib.h</A>, we'll
+concentrate here on how to build the Python wrapper module around
+it. Note that this is the "normal" situation when you are writing a
+Python extension module: you have some sort of functionality available
+to C programmers and want to make a Python interface to it. <p>
+
+<H2>Using Modulator</H2>
+
+The method we describe in this document, using Modulator, is the best
+method for small interfaces. For large interfaces there is another
+tool, Bgen, which actually generates the complete module without you
+lifting a single finger. Bgen, however, has the disadvantage of having
+a very steep learning curve, so an example using it will have to wait
+until another document, when I have more time. <p>
+
+First, let us look at the <A
+HREF="interslip/InterslipLib.h">InterslipLib.h</A> header file,
+and see that the whole interface consists of six routines:
+<CODE>is_open</CODE>, <CODE>is_connect</CODE>,
+<CODE>is_disconnect</CODE>, <CODE>is_status</CODE>,
+<CODE>is_getconfig</CODE> and <CODE>is_setconfig</CODE>.  Our first
+step will be to create a skeleton file <A
+HREF="interslip/@interslipmodule.c">@interslipmodule.c</A>, a
+dummy module that will contain all the glue code that python expects
+of an extension module. Creating this glue code is a breeze with
+modulator, a tool that we only have to tell that we want to create a
+module with methods of the six names above and that will create the
+complete skeleton C code for us. <p>
+
+Why call this dummy module <CODE>@interslipmodule.c</CODE> and not
+<CODE>interslipmodule.c</CODE>? Self-preservation: if ever you happen
+to repeat the whole process after you have actually turned the
+skeleton module into a real module you would overwrite your
+hand-written code. By calling the dummy module a different name you
+have to make <EM>two</EM> mistakes in a row before you do this. <p>
+
+On systems with the Tk windowing API for Python (currently only
+unix/X11 systems, but mac support may be available when you read this)
+this is extremely simple. It is actually so simple that it pays to
+create the skeleton module under unix and ship the code to your
+mac. You start modulator and are provided with a form in which you
+fill out the details of the module you are creating. <p>
+
+<IMG SRC="html.icons/modulator.gif" ALIGN=CENTER><p>
+
+You'll need to supply a module name (<CODE>interslip</CODE>, in our
+case), a module abbreviation (<CODE>pyis</CODE>, which is used as a
+prefix to all the routines and data structures modulator will create
+for you) and you enter the names of all the methods your module will
+export (the list above, with <CODE>is_</CODE> stripped off). Note that
+we use <CODE>pyis</CODE> as the prefix instead of the more logical
+<CODE>is</CODE>, since the latter would cause our routine names to
+collide with those in the API we are interfacing to! The method names
+are the names as seen by the python program, and the C routine names
+will have the prefix and an underscore prepended. Modulator can do
+much more, like generating code for objects and such, but that is a
+topic for a later example. <p>
+
+Once you have told modulator all about the module you want to create
+you press "check", which checks that you haven't omitted any
+information and "Generate code". This will prompt you for a C output
+file and generate your module for you. <p>
+
+<H2>Using Modulator without Tk</H2>
+
+
+Modulator actually uses a two-stage process to create your code: first
+the information you provided is turned into a number of python
+statements and then these statements are executed to generate your
+code. This is done so that you can even use modulator if you don't
+have Tk support in Python: you'll just have to write the modulator
+python statements by hand (about 10 lines, in our example) and
+modulator will generate the C code (about 150 lines, in our
+example). Here is the Python code you'll want to execute to generate
+our skeleton module: <p>
+
+<CODE><PRE>
+	import addpack
+	addpack.addpack('Tools')
+	addpack.addpack('modulator')
+	import genmodule
+
+	m = genmodule.module()
+	m.name = 'interslip'
+	m.abbrev = 'pyis'
+	m.methodlist = ['open', 'connect', 'disconnect', 'status', \
+		'getconfig', 'setconfig']
+	m.objects = []
+
+	fp = open('@interslipmodule.c', 'w')
+	genmodule.write(fp, m)
+</PRE></CODE>
+
+Drop this program on the python interpreter and out will come your
+skeleton module. <p>
+
+Now, rename the file to interslipmodule.c and you're all set to start
+developing. The module is complete in the sense that it should
+compile, and that if you import it in a python program you will see
+all the methods.  It is, of course, not yet complete in a functional
+way... <p>
+
+<H2>Adding a module to 68K Python</H2>
+
+What you do now depends on whether you're developing for PowerPC (or
+for CFM68K) or for "traditional" mac. For a traditional 68K Python,
+you will have to add your new module to the project file of the Python
+interpreter, and you have to edit "config.c" to add the module to the
+set of builtin modules. In config.c you will add the module at two
+places: near the start of the file there is a list of external
+declarations for all init() routines. Add a line of the form
+<CODE><PRE>
+		extern void initinterslip();
+</PRE></CODE>
+here. Further down the file there is an array that is initialized with
+modulename/initfunction pairs. Add a line of the form
+<CODE><PRE>
+		{"interslip",	initinterslip},
+</PRE></CODE>
+here. You may want to bracket these two lines with
+<CODE><PRE>
+	#ifdef USE_INTERSLIP
+	#endif
+</PRE></CODE>
+lines, that way you can easily control whether the module is
+incorporated into python at compile time. If you decide to do the
+latter edit your config file (you can find the name in the "C/C++
+language" section of the MW preferences dialog, it will probably be
+"mwerks_nonshared_config.h") and add a
+<CODE><PRE>
+	#define USE_INTERSLIP
+</PRE></CODE>
+
+Make the new interpreter and check that you can import the module, see
+the methods (with "dir(interslip)") and call them. <p>
+
+<H2>Creating a PowerPC plugin module</H2>
+
+For PowerPC development you could follow the same path, but it is
+actually a better idea to use a dynamically loadable module. The
+advantage of dynamically loadable modules is that they are not loaded
+until a python program actually uses them (resulting in less memory
+usage by the interpreter) and that development is a lot simpler (since
+your projects will all be smaller). Moreover, you can distribute a
+plugin module by itself without haveing to distribute a complete
+python interpreter. <p>
+
+Go to the "PlugIns" folder and copy the files xxmodule.�,
+xxmodule_config.h and xxmodule.�.exp to interslipmodule.�,
+interslipmodule_config.h and interslipmodule.�.exp, respectively. Edit
+interslipmodule.�.exp and change the name of the exported routine
+"initxx" to "initinterslip".  Open interslipmodule.� with CodeWarrior,
+remove the file xxmodule.c and add interslipmodule.c and make a number
+of adjustments to the preferences:
+<UL>
+<LI> in C/C++ language, set the header file to interslipmodule_config.h
+<LI> in PPC linker, set the entry point to "initinterslip"
+<LI> in PPC PEF, set the fragment name to "interslipmodule"
+<LI> in PPC Project, set the output file name to "interslipmodule.slb".
+</UL>
+Next, compile and link your module, fire up python and do the same
+tests as for 68K python. <p>
+
+<H2>Getting the module to do real work</H2>
+
+So far, so good. In half an hour or so we have created a complete new
+extension module for Python. The downside, however, is that the module
+does not do anything useful. So, in the next half hour we will turn
+our beautiful skeleton module into something that is at least as
+beautiful but also gets some serious work done.  For this once,
+<EM>I</EM> have spent that half hour for you, and you can see the
+results in <A
+HREF="interslip/interslipmodule.c">interslipmodule.c</A>. <p>
+
+We add
+<CODE><PRE>
+	#include "InterslipLib.h"
+	#include "macglue.h"
+</PRE></CODE>
+to the top of the file, and work our way through each of the methods
+to add the functionality needed. Starting with open, we fill in the
+template docstring, the value accessible from Python by looking at
+<CODE>interslip.open.__doc__</CODE>.  There are not many tools using
+this information at the moment, but as soon as class browsers for
+python become available having this minimal documentation available is
+a good idea. We put "Load the interslip driver" as the comment
+here. <p>
+
+Next, we tackle the body of <CODE>pyis_open()</CODE>.  Since it has no
+arguments and no return value we don't need to mess with that, we just
+have to add a call to <CODE>is_open()</CODE> and check the return for
+an error code, in which case we raise an error:
+<CODE><PRE>
+	err = is_open();
+	if ( err ) {
+		PyErr_Mac(ErrorObject, err);
+		return NULL;
+	}
+</PRE></CODE>
+The routine <CODE><A NAME="PyErr_Mac">PyErr_Mac()</A></CODE> is a
+useful routine that raises the exception passed as its first
+argument. The data passed with the exception is based on the standard
+MacOS error code given, and PyErr_Mac() attempts to locate a textual
+description of the error code (which sure beats the "error -14021"
+messages that so many macintosh applications tell their poor
+users). <p>
+
+We will skip pyis_connect and pyis_disconnect here, which are pretty
+much identical to pyis_open: no arguments, no return value, just a
+call and an error check. With pyis_status() things get interesting
+again: this call still takes 3 arguments, and all happen to be values
+returned (a numeric connection status indicator, a message sequence
+number and a pointer to the message itself, in MacOS pascal-style
+string form). We declare variables to receive the returned values, do
+the call, check the error and format the return value. <p>
+
+Building the return value is done using <CODE><A
+NAME="Py_BuildValue">Py_BuildValue</A></CODE>:
+<CODE><PRE>
+	return Py_BuildValue("iiO&", (int)status, (int)seqnum, PyMac_BuildStr255, message);
+</PRE></CODE>
+Py_BuildValue() is a very handy routine that builds tuples according
+to a format string, somewhat similar to the way <CODE>printf()</CODE>
+works.  The format string specifies the arguments expected after the
+string, and turns them from C objects into python objects. The
+resulting objects are put in a python tuple object and returned. The
+"i" format specifier signifies an "int" (hence the cast: status and
+seqnum are declared as "long", which is what the is_status() routine
+wants, and even though we use a 4-byte project there is really no
+reason not to put the cast here). Py_BuildValue and its counterpart
+Py_ParseTuple have format codes for all the common C types like ints,
+shorts, C-strings, floats, etc. Also, there is a nifty escape
+mechanism to format values about which is does not know. This is
+invoked by the "O&" format: it expects two arguments, a routine
+pointer and an int-sized data object. The routine is called with the
+object as a parameter and it should return a python objects
+representing the data. <CODE>Macglue.h</CODE> declares a number of
+such formatting routines for common MacOS objects like Str255, FSSpec,
+OSType, Rect, etc. See the comments in the include file for
+details. <p>
+
+<CODE>Pyis_getconfig()</CODE> is again similar to pyis_getstatus, only
+two minor points are worth noting here.  First, the C API return the
+input and output baudrate squashed together into a single 4-byte
+long. We separate them out before returning the result to
+python. Second, whereas the status call returned us a pointer to a
+<CODE>Str255</CODE> it kept we are responsible for allocating the
+<CODE>Str255</CODE> for getconfig. This is something that would have
+been easy to get wrong had we not used prototypes everywhere. Morale:
+always try to include the header files for interfaces to libraries and
+other stuff, so that the compiler can catch any mistakes you make. <p>
+
+<CODE>Pyis_setconfig()</CODE> finally shows off
+<CODE>Py_ParseTuple</CODE>, the companion function to
+<CODE>Py_BuildValue</CODE>.  You pass it the argument tuple "args"
+that your method gets as its second argument, a format string and
+pointers to where you want the arguments stored. Again, standard C
+types such as strings and integers Py_ParseTuple knows all about and
+through the "O&" format you can extend the functionality. For each
+"O&" you pass a function pointer and a pointer to a data area. The
+function will be called with a PyObject pointer and your data pointer
+and it should convert the python object to the correct C type. It
+should return 1 on success and 0 on failure. Again, a number of
+converters for standard MacOS types are provided, and declared in
+<CODE>macglue.h</CODE>. <p>
+
+Next in our source file comes the method table for our module, which
+has been generated by modulator (and it did a good job too!), but
+which is worth looking at for a moment.  Entries are of the form
+<CODE><PRE>
+	{"open",	pyis_open,	1,	pyis_open__doc__},
+</PRE></CODE>
+where the entries are python method name, C routine pointer, flags and
+docstring pointer.  The value to note is the 1 for the flags: this
+signifies that you want to use "new-style" Py_ParseTuple behaviour. If
+you are writing a new module always use this, but if you are modifying
+old code which calls something like <CODE>getargs(args, "(ii)",
+...)</CODE> you will have to put zero here. See "extending and
+embedding" or possibly the getargs.c source file for details if you
+need them. <p>
+
+Finally, we add some code to the init module, to put some symbolic
+constants (codes that can by returned by the status method) in the
+module dictionary, so the python program can use "interslip.RUN"
+instead of the cryptic "4" when it wants to check that the interslip
+driver is in RUN state. Modulator has already generated code to get at
+the module dictionary using PyModule_GetDict() to store the exception
+object, so we simply call
+<CODE><PRE>
+	PyDict_SetItemString(d, "IDLE", PyInt_FromLong(IS_IDLE));
+</PRE></CODE>
+for each of our items. Since the last bit of code in our init routine
+checks for previous errors with <CODE>PyErr_Occurred()</CODE> and
+since <CODE>PyDict_SetItemString()</CODE> gracefully handles the case
+of <CODE>NULL</CODE> parameters (if <CODE>PyInt_FromLong()</CODE>
+failed, for instance) we don't have to do error checking here. In some
+other cases you may have to do error checking yourself. <p>
+
+This concludes our crash-course on writing Python extensions in C on
+the Macintosh.  If you are not done reading yet I suggest you look
+back at the <A HREF="index.html">MacPython Crashcourse index</A> to
+find another topic to study. <p>
author	Jack Jansen <jack.jansen@cwi.nl>	1996-03-18 13:38:52 (GMT)
committer	Jack Jansen <jack.jansen@cwi.nl>	1996-03-18 13:38:52 (GMT)
commit	a6308130bb9e130ec532e05a2784e170584a5ac7 (patch)
tree	b85ff85f71045522a37067d013067082ce497b2b /Mac/Demo/plugins.html
parent	f4875af09c1c2dc2ad76329560ce4345b0fe4cd9 (diff)
download	cpython-a6308130bb9e130ec532e05a2784e170584a5ac7.zip cpython-a6308130bb9e130ec532e05a2784e170584a5ac7.tar.gz cpython-a6308130bb9e130ec532e05a2784e170584a5ac7.tar.bz2