Mercurial > cpython-lru_cache-weakref

annotate Mac/Demo/plugins.html @ 4566:6403c94de50d legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added safeguard against failure in __del__.
author Guido van Rossum <guido@python.org>
date Wed, 27 Nov 1996 19:39:58 +0000
parents a71d2fd90fa8
children 9a3e6f0d6b5a
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
3457
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
1 <HTML><HEAD><TITLE>Creating a C extension module on the Macintosh</TITLE></HEAD>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
2 <BODY>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
3 <H1>Creating a C extension module on the Macintosh</H1>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
4 <HR>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
5
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
6 This document gives a step-by-step example of how to create a new C
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
7 extension module on the mac. For this example, we will create a module
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
8 to interface to the programmers' API of InterSLIP, a package that
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
9 allows you to use MacTCP (and, hence, all internet services) over a
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
10 modem connection. <p>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
11
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
12 <H2>Prerequisites</H2>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
13
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
14 There are a few things you need to pull this off. First and foremost,
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
15 you need a C development environment. Actually, you need a specific
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
16 development environment, CodeWarrior by <A
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
17 HREF="http://www.metrowerks.com/">MetroWerks</A>. You will probably
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
18 need the latest version. You may be able to get by with an older
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
19 version of CodeWarrior or with another development environment (Up to
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
20 about 1994 python was developed with THINK C, and in the dim past it
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
21 was compiled with MPW C) assuming you have managed to get Python to
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
22 compile under your development environment, but the step-by-step
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
23 character of this document will be lost. <p>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
24
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
25 Next, you need a <A HREF="http://www.python.org/python/Sources.html">python
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
26 source distribution</A>. There is a <A
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
27 HREF="update-to-1.3/into-PlugIns.hqx"> fixed project template</A> that
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
28 you also need if you are going to make a dynamically loaded
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
29 module. For PowerPC development you can actually get by without a full
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
30 source distribution, using the PPC Development distribution (if I have
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
31 gotten around to putting it together by the time you read
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
32 this). You'll also need a functional python interpreter, and the
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
33 Modulator program (which lives in <CODE>Tools:Modulator</CODE> in the
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
34 standard source distribution). You may also find that Guido's <A
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
35 HREF="http://www.python.org/doc/ext/ext.html">Extending and embedding
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
36 the Python interpreter</A> is a very handy piece of documentation. I
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
37 will skip lots of details that are handled there, like complete
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
38 descriptions of <CODE>Py_ParseTuple</CODE> and such utility routines,
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
39 or the general structure of extension modules. <p>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
40
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
41 <H2>InterSLIP and the C API to it</H2>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
42
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
43 InterSLIP, the utility to which we are going to create a python
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
44 interface, is a system extension that does all the work of connecting
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
45 to the internet over a modem connection. InterSLIP is provided
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
46 free-of-charge by <A
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
47 HREF="http://www.intercon.com/">InterCon</A>. First it connects to
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
48 your modem, then it goes through the whole process of dialling,
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
49 logging in and possibly starting the SLIP software on the remote
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
50 computer and finally it starts with the real work: packing up IP
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
51 packets handed to it by MacTCP and sending them to the remote side
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
52 (and, of course, the reverse action of receiving incoming packets,
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
53 unpacking them and handing them to MacTCP). InterSLIP is a device
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
54 driver, and you control it using a application supplied with it,
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
55 InterSLIP Setup. The API that InterSLIP Setup uses to talk to the
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
56 device driver is published in the documentation and, hence, also
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
57 useable by other applications. <p>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
58
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
59 I happened to have a C interface to the API, which is all ugly
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
60 low-level device-driver calls by itself. The C interface is in <A
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
61 HREF="interslip/InterslipLib.c">InterslipLib.c</A> and <A
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
62 HREF="interslip/InterslipLib.h">InterslipLib.h</A>, we'll
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
63 concentrate here on how to build the Python wrapper module around
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
64 it. Note that this is the "normal" situation when you are writing a
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
65 Python extension module: you have some sort of functionality available
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
66 to C programmers and want to make a Python interface to it. <p>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
67
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
68 <H2>Using Modulator</H2>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
69
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
70 The method we describe in this document, using Modulator, is the best
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
71 method for small interfaces. For large interfaces there is another
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
72 tool, Bgen, which actually generates the complete module without you
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
73 lifting a single finger. Bgen, however, has the disadvantage of having
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
74 a very steep learning curve, so an example using it will have to wait
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
75 until another document, when I have more time. <p>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
76
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
77 First, let us look at the <A
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
78 HREF="interslip/InterslipLib.h">InterslipLib.h</A> header file,
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
79 and see that the whole interface consists of six routines:
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
80 <CODE>is_open</CODE>, <CODE>is_connect</CODE>,
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
81 <CODE>is_disconnect</CODE>, <CODE>is_status</CODE>,
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
82 <CODE>is_getconfig</CODE> and <CODE>is_setconfig</CODE>. Our first
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
83 step will be to create a skeleton file <A
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
84 HREF="interslip/@interslipmodule.c">@interslipmodule.c</A>, a
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
85 dummy module that will contain all the glue code that python expects
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
86 of an extension module. Creating this glue code is a breeze with
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
87 modulator, a tool that we only have to tell that we want to create a
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
88 module with methods of the six names above and that will create the
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
89 complete skeleton C code for us. <p>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
90
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
91 Why call this dummy module <CODE>@interslipmodule.c</CODE> and not
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
92 <CODE>interslipmodule.c</CODE>? Self-preservation: if ever you happen
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
93 to repeat the whole process after you have actually turned the
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
94 skeleton module into a real module you would overwrite your
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
95 hand-written code. By calling the dummy module a different name you
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
96 have to make <EM>two</EM> mistakes in a row before you do this. <p>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
97
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
98 On systems with the Tk windowing API for Python (currently only
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
99 unix/X11 systems, but mac support may be available when you read this)
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
100 this is extremely simple. It is actually so simple that it pays to
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
101 create the skeleton module under unix and ship the code to your
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
102 mac. You start modulator and are provided with a form in which you
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
103 fill out the details of the module you are creating. <p>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
104
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
105 <IMG SRC="html.icons/modulator.gif" ALIGN=CENTER><p>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
106
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
107 You'll need to supply a module name (<CODE>interslip</CODE>, in our
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
108 case), a module abbreviation (<CODE>pyis</CODE>, which is used as a
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
109 prefix to all the routines and data structures modulator will create
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
110 for you) and you enter the names of all the methods your module will
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
111 export (the list above, with <CODE>is_</CODE> stripped off). Note that
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
112 we use <CODE>pyis</CODE> as the prefix instead of the more logical
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
113 <CODE>is</CODE>, since the latter would cause our routine names to
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
114 collide with those in the API we are interfacing to! The method names
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
115 are the names as seen by the python program, and the C routine names
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
116 will have the prefix and an underscore prepended. Modulator can do
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
117 much more, like generating code for objects and such, but that is a
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
118 topic for a later example. <p>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
119
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
120 Once you have told modulator all about the module you want to create
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
121 you press "check", which checks that you haven't omitted any
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
122 information and "Generate code". This will prompt you for a C output
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
123 file and generate your module for you. <p>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
124
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
125 <H2>Using Modulator without Tk</H2>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
126
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
127
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
128 Modulator actually uses a two-stage process to create your code: first
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
129 the information you provided is turned into a number of python
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
130 statements and then these statements are executed to generate your
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
131 code. This is done so that you can even use modulator if you don't
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
132 have Tk support in Python: you'll just have to write the modulator
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
133 python statements by hand (about 10 lines, in our example) and
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
134 modulator will generate the C code (about 150 lines, in our
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
135 example). Here is the Python code you'll want to execute to generate
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
136 our skeleton module: <p>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
137
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
138 <CODE><PRE>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
139 import addpack
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
140 addpack.addpack('Tools')
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
141 addpack.addpack('modulator')
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
142 import genmodule
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
143
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
144 m = genmodule.module()
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
145 m.name = 'interslip'
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
146 m.abbrev = 'pyis'
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
147 m.methodlist = ['open', 'connect', 'disconnect', 'status', \
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
148 'getconfig', 'setconfig']
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
149 m.objects = []
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
150
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
151 fp = open('@interslipmodule.c', 'w')
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
152 genmodule.write(fp, m)
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
153 </PRE></CODE>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
154
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
155 Drop this program on the python interpreter and out will come your
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
156 skeleton module. <p>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
157
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
158 Now, rename the file to interslipmodule.c and you're all set to start
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
159 developing. The module is complete in the sense that it should
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
160 compile, and that if you import it in a python program you will see
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
161 all the methods. It is, of course, not yet complete in a functional
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
162 way... <p>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
163
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
164 <H2>Adding a module to 68K Python</H2>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
165
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
166 What you do now depends on whether you're developing for PowerPC (or
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
167 for CFM68K) or for "traditional" mac. For a traditional 68K Python,
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
168 you will have to add your new module to the project file of the Python
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
169 interpreter, and you have to edit "config.c" to add the module to the
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
170 set of builtin modules. In config.c you will add the module at two
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
171 places: near the start of the file there is a list of external
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
172 declarations for all init() routines. Add a line of the form
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
173 <CODE><PRE>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
174 extern void initinterslip();
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
175 </PRE></CODE>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
176 here. Further down the file there is an array that is initialized with
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
177 modulename/initfunction pairs. Add a line of the form
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
178 <CODE><PRE>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
179 {"interslip", initinterslip},
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
180 </PRE></CODE>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
181 here. You may want to bracket these two lines with
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
182 <CODE><PRE>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
183 #ifdef USE_INTERSLIP
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
184 #endif
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
185 </PRE></CODE>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
186 lines, that way you can easily control whether the module is
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
187 incorporated into python at compile time. If you decide to do the
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
188 latter edit your config file (you can find the name in the "C/C++
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
189 language" section of the MW preferences dialog, it will probably be
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
190 "mwerks_nonshared_config.h") and add a
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
191 <CODE><PRE>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
192 #define USE_INTERSLIP
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
193 </PRE></CODE>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
194
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
195 Make the new interpreter and check that you can import the module, see
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
196 the methods (with "dir(interslip)") and call them. <p>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
197
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
198 <H2>Creating a PowerPC plugin module</H2>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
199
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
200 For PowerPC development you could follow the same path, but it is
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
201 actually a better idea to use a dynamically loadable module. The
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
202 advantage of dynamically loadable modules is that they are not loaded
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
203 until a python program actually uses them (resulting in less memory
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
204 usage by the interpreter) and that development is a lot simpler (since
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
205 your projects will all be smaller). Moreover, you can distribute a
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
206 plugin module by itself without haveing to distribute a complete
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
207 python interpreter. <p>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
208
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
209 Go to the "PlugIns" folder and copy the files xxmodule.µ,
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
210 xxmodule_config.h and xxmodule.µ.exp to interslipmodule.µ,
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
211 interslipmodule_config.h and interslipmodule.µ.exp, respectively. Edit
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
212 interslipmodule.µ.exp and change the name of the exported routine
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
213 "initxx" to "initinterslip". Open interslipmodule.µ with CodeWarrior,
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
214 remove the file xxmodule.c and add interslipmodule.c and make a number
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
215 of adjustments to the preferences:
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
216 <UL>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
217 <LI> in C/C++ language, set the header file to interslipmodule_config.h
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
218 <LI> in PPC linker, set the entry point to "initinterslip"
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
219 <LI> in PPC PEF, set the fragment name to "interslipmodule"
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
220 <LI> in PPC Project, set the output file name to "interslipmodule.slb".
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
221 </UL>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
222 Next, compile and link your module, fire up python and do the same
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
223 tests as for 68K python. <p>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
224
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
225 <H2>Getting the module to do real work</H2>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
226
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
227 So far, so good. In half an hour or so we have created a complete new
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
228 extension module for Python. The downside, however, is that the module
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
229 does not do anything useful. So, in the next half hour we will turn
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
230 our beautiful skeleton module into something that is at least as
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
231 beautiful but also gets some serious work done. For this once,
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
232 <EM>I</EM> have spent that half hour for you, and you can see the
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
233 results in <A
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
234 HREF="interslip/interslipmodule.c">interslipmodule.c</A>. <p>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
235
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
236 We add
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
237 <CODE><PRE>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
238 #include "InterslipLib.h"
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
239 #include "macglue.h"
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
240 </PRE></CODE>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
241 to the top of the file, and work our way through each of the methods
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
242 to add the functionality needed. Starting with open, we fill in the
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
243 template docstring, the value accessible from Python by looking at
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
244 <CODE>interslip.open.__doc__</CODE>. There are not many tools using
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
245 this information at the moment, but as soon as class browsers for
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
246 python become available having this minimal documentation available is
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
247 a good idea. We put "Load the interslip driver" as the comment
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
248 here. <p>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
249
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
250 Next, we tackle the body of <CODE>pyis_open()</CODE>. Since it has no
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
251 arguments and no return value we don't need to mess with that, we just
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
252 have to add a call to <CODE>is_open()</CODE> and check the return for
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
253 an error code, in which case we raise an error:
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
254 <CODE><PRE>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
255 err = is_open();
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
256 if ( err ) {
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
257 PyErr_Mac(ErrorObject, err);
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
258 return NULL;
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
259 }
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
260 </PRE></CODE>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
261 The routine <CODE><A NAME="PyErr_Mac">PyErr_Mac()</A></CODE> is a
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
262 useful routine that raises the exception passed as its first
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
263 argument. The data passed with the exception is based on the standard
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
264 MacOS error code given, and PyErr_Mac() attempts to locate a textual
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
265 description of the error code (which sure beats the "error -14021"
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
266 messages that so many macintosh applications tell their poor
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
267 users). <p>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
268
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
269 We will skip pyis_connect and pyis_disconnect here, which are pretty
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
270 much identical to pyis_open: no arguments, no return value, just a
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
271 call and an error check. With pyis_status() things get interesting
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
272 again: this call still takes 3 arguments, and all happen to be values
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
273 returned (a numeric connection status indicator, a message sequence
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
274 number and a pointer to the message itself, in MacOS pascal-style
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
275 string form). We declare variables to receive the returned values, do
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
276 the call, check the error and format the return value. <p>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
277
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
278 Building the return value is done using <CODE><A
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
279 NAME="Py_BuildValue">Py_BuildValue</A></CODE>:
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
280 <CODE><PRE>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
281 return Py_BuildValue("iiO&", (int)status, (int)seqnum, PyMac_BuildStr255, message);
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
282 </PRE></CODE>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
283 Py_BuildValue() is a very handy routine that builds tuples according
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
284 to a format string, somewhat similar to the way <CODE>printf()</CODE>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
285 works. The format string specifies the arguments expected after the
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
286 string, and turns them from C objects into python objects. The
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
287 resulting objects are put in a python tuple object and returned. The
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
288 "i" format specifier signifies an "int" (hence the cast: status and
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
289 seqnum are declared as "long", which is what the is_status() routine
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
290 wants, and even though we use a 4-byte project there is really no
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
291 reason not to put the cast here). Py_BuildValue and its counterpart
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
292 Py_ParseTuple have format codes for all the common C types like ints,
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
293 shorts, C-strings, floats, etc. Also, there is a nifty escape
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
294 mechanism to format values about which is does not know. This is
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
295 invoked by the "O&" format: it expects two arguments, a routine
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
296 pointer and an int-sized data object. The routine is called with the
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
297 object as a parameter and it should return a python objects
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
298 representing the data. <CODE>Macglue.h</CODE> declares a number of
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
299 such formatting routines for common MacOS objects like Str255, FSSpec,
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
300 OSType, Rect, etc. See the comments in the include file for
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
301 details. <p>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
302
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
303 <CODE>Pyis_getconfig()</CODE> is again similar to pyis_getstatus, only
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
304 two minor points are worth noting here. First, the C API return the
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
305 input and output baudrate squashed together into a single 4-byte
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
306 long. We separate them out before returning the result to
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
307 python. Second, whereas the status call returned us a pointer to a
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
308 <CODE>Str255</CODE> it kept we are responsible for allocating the
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
309 <CODE>Str255</CODE> for getconfig. This is something that would have
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
310 been easy to get wrong had we not used prototypes everywhere. Morale:
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
311 always try to include the header files for interfaces to libraries and
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
312 other stuff, so that the compiler can catch any mistakes you make. <p>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
313
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
314 <CODE>Pyis_setconfig()</CODE> finally shows off
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
315 <CODE>Py_ParseTuple</CODE>, the companion function to
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
316 <CODE>Py_BuildValue</CODE>. You pass it the argument tuple "args"
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
317 that your method gets as its second argument, a format string and
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
318 pointers to where you want the arguments stored. Again, standard C
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
319 types such as strings and integers Py_ParseTuple knows all about and
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
320 through the "O&" format you can extend the functionality. For each
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
321 "O&" you pass a function pointer and a pointer to a data area. The
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
322 function will be called with a PyObject pointer and your data pointer
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
323 and it should convert the python object to the correct C type. It
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
324 should return 1 on success and 0 on failure. Again, a number of
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
325 converters for standard MacOS types are provided, and declared in
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
326 <CODE>macglue.h</CODE>. <p>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
327
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
328 Next in our source file comes the method table for our module, which
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
329 has been generated by modulator (and it did a good job too!), but
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
330 which is worth looking at for a moment. Entries are of the form
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
331 <CODE><PRE>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
332 {"open", pyis_open, 1, pyis_open__doc__},
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
333 </PRE></CODE>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
334 where the entries are python method name, C routine pointer, flags and
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
335 docstring pointer. The value to note is the 1 for the flags: this
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
336 signifies that you want to use "new-style" Py_ParseTuple behaviour. If
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
337 you are writing a new module always use this, but if you are modifying
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
338 old code which calls something like <CODE>getargs(args, "(ii)",
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
339 ...)</CODE> you will have to put zero here. See "extending and
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
340 embedding" or possibly the getargs.c source file for details if you
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
341 need them. <p>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
342
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
343 Finally, we add some code to the init module, to put some symbolic
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
344 constants (codes that can by returned by the status method) in the
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
345 module dictionary, so the python program can use "interslip.RUN"
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
346 instead of the cryptic "4" when it wants to check that the interslip
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
347 driver is in RUN state. Modulator has already generated code to get at
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
348 the module dictionary using PyModule_GetDict() to store the exception
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
349 object, so we simply call
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
350 <CODE><PRE>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
351 PyDict_SetItemString(d, "IDLE", PyInt_FromLong(IS_IDLE));
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
352 </PRE></CODE>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
353 for each of our items. Since the last bit of code in our init routine
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
354 checks for previous errors with <CODE>PyErr_Occurred()</CODE> and
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
355 since <CODE>PyDict_SetItemString()</CODE> gracefully handles the case
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
356 of <CODE>NULL</CODE> parameters (if <CODE>PyInt_FromLong()</CODE>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
357 failed, for instance) we don't have to do error checking here. In some
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
358 other cases you may have to do error checking yourself. <p>
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
359
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
360 This concludes our crash-course on writing Python extensions in C on
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
361 the Macintosh. If you are not done reading yet I suggest you look
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
362 back at the <A HREF="index.html">MacPython Crashcourse index</A> to
a71d2fd90fa8 Explanations of the examples here
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
363 find another topic to study. <p>