diff options
| -rw-r--r-- | Tools/bgen/README | 166 |
1 files changed, 5 insertions, 161 deletions
diff --git a/Tools/bgen/README b/Tools/bgen/README index 38d3ad6..70700c6 100644 --- a/Tools/bgen/README +++ b/Tools/bgen/README @@ -1,163 +1,7 @@ -BGEN -- An Experiment: Automatic Generation of Extension Modules -================================================================ +BGEN -- Automatic Generation of Extension Modules +================================================= This directory contains BGEN -- a package that helps in generating -complete source code for Python extension module. It currently also -contains a set of examples that were generated with BGEN. These -examples are mostly interfaces to a number of important managers in -the Macintosh toolbox. - - -Overview of Subdirectories --------------------------- - -Main subdirectories: - -bgen the code generator package - -Example subdirectories: - -ae AppleEvents -ctl Controls -cm Component manager -dlg Dialogs -evt Events -menu Menus -list Lists -qd QuickDraw -qt QuickTime -res Resources -snd Sound -win Windows - - -Contents of Subdirectories --------------------------- - -The contents of each example subdirectory is similar (<Foobar> is -for instance AppleEvents, while <foo> is ae): - -<foo>scan.py Scan the <Foobar>.h header, generating <foo>gen.py -<foo>gen.py Output of <foo>scan.py, input for <foo>support.py -<foo>edit.py Manually written complement of <foo>gen.py, sometimes -<foo>support.py Generate <Foo>module.c from <foo>gen.py and <foo>edit.py -<Foo>module.c The interface module, ready to be compiled -<Foobar>.py Symbolic constants extracted from <Foobar.h> - - -Tests and Examples ------------------- - -Other files in these subdirectories are usually examples using the -extension. If there's a file t<foo>.py, it usually is a really -boring test program. - -Some test programs contain pathnames that should be edited before -trying them. - -Some of the less boring tests and examples: - -At the top level: - -test.py Application mainloop, uses most Mac extensions - -In ae: - -aetools.py Conversions between AE and Python data type -echo.py Dummy AE server, echoes all data back -tell.py Primitive AE client -aete.py Decode 'aete' and 'aeut' resources (incomplete) -gensuitemodule.py - Read aete/aeut resources and turn them into python - modules. The *_Suite.py modules have been generated - with this. -AEservertest.py A simple AE server, similar to echo but different. - -In cm: -cmtest.py List all components in the system plus some info on them - -In qt: -MovieInWindow.py Play a movie in a fixed-sized window, stop on mouse-press -VerySimplePlayer.py Play a movie with the standard quicktime controller. - -In res: - -listres.py List *all* resources in current and in all res files -copyres.py Copy a resource file -mkerrstrres.py Read "errors.txt" and create a set of "Estr" resources - -In snd: - -playaiff.py Play an AIFF file -morse.py Turn text into Morse code -audiodev.py The standard audiodev.py extended with Mac support -Audio_mac.py The Mac support for audiodev.py - - -Creating new Macintosh interfaces ---------------------------------- - -These instructions were written up by Jack while he was building the -interface to Lists.h, the macintosh list manager. they may or may not -have a more global scope than exactly that. - -First, start by copying ...scan.py and ...support.py from another, -preferrably similar type. I started with evt, but that was a mistake -since evt has no "own" object. Ctl or Dlg would probably have been a -better idea. - -Now, the first thing to do is to comment out the blacklisted types and -functions and the transformation rules for arguments, we'll fill those -in lateron. Also, change the various definitions at the top, so that -the right include file is parsed, and the .py files are generated with -the correct name. If your manager has a type that will be implemented -as a python object you may as well now change the destination() method -to recognize that. (List was funny in this respect, since it has the -list as the last argument in stead of the first). - -Now run your scanner. This will probably go fine until it tries to -execute the generated code in the ...gen.py module. Look at that file, -it will have formalized "definitions" of all the functions and methods -that will be generated. Look at them all (with the documentation of the -manager you're implementing in hand). Now you'll have to fix the -blacklists and the repair instructions. This is sort of a black art, -but a few guidelines may be handy here: -- If there are argument types you cannot implement (or want to leave for - the moment) put them in blacklisttypes. Complex structures come to - mind, or routine pointers/UPP's. You will probably also want to - blacklist the routine that disposes of your object (since you'll do - that in the python destruction routine). -- Various types of buffers are available in bgenBuffer, bgenHeapBuffer - and macsupport in the bgen directory. These'll let you handle all - sorts of input and output parameters. You can put instructions in the - repair list to let the C-arguments be handled by the correct type - of buffer. Check the other bgen-generated modules for using this for - passing raw structures and input and output buffers. -- It appears that the parser usually guesses correctly whether a parameter - is meant for input or output. But, check the routines to be sure. -- Some types are pretty hard to handle but you need the functionality - the a routine that uses them anyway. Various routines expecting ProcPtrs - or RegionHandles come to mind. Often, you can use the FakeType class - to provide a sensible default (i.e. NULL or a pointer to a routine you - coded in C, or a region specifying "the whole window"). This way, python - programmers won't get the full functionality but at least they'll get the - common case. You put the FakeType stuff in ...support.py. - -Next you'll probably have to write the code to implement your object. -This will probably be a subclass of GlobalObjectDefinition. This goes -into ...support.py. Also, some types used by the manager may look -enough like standard types that you can equate them here (there are a -lot of 2-integer structures that look remarkably like a Point, for -instance). - -You'll also have to define the Function() and Method() classes. The -OSErrFunctionGenerator and its method-counterpart are particularly -handy for a lot of mac managers. - -Finally, you'll have to try and compile your resulting C-source, and go -through the steps above until it works. For tlist.py, the test program -for list, I started with the application framework. This is probably a -good idea for any manager that does something to the display, since -ApplicationFramework takes care of all the intricacies of event -handling and decoding (up to a point). - +complete source code for Python extension module. For examples of its +use, see the Mac Python source distribution (available separately +from the Python ftp archives). Note that BGEN is not Mac specific! |