CodeGen(3) User Contributed Perl Documentation CodeGen(3)NAMEGtk2::CodeGen - code generation utilities for Glib-based bindings.
SYNOPSIS
# usually in Makefile.PL
use Gtk2::CodeGen;
# most common, use all defaults
Gtk2::CodeGen->parse_maps ('myprefix');
Gtk2::CodeGen->write_boot;
# more exotic, change everything
Gtk2::CodeGen->parse_maps ('foo',
input => 'foo.maps',
header => 'foo-autogen.h',
typemap => 'foo.typemap',
register => 'register-foo.xsh');
Gtk2::CodeGen->write_boot (filename => 'bootfoo.xsh',
glob => 'Foo*.xs',
ignore => '^(Foo|Foo::Bar)$');
DESCRIPTION
This module packages some of the boilerplate code needed for performing
code generation typically used by perl bindings for gobject-based
libraries, using the Glib module as a base.
The default output filenames are in the subdirectory 'build', which
usually will be present if you are using ExtUtils::Depends (as most
Glib-based extensions probably should).
METHODS
Gtk2::CodeGen->write_boot;
Gtk2::CodeGen->write_boot (KEY => VAL, ...)
Many GObject-based libraries to be bound to perl will be too large
to put in a single XS file; however, a single PM file typically
only bootstraps one XS file's code. "write_boot" generates an XSH
file to be included from the BOOT section of that one bootstrapped
module, calling the boot code for all the other XS files in the
project.
Options are passed to the function in a set of key/val pairs, and
all options may default.
filename the name of the output file to be created.
the default is 'build/boot.xsh'.
glob a glob pattern that specifies the names of
the xs files to scan for MODULE lines.
the default is 'xs/*.xs'.
xs_files use this to supply an explicit list of file
names (as an array reference) to use instead
of a glob pattern. the default is to use
the glob pattern.
ignore regular expression matching any and all
module names which should be ignored, i.e.
NOT included in the list of symbols to boot.
this parameter is extremely important for
avoiding infinite loops at startup; see the
discussion for an explanation and rationale.
the default is '^[^:]+$', or, any name that
contains no colons, i.e., any toplevel
package name.
This function performs a glob (using perl's builtin glob operator)
on the pattern specified by the 'glob' option to retrieve a list of
file names. It then scans each file in that list for lines
matching the pattern "^MODULE" -- that is, the MODULE directive in
an XS file. The module name is pulled out and matched against the
regular expression specified by the ignore parameter. If this
module is not to be ignored, we next check to see if the name has
been seen. If not, the name will be converted to a boot symbol
(basically, s/:/_/ and prepend "boot_") and this symbol will be
added to a call to GPERL_CALL_BOOT in the generated file; it is
then marked as seen so we don't call it again.
What is this all about, you ask? In order to bind an XSub to perl,
the C function must be registered with the interpreter. This is
the function of the "boot" code, which is typically called in the
bootstrapping process. However, when multiple XS files are used
with only one PM file, some other mechanism must call the boot code
from each XS file before any of the function therein will be
available.
A typical setup for a multiple-XS, single-PM module will be to call
the various bits of boot code from the BOOT: section of the
toplevel module's XS file.
To use Gtk2 as an example, when you do 'use Gtk2', Gtk2.pm calls
bootstrap on Gtk2, which calls the C function boot_Gtk2. This
function calls the boot symbols for all the other xs files in the
module. The distinction is that the toplevel module, Gtk2, has no
colons in its name.
"xsubpp" generates the boot function's name by replacing the colons
in the MODULE name with underscores and prepending "boot_". We
need to be careful not to include the boot code for the
bootstrapped module, (say Toplevel, or Gtk2, or whatever) because
the bootstrap code in Toplevel.pm will call boot_Toplevel when
loaded, and boot_Toplevel should actually include the file we are
creating here.
The default value for the ignore parameter ignores any name not
containing colons, because it is assumed that this will be a
toplevel module, and any other packages/modules it boots will be
below this namespace, i.e., they will contain colons. This
assumption holds true for Gtk2 and Gnome2, but obviously fails for
something like Gnome2::Canvas. To boot that module properly, you
must use a regular expression such as "^Gnome2::Canvas$".
Note that you can, of course, match more than just one name, e.g.
"^(Foo|Foo::Bar)$", if you wanted to have Foo::Bar be included in
the same dynamically loaded object but only be booted when
absolutely necessary. (If you get that to work, more power to
you.)
Also, since this code scans for ^MODULE, you must comment the
MODULE section out with leading # marks if you want to hide it from
"write_boot".
Gtk2::CodeGen->parse_maps (PREFIX, [KEY => VAL, ...])
Convention within Glib/Gtk2 and friends is to use preprocessor
macros in the style of SvMyType and newSVMyType to get values in
and out of perl, and to use those same macros from both hand-
written code as well as the typemaps. However, if you have a lot
of types in your library (such as the nearly 200 types in Gtk+
2.x), then writing those macros becomes incredibly tedious,
especially so when you factor in all of the variants and such.
So, this function can turn a flat file containing terse
descriptions of the types into a header containing all the cast
macros, a typemap file using them, and an XSH file containing the
proper code to register each of those types (to be included by your
module's BOOT code).
The PREFIX is mandatory, and is used in some of the resulting
filenames, You can also override the defaults by providing key=>val
pairs:
input input file name. default is 'maps'. if this
key's value is an array reference, all the
filenames in the array will be scanned.
header name of the header file to create, default is
build/$prefix-autogen.h
typemap name of the typemap file to create, default is
build/$prefix.typemap
register name of the xsh file to contain all of the
type registrations, default is build/register.xsh
the maps file is a table of type descriptions, one per line, with
fields separated by whitespace. the fields should be:
TYPE macro e.g., GTK_TYPE_WIDGET
class name e.g. GtkWidget, name of the C type
base type one of GObject, GBoxed, GEnum, GFlags.
GtkObject is also supported, but the
distinction is no longer necessary as
of Glib 0.26.
package name of the perl package to which this
class name should be mapped, e.g.
Gtk2::Widget
As a special case, you can also use this same format to register
error domains; in this case two of the four columns take on
slightly different meanings:
domain macro e.g., GDK_PIXBUF_ERROR
enum type macro e.g., GDK_TYPE_PIXBUF_ERROR
base type GError
package name of the Perl package to which this
class name should be mapped, e.g.,
Gtk2::Gdk::Pixbuf::Error.
Gtk2::CodeGen->generate_constants_wrappers (KEY => VAL, ...)
Generates an XS file with XSUB wrappers for C constants. The key-
value pairs may contain one or more of the following keys:
prefix: Specifies the package name the functions should be put
into.
lists: Reference to an array of filenames which specify the
constants that should be wrapped.
xs_file: The name of the XS file that should be created.
header: The name of the header file that should be included in the
generated XS file.
export_tag: The name of the Exporter tag that should be used for
the constants wrappers.
All of the keys have mostly sane defaults.
Don't forget to add the generated XS file to the list of XS files
to be compiled.
The lists describing the constants to be wrapped should have the
following format:
CONSTANT_NAME [ \t+ CONSTANT_CONVERTER ]
That is, the constant's name optionally followed by a tab and the
converter that is to be used to convert the constant to a Perl
scalar. If CONSTANT_CONVERTER is a simple string like 'newSViv' it
will be used as follows to get a Perl scalar: CONSTANT_CONVERTER
(CONSTANT_NAME). If it contains '$var', as in 'newSVpv ($var,
PL_na)', then '$var' will be replaced with CONSTANT_NAME and the
resulting string will be used for conversion.
The default for CONSTANT_CONVERTER is 'newSViv'.
SEE ALSO
Glib::CodeGen does the actual work; Gtk2::CodeGen is now just a wrapper
which adds support for gtk-specific types.
AUTHOR
muppet <scott at asofyet dot org>
COPYRIGHT
Copyright (C) 2003-2005 by the gtk2-perl team (see the file AUTHORS for
the full list)
This library is free software; you can redistribute it and/or modify it
under the terms of the GNU Library General Public License as published
by the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
This library is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Library General Public License for more details.
You should have received a copy of the GNU Library General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307
USA.
perl v5.14.1 2011-08-02 CodeGen(3)