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