112 lines
4.0 KiB
Plaintext
112 lines
4.0 KiB
Plaintext
Some mostly unfinished docs are here.
|
|
|
|
-Yosh
|
|
|
|
This document describes the tool PDBGEN.
|
|
|
|
If you added or modified .pdb files do not run this tool manually but
|
|
run make instead! It will call pdbgen.pl then to generate the files
|
|
into the right output directories.
|
|
|
|
PDBGEN
|
|
------------------
|
|
|
|
What is this?
|
|
PDBGEN is a tool to automate much of the drudge work of making PDB interfaces
|
|
to PIKA internals. Right now, it generates PDB description records,
|
|
argument marshallers (with sanity checking) for the app side, as well
|
|
as libpika wrappers for C plugins. It's written so that extending it
|
|
to provide support for CORBA and other languages suited to static
|
|
autogeneration.
|
|
|
|
Invoking PDBGEN from the command line:
|
|
1. Change into the ./pdb directory.
|
|
2. $ ./pdbgen.pl DIRNAME
|
|
where DIRNAME is either "lib" or "app", depending on which set of files
|
|
you want to generate. The files are written into $destdir/app or $destdir/libpika.
|
|
$destdir is the environment variable destdir. If it's not set,
|
|
then it's the ./pdb directory. Make sure the directories
|
|
$destdir/app and $destdir/libpika already exist and you have write permissions.
|
|
Otherwise the code generator will fail and exit.
|
|
It's up to you to diff the file you changed. When you're happy with
|
|
the generated file, copy it into the actual ./app/ or ./libpika/ directory
|
|
where it finally gets built.
|
|
|
|
Anatomy of a PDB descriptor:
|
|
PDB descriptors are Perl code. You define a subroutine, which corresponds
|
|
to the PDB function you want to create. You then fill certain special
|
|
variables to fully describe all the information pdbgen needs to generate
|
|
code. Since it's perl, you can do practically whatever perl lets you
|
|
do to help you do this. However, at the simplest level, you don't need
|
|
to know perl at all to make PDB descriptors.
|
|
|
|
Annotated description:
|
|
For example, we will look at pika_display_new, specified in gdisplay.pdb.
|
|
|
|
sub display_new {
|
|
|
|
We start with the name of our PDB function (not including the "pika_" prefix).
|
|
|
|
$blurb = 'Create a new display for the specified image.';
|
|
|
|
This directly corresponds to the "blurb" field in the ProcRecord.
|
|
|
|
$help = <<'HELP';
|
|
Creates a new display for the specified image. If the image already has a
|
|
display, another is added. Multiple displays are handled transparently by the
|
|
PIKA. The newly created display is returned and can be subsequently destroyed
|
|
with a call to 'pika-display-delete'. This procedure only makes sense for use
|
|
with the PIKA UI.
|
|
HELP
|
|
|
|
This is the help field. Notice because it is a long string, we used HERE
|
|
document syntax to split it over multiple lines. Any extra whitespace
|
|
in $blurb or $help, including newlines, is automatically stripped, so you
|
|
don't have to worry about that.
|
|
|
|
&std_pdb_misc;
|
|
|
|
This is the "author", "copyright", and "date" fields. Since S&P are quite
|
|
common, they get a special shortcut which fills these in for you. Stuff
|
|
like this is defined in stddefs.pdb.
|
|
|
|
@inargs = ( &std_image_arg );
|
|
|
|
You specify arguments in a list. Again, your basic image is very common,
|
|
so it gets a shortcut.
|
|
|
|
@outargs = (
|
|
{ name => 'display', type => 'display',
|
|
desc => 'The new display', alias => 'gdisp', init => 1 }
|
|
);
|
|
|
|
This is a real argument. It has a name, type, description at a minimum.
|
|
"alias" lets you use the alias name in your invoker code, but the real
|
|
name is still shown in the ProcRecord. This is useful not only as a
|
|
shorthand, but for grabbing variables defined somewhere else (or constants),
|
|
in conjunction with the "no_declare" flag. "init" simply says initialize
|
|
this variable to a dummy value (in this case to placate gcc warnings)
|
|
|
|
%invoke = (
|
|
headers => [ qw("gdisplay.h") ],
|
|
|
|
These are the headers needed for the functions you call.
|
|
|
|
vars => [ 'guint scale = 0x101' ],
|
|
|
|
Extra variables can be put here for your invoker.
|
|
|
|
code => <<'CODE'
|
|
{
|
|
if (gimage->layers == NULL)
|
|
success = FALSE;
|
|
else
|
|
success = ((gdisp = gdisplay_new (gimage, scale)) != NULL);
|
|
}
|
|
CODE
|
|
|
|
The actual invoker code. Since it's a multiline block, we put curly braces
|
|
in the beginning.
|
|
|
|
|
