| <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. The actual example does not work anymore, as both |
| MacTCP and Interslip died long ago, but the text is still mostly |
| correct.<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 |
| need Version 7 or later. 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 to install the Developer option in the MacPython installer. |
| 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> |
| |
| If you installed Tk support when you installed Python this is extremely |
| simple. 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>Creating a plugin module</H2> |
| |
| The easiest way to build a plugin module is to use the distutils package, |
| this works fine on MacOS with CodeWarrior. See the distutils documentation |
| for details. Keep in mind that even though you are on the Mac you specify |
| filenames with Unix syntax: they are actually URLs, not filenames. |
| <p> |
| |
| Alternatively you can build the project file by hand. |
| Go to the ":Mac:Build" folder and copy the files xx.carbon.mcp, |
| and xx.carbon.mcp.exp to interslipmodule.carbon.mcp and |
| interslipmodule.carbon.mcp.exp, respectively. Edit |
| interslipmodule.carbon.mcp.exp and change the name of the exported routine |
| "initxx" to "initinterslip". Open interslipmodule.carbon.mcp with CodeWarrior, |
| remove the file xxmodule.c and add interslipmodule.c and make a number |
| of adjustments to the preferences: |
| <UL> |
| <LI> in PPC target, set the output file name to "interslipmodule.carbon.slb", |
| <LI> if you are working without a source distribution (i.e. with a normal |
| binary distribution plus a development distribution) you will not have |
| a file <code>PythonCoreCarbon</code>. The installation process has deposited this |
| file in the System <code>Extensions</code> folder under the name |
| <code>PythonCoreCarbon <i>version</i></code>. Add that file to the project, replacing |
| <code>PythonCoreCarbon</code>. |
| <LI> you must either download and build GUSI (if your extension module uses sockets |
| or other Unix I/O constructs) or remove GUSI references from the Access Paths |
| settings. See the <a href="building.html">Building</a> document for where to get GUSI |
| and how to build it. |
| </UL> |
| Next, compile and link your module, fire up python and test it. <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> |