|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 files 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.
This function performs a glob (using perls 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 dont 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 modules 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 functions 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 modules 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:
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:
|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:
All of the keys have mostly sane defaults.
Dont 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:
That is, the constants 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, 0), then $var will be replaced with CONSTANT_NAME and the resulting string will be used for conversion.
The default for CONSTANT_CONVERTER is newSViv.
Glib::CodeGen does the actual work; Gtk2::CodeGen is now just a wrapper which adds support for gtk-specific types.
muppet <scott at asofyet dot org>
Copyright (C) 2003-2005, 2013 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.20.3||GTK2::CODEGEN (3)||2013-09-29|