Guido van Rossum | bcf0854 | 1995-02-05 16:52:24 +0000 | [diff] [blame] | 1 | BGEN -- An Experiment: Automatic Generation of Extension Modules |
| 2 | ================================================================ |
| 3 | |
| 4 | This directory contains BGEN -- a package that helps in generating |
| 5 | complete source code for Python extension module. It currently also |
| 6 | contains a set of examples that were generated with BGEN. These |
| 7 | examples are mostly interfaces to a number of important managers in |
| 8 | the Macintosh toolbox. |
| 9 | |
| 10 | |
| 11 | Overview of Subdirectories |
| 12 | -------------------------- |
| 13 | |
| 14 | Main subdirectories: |
| 15 | |
| 16 | bgen the code generator package |
| 17 | |
| 18 | Example subdirectories: |
| 19 | |
| 20 | ae AppleEvents |
| 21 | ctl Controls |
Jack Jansen | 0a54ae2 | 1995-12-09 14:02:10 +0000 | [diff] [blame] | 22 | cm Component manager |
Guido van Rossum | bcf0854 | 1995-02-05 16:52:24 +0000 | [diff] [blame] | 23 | dlg Dialogs |
| 24 | evt Events |
| 25 | menu Menus |
Jack Jansen | ec38010 | 1995-08-14 11:55:07 +0000 | [diff] [blame] | 26 | list Lists |
Guido van Rossum | bcf0854 | 1995-02-05 16:52:24 +0000 | [diff] [blame] | 27 | qd QuickDraw |
Jack Jansen | 0a54ae2 | 1995-12-09 14:02:10 +0000 | [diff] [blame] | 28 | qt QuickTime |
Guido van Rossum | bcf0854 | 1995-02-05 16:52:24 +0000 | [diff] [blame] | 29 | res Resources |
| 30 | snd Sound |
| 31 | win Windows |
| 32 | |
| 33 | |
| 34 | Contents of Subdirectories |
| 35 | -------------------------- |
| 36 | |
| 37 | The contents of each example subdirectory is similar (<Foobar> is |
| 38 | for 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 | |
| 48 | Tests and Examples |
| 49 | ------------------ |
| 50 | |
| 51 | Other files in these subdirectories are usually examples using the |
| 52 | extension. If there's a file t<foo>.py, it usually is a really |
| 53 | boring test program. |
| 54 | |
| 55 | Some test programs contain pathnames that should be edited before |
| 56 | trying them. |
| 57 | |
| 58 | Some of the less boring tests and examples: |
| 59 | |
| 60 | At the top level: |
| 61 | |
| 62 | test.py Application mainloop, uses most Mac extensions |
| 63 | |
| 64 | In ae: |
| 65 | |
| 66 | aetools.py Conversions between AE and Python data type |
| 67 | echo.py Dummy AE server, echoes all data back |
| 68 | tell.py Primitive AE client |
| 69 | aete.py Decode 'aete' and 'aeut' resources (incomplete) |
Jack Jansen | ec38010 | 1995-08-14 11:55:07 +0000 | [diff] [blame] | 70 | gensuitemodule.py |
| 71 | Read aete/aeut resources and turn them into python |
| 72 | modules. The *_Suite.py modules have been generated |
| 73 | with this. |
| 74 | AEservertest.py A simple AE server, similar to echo but different. |
Jack Jansen | 0a54ae2 | 1995-12-09 14:02:10 +0000 | [diff] [blame] | 75 | |
| 76 | In cm: |
| 77 | cmtest.py List all components in the system plus some info on them |
| 78 | |
| 79 | In qt: |
| 80 | MovieInWindow.py Play a movie in a fixed-sized window, stop on mouse-press |
| 81 | VerySimplePlayer.py Play a movie with the standard quicktime controller. |
Guido van Rossum | bcf0854 | 1995-02-05 16:52:24 +0000 | [diff] [blame] | 82 | |
| 83 | In res: |
| 84 | |
| 85 | listres.py List *all* resources in current and in all res files |
| 86 | copyres.py Copy a resource file |
| 87 | mkerrstrres.py Read "errors.txt" and create a set of "Estr" resources |
| 88 | |
| 89 | In snd: |
| 90 | |
| 91 | playaiff.py Play an AIFF file |
| 92 | morse.py Turn text into Morse code |
| 93 | audiodev.py The standard audiodev.py extended with Mac support |
| 94 | Audio_mac.py The Mac support for audiodev.py |
Jack Jansen | ec38010 | 1995-08-14 11:55:07 +0000 | [diff] [blame] | 95 | |
| 96 | |
| 97 | Creating new Macintosh interfaces |
| 98 | --------------------------------- |
| 99 | |
| 100 | These instructions were written up by Jack while he was building the |
| 101 | interface to Lists.h, the macintosh list manager. they may or may not |
| 102 | have a more global scope than exactly that. |
| 103 | |
| 104 | First, start by copying ...scan.py and ...support.py from another, |
| 105 | preferrably similar type. I started with evt, but that was a mistake |
| 106 | since evt has no "own" object. Ctl or Dlg would probably have been a |
| 107 | better idea. |
| 108 | |
| 109 | Now, the first thing to do is to comment out the blacklisted types and |
| 110 | functions and the transformation rules for arguments, we'll fill those |
| 111 | in lateron. Also, change the various definitions at the top, so that |
| 112 | the right include file is parsed, and the .py files are generated with |
| 113 | the correct name. If your manager has a type that will be implemented |
| 114 | as a python object you may as well now change the destination() method |
| 115 | to recognize that. (List was funny in this respect, since it has the |
| 116 | list as the last argument in stead of the first). |
| 117 | |
| 118 | Now run your scanner. This will probably go fine until it tries to |
| 119 | execute the generated code in the ...gen.py module. Look at that file, |
| 120 | it will have formalized "definitions" of all the functions and methods |
| 121 | that will be generated. Look at them all (with the documentation of the |
| 122 | manager you're implementing in hand). Now you'll have to fix the |
| 123 | blacklists and the repair instructions. This is sort of a black art, |
| 124 | but 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 | |
| 146 | Next you'll probably have to write the code to implement your object. |
| 147 | This will probably be a subclass of GlobalObjectDefinition. This goes |
| 148 | into ...support.py. Also, some types used by the manager may look |
| 149 | enough like standard types that you can equate them here (there are a |
| 150 | lot of 2-integer structures that look remarkably like a Point, for |
| 151 | instance). |
| 152 | |
| 153 | You'll also have to define the Function() and Method() classes. The |
| 154 | OSErrFunctionGenerator and its method-counterpart are particularly |
| 155 | handy for a lot of mac managers. |
| 156 | |
| 157 | Finally, you'll have to try and compile your resulting C-source, and go |
| 158 | through the steps above until it works. For tlist.py, the test program |
| 159 | for list, I started with the application framework. This is probably a |
| 160 | good idea for any manager that does something to the display, since |
| 161 | ApplicationFramework takes care of all the intricacies of event |
| 162 | handling and decoding (up to a point). |
| 163 | |