blob: 38d3ad6381e4a1c68ec5145b5394cc49fc8f7ea8 [file] [log] [blame]
Guido van Rossumbcf08541995-02-05 16:52:24 +00001BGEN -- An Experiment: Automatic Generation of Extension Modules
2================================================================
3
4This directory contains BGEN -- a package that helps in generating
5complete source code for Python extension module. It currently also
6contains a set of examples that were generated with BGEN. These
7examples are mostly interfaces to a number of important managers in
8the Macintosh toolbox.
9
10
11Overview of Subdirectories
12--------------------------
13
14Main subdirectories:
15
16bgen the code generator package
17
18Example subdirectories:
19
20ae AppleEvents
21ctl Controls
Jack Jansen0a54ae21995-12-09 14:02:10 +000022cm Component manager
Guido van Rossumbcf08541995-02-05 16:52:24 +000023dlg Dialogs
24evt Events
25menu Menus
Jack Jansenec380101995-08-14 11:55:07 +000026list Lists
Guido van Rossumbcf08541995-02-05 16:52:24 +000027qd QuickDraw
Jack Jansen0a54ae21995-12-09 14:02:10 +000028qt QuickTime
Guido van Rossumbcf08541995-02-05 16:52:24 +000029res Resources
30snd Sound
31win Windows
32
33
34Contents of Subdirectories
35--------------------------
36
37The contents of each example subdirectory is similar (<Foobar> is
38for instance AppleEvents, while <foo> is ae):
39
40<foo>scan.py Scan the <Foobar>.h header, generating <foo>gen.py
41<foo>gen.py Output of <foo>scan.py, input for <foo>support.py
42<foo>edit.py Manually written complement of <foo>gen.py, sometimes
43<foo>support.py Generate <Foo>module.c from <foo>gen.py and <foo>edit.py
44<Foo>module.c The interface module, ready to be compiled
45<Foobar>.py Symbolic constants extracted from <Foobar.h>
46
47
48Tests and Examples
49------------------
50
51Other files in these subdirectories are usually examples using the
52extension. If there's a file t<foo>.py, it usually is a really
53boring test program.
54
55Some test programs contain pathnames that should be edited before
56trying them.
57
58Some of the less boring tests and examples:
59
60At the top level:
61
62test.py Application mainloop, uses most Mac extensions
63
64In ae:
65
66aetools.py Conversions between AE and Python data type
67echo.py Dummy AE server, echoes all data back
68tell.py Primitive AE client
69aete.py Decode 'aete' and 'aeut' resources (incomplete)
Jack Jansenec380101995-08-14 11:55:07 +000070gensuitemodule.py
71 Read aete/aeut resources and turn them into python
72 modules. The *_Suite.py modules have been generated
73 with this.
74AEservertest.py A simple AE server, similar to echo but different.
Jack Jansen0a54ae21995-12-09 14:02:10 +000075
76In cm:
77cmtest.py List all components in the system plus some info on them
78
79In qt:
80MovieInWindow.py Play a movie in a fixed-sized window, stop on mouse-press
81VerySimplePlayer.py Play a movie with the standard quicktime controller.
Guido van Rossumbcf08541995-02-05 16:52:24 +000082
83In res:
84
85listres.py List *all* resources in current and in all res files
86copyres.py Copy a resource file
87mkerrstrres.py Read "errors.txt" and create a set of "Estr" resources
88
89In snd:
90
91playaiff.py Play an AIFF file
92morse.py Turn text into Morse code
93audiodev.py The standard audiodev.py extended with Mac support
94Audio_mac.py The Mac support for audiodev.py
Jack Jansenec380101995-08-14 11:55:07 +000095
96
97Creating new Macintosh interfaces
98---------------------------------
99
100These instructions were written up by Jack while he was building the
101interface to Lists.h, the macintosh list manager. they may or may not
102have a more global scope than exactly that.
103
104First, start by copying ...scan.py and ...support.py from another,
105preferrably similar type. I started with evt, but that was a mistake
106since evt has no "own" object. Ctl or Dlg would probably have been a
107better idea.
108
109Now, the first thing to do is to comment out the blacklisted types and
110functions and the transformation rules for arguments, we'll fill those
111in lateron. Also, change the various definitions at the top, so that
112the right include file is parsed, and the .py files are generated with
113the correct name. If your manager has a type that will be implemented
114as a python object you may as well now change the destination() method
115to recognize that. (List was funny in this respect, since it has the
116list as the last argument in stead of the first).
117
118Now run your scanner. This will probably go fine until it tries to
119execute the generated code in the ...gen.py module. Look at that file,
120it will have formalized "definitions" of all the functions and methods
121that will be generated. Look at them all (with the documentation of the
122manager you're implementing in hand). Now you'll have to fix the
123blacklists and the repair instructions. This is sort of a black art,
124but a few guidelines may be handy here:
125- If there are argument types you cannot implement (or want to leave for
126 the moment) put them in blacklisttypes. Complex structures come to
127 mind, or routine pointers/UPP's. You will probably also want to
128 blacklist the routine that disposes of your object (since you'll do
129 that in the python destruction routine).
130- Various types of buffers are available in bgenBuffer, bgenHeapBuffer
131 and macsupport in the bgen directory. These'll let you handle all
132 sorts of input and output parameters. You can put instructions in the
133 repair list to let the C-arguments be handled by the correct type
134 of buffer. Check the other bgen-generated modules for using this for
135 passing raw structures and input and output buffers.
136- It appears that the parser usually guesses correctly whether a parameter
137 is meant for input or output. But, check the routines to be sure.
138- Some types are pretty hard to handle but you need the functionality
139 the a routine that uses them anyway. Various routines expecting ProcPtrs
140 or RegionHandles come to mind. Often, you can use the FakeType class
141 to provide a sensible default (i.e. NULL or a pointer to a routine you
142 coded in C, or a region specifying "the whole window"). This way, python
143 programmers won't get the full functionality but at least they'll get the
144 common case. You put the FakeType stuff in ...support.py.
145
146Next you'll probably have to write the code to implement your object.
147This will probably be a subclass of GlobalObjectDefinition. This goes
148into ...support.py. Also, some types used by the manager may look
149enough like standard types that you can equate them here (there are a
150lot of 2-integer structures that look remarkably like a Point, for
151instance).
152
153You'll also have to define the Function() and Method() classes. The
154OSErrFunctionGenerator and its method-counterpart are particularly
155handy for a lot of mac managers.
156
157Finally, you'll have to try and compile your resulting C-source, and go
158through the steps above until it works. For tlist.py, the test program
159for list, I started with the application framework. This is probably a
160good idea for any manager that does something to the display, since
161ApplicationFramework takes care of all the intricacies of event
162handling and decoding (up to a point).
163