Initial checkin of Pika from heckimp

pdb/README

@@ -0,0 +1,111 @@
+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.
+
+