mirror of
https://github.com/python/cpython.git
synced 2025-10-11 01:12:48 +00:00
Removed most of the README text since it is all about the Mac specific
examples, which no longer live here.
This commit is contained in:
Guido van Rossum
parent
faefe4cb60
commit
814842f395
1 changed files with 5 additions and 161 deletions
|
|
@ -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
|
This directory contains BGEN -- a package that helps in generating
|
||||||
complete source code for Python extension module. It currently also
|
complete source code for Python extension module. For examples of its
|
||||||
contains a set of examples that were generated with BGEN. These
|
use, see the Mac Python source distribution (available separately
|
||||||
examples are mostly interfaces to a number of important managers in
|
from the Python ftp archives). Note that BGEN is not Mac specific!
|
||||||
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).
|
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue