1CodeGen(3)            User Contributed Perl Documentation           CodeGen(3)
2
3
4

NAME

6       Glib::CodeGen - code generation utilities for Glib-based bindings.
7

SYNOPSIS

9        # usually in Makefile.PL
10        use Glib::CodeGen;
11
12        # most common, use all defaults
13        Glib::CodeGen->parse_maps ('myprefix');
14        Glib::CodeGen->write_boot;
15
16        # more exotic, change everything
17        Glib::CodeGen->parse_maps ('foo',
18                                   input => 'foo.maps',
19                                   header => 'foo-autogen.h',
20                                   typemap => 'foo.typemap',
21                                   register => 'register-foo.xsh');
22        Glib::CodeGen->write_boot (filename => 'bootfoo.xsh',
23                                   glob => 'Foo*.xs',
24                                   ignore => '^(Foo⎪Foo::Bar)$');
25
26        # add a custom type handler (rarely necessary)
27        Glib::CodeGen->add_type_handler (FooType => \&gen_foo_stuff);
28        # (see the section EXTENDING TYPE SUPPORT for more info.)
29

DESCRIPTION

31       This module packages some of the boilerplate code needed for performing
32       code generation typically used by perl bindings for gobject-based
33       libraries, using the Glib module as a base.
34
35       The default output filenames are in the subdirectory 'build', which
36       usually will be present if you are using ExtUtils::Depends (as most
37       Glib-based extensions probably should).
38
39       METHODS
40
41       Glib::CodeGen->write_boot;
42       Glib::CodeGen->write_boot (KEY => VAL, ...)
43           Many GObject-based libraries to be bound to perl will be too large
44           to put in a single XS file; however, a single PM file typically
45           only bootstraps one XS file's code.  "write_boot" generates an XSH
46           file to be included from the BOOT section of that one bootstrapped
47           module, calling the boot code for all the other XS files in the
48           project.
49
50           Options are passed to the function in a set of key/val pairs, and
51           all options may default.
52
53             filename     the name of the output file to be created.
54                          the default is 'build/boot.xsh'.
55
56             glob         a glob pattern that specifies the names of
57                          the xs files to scan for MODULE lines.
58                          the default is 'xs/*.xs'.
59
60             xs_files     use this to supply an explicit list of file
61                          names (as an array reference) to use instead
62                          of a glob pattern.  the default is to use
63                          the glob pattern.
64
65             ignore       regular expression matching any and all
66                          module names which should be ignored, i.e.
67                          NOT included in the list of symbols to boot.
68                          this parameter is extremely important for
69                          avoiding infinite loops at startup; see the
70                          discussion for an explanation and rationale.
71                          the default is '^[^:]+$', or, any name that
72                          contains no colons, i.e., any toplevel
73                          package name.
74
75           This function performs a glob (using perl's builtin glob operator)
76           on the pattern specified by the 'glob' option to retrieve a list of
77           file names.  It then scans each file in that list for lines match‐
78           ing the pattern "^MODULE" -- that is, the MODULE directive in an XS
79           file.  The module name is pulled out and matched against the regu‐
80           lar expression specified by the ignore parameter.  If this module
81           is not to be ignored, we next check to see if the name has been
82           seen.  If not, the name will be converted to a boot symbol (basi‐
83           cally, s/:/_/ and prepend "boot_") and this symbol will be added to
84           a call to GPERL_CALL_BOOT in the generated file; it is then marked
85           as seen so we don't call it again.
86
87           What is this all about, you ask?  In order to bind an XSub to perl,
88           the C function must be registered with the interpreter.  This is
89           the function of the "boot" code, which is typically called in the
90           bootstrapping process.  However, when multiple XS files are used
91           with only one PM file, some other mechanism must call the boot code
92           from each XS file before any of the function therein will be avail‐
93           able.
94
95           A typical setup for a multiple-XS, single-PM module will be to call
96           the various bits of boot code from the BOOT: section of the
97           toplevel module's XS file.
98
99           To use Gtk2 as an example, when you do 'use Gtk2', Gtk2.pm calls
100           bootstrap on Gtk2, which calls the C function boot_Gtk2.  This
101           function calls the boot symbols for all the other xs files in the
102           module.  The distinction is that the toplevel module, Gtk2, has no
103           colons in its name.
104
105           "xsubpp" generates the boot function's name by replacing the colons
106           in the MODULE name with underscores and prepending "boot_".  We
107           need to be careful not to include the boot code for the boot‐
108           strapped module, (say Toplevel, or Gtk2, or whatever) because the
109           bootstrap code in Toplevel.pm will call boot_Toplevel when loaded,
110           and boot_Toplevel should actually include the file we are creating
111           here.
112
113           The default value for the ignore parameter ignores any name not
114           containing colons, because it is assumed that this will be a
115           toplevel module, and any other packages/modules it boots will be
116           below this namespace, i.e., they will contain colons.  This assump‐
117           tion holds true for Gtk2 and Gnome2, but obviously fails for some‐
118           thing like Gnome2::Canvas.  To boot that module properly, you must
119           use a regular expression such as "^Gnome2::Canvas$".
120
121           Note that you can, of course, match more than just one name, e.g.
122           "^(Foo⎪Foo::Bar)$", if you wanted to have Foo::Bar be included in
123           the same dynamically loaded object but only be booted when abso‐
124           lutely necessary.  (If you get that to work, more power to you.)
125
126           Also, since this code scans for ^MODULE, you must comment the MOD‐
127           ULE section out with leading # marks if you want to hide it from
128           "write_boot".
129
130       Glib::CodeGen->parse_maps (PREFIX, [KEY => VAL, ...])
131           Convention within Glib/Gtk2 and friends is to use preprocessor
132           macros in the style of SvMyType and newSVMyType to get values in
133           and out of perl, and to use those same macros from both hand-writ‐
134           ten code as well as the typemaps.  However, if you have a lot of
135           types in your library (such as the nearly 200 types in Gtk+ 2.x),
136           then writing those macros becomes incredibly tedious, especially so
137           when you factor in all of the variants and such.
138
139           So, this function can turn a flat file containing terse descrip‐
140           tions of the types into a header containing all the cast macros, a
141           typemap file using them, and an XSH file containing the proper code
142           to register each of those types (to be included by your module's
143           BOOT code).
144
145           The PREFIX is mandatory, and is used in some of the resulting file‐
146           names, You can also override the defaults by providing key=>val
147           pairs:
148
149             input    input file name.  default is 'maps'.  if this
150                      key's value is an array reference, all the
151                      filenames in the array will be scanned.
152             header   name of the header file to create, default is
153                      build/$prefix-autogen.h
154             typemap  name of the typemap file to create, default is
155                      build/$prefix.typemap
156             register name of the xsh file to contain all of the
157                      type registrations, default is build/register.xsh
158
159           the maps file is a table of type descriptions, one per line, with
160           fields separated by whitespace.  the fields should be:
161
162             TYPE macro    e.g., GTK_TYPE_WIDGET
163             class name    e.g. GtkWidget, name of the C type
164             base type     one of GObject, GBoxed, GEnum, GFlags.
165                           To support other base types, see
166                           EXTENDING TYPE SUPPORT for info on
167                           on how to add a custom type handler.
168             package       name of the perl package to which this
169                           class name should be mapped, e.g.
170                           Gtk2::Widget
171
172           As a special case, you can also use this same format to register
173           error domains; in this case two of the four columns take on
174           slightly different meanings:
175
176             domain macro     e.g., GDK_PIXBUF_ERROR
177             enum type macro  e.g., GDK_TYPE_PIXBUF_ERROR
178             base type        GError
179             package          name of the Perl package to which this
180                              class name should be mapped, e.g.,
181                              Gtk2::Gdk::Pixbuf::Error.
182

EXTENDING TYPE SUPPORT

184       "parse_maps" uses the base type entry in each maps record to decide how
185       to generate output for that type.  In the base module, type support is
186       included for the base types provided by Glib.  It is easy to add sup‐
187       port for your own types, by merely adding a type handler.  This type
188       handler will call utility functions to add typemaps, BOOT lines, and
189       header lines.
190
191       Glib::CodeGen->add_type_handler ($base_type => $handler)
192           $base_type (string) C name of the base type to handle.
193           $handler (subroutine) Callback used to handle this type.
194
195           Use $handler to generate output for records whose base type is
196           $base_type.  $base_type is the C type name as found in the third
197           column of a maps file entry.
198
199           $handler will be called with the (possibly preprocessed) contents
200           of the current maps file record, and should call the "add_typemap",
201           "add_register", and "add_header" functions to set up the necessary
202           C/XS glue for that type.
203
204           For example:
205
206             Glib::CodeGen->add_type_handler (CoolThing => sub {
207                 my ($typemacro, $classname, $base, $package) = @_;
208
209                 # $typemacro is the C type macro, like COOL_TYPE_THING.
210                 # $classname is the actual C type name, like CoolFooThing.
211                 # $base is the C name of the base type.  If CoolFooThing
212                 #     isa CoolThing, $base will be CoolThing.  This
213                 #     parameter is useful when using the same type handler
214                 #     for multiple base types.
215                 # $package is the package name that corresponds to
216                 #     $classname, as specified in the maps file.
217
218                 ...
219             });
220
221       add_typemap $type, $typemap [, $input, $output]
222           Add a typemap entry for $type, named $typemap.  If $input and/or
223           $output are defined, their text will be used as the "INPUT" and/or
224           "OUTPUT" typemap implementations (respectively) for $typemap.  Note
225           that in general, you'll use "T_GPERL_GENERIC_WRAPPER" or some other
226           existing typemap for $typemap, so $input and $output are very
227           rarely used.
228
229           Example:
230
231             # map $classname pointers and all their variants to the generic
232             # wrapper typemap.
233             add_typemap "$classname *", "T_GPERL_GENERIC_WRAPPER";
234             add_typemap "const $classname *", "T_GPERL_GENERIC_WRAPPER";
235             add_typemap "$classname\_ornull *", "T_GPERL_GENERIC_WRAPPER";
236             add_typemap "const $classname\_ornull *", "T_GPERL_GENERIC_WRAPPER";
237             add_typemap "$classname\_own *", "T_GPERL_GENERIC_WRAPPER";
238             add_typemap "$classname\_copy *", "T_GPERL_GENERIC_WRAPPER";
239             add_typemap "$classname\_own_ornull *", "T_GPERL_GENERIC_WRAPPER";
240
241             # custom code for an int-like enum:
242             add_typemap $class => T_FOO,
243                         "\$var = foo_unwrap (\$arg);", # input
244                         "\$arg = foo_wrap (\$var);"; # output
245
246       add_register $text
247           Add $text to the generated "register.xsh".  This is usually used
248           for registering types with the bindings, e.g.:
249
250              add_register "#ifdef $typemacro\n"
251                     . "gperl_register_object ($typemacro, \"$package\");\n"
252                     . "#endif /* $typemacro */";
253
254       add_header $text
255           Add $text to the generated C header.  You'll put variant typedefs
256           and wrap/unwrap macros in the header, and will usually want to wrap
257           the declarations in "#ifdef $typemacro" for safety.
258

BUGS

260       GInterfaces are mostly just ignored.
261
262       The code is ugly.
263

AUTHOR

265       muppet <scott at asofyet dot org>
266
268       Copyright (C) 2003-2005 by the gtk2-perl team (see the file AUTHORS for
269       the full list)
270
271       This library is free software; you can redistribute it and/or modify it
272       under the terms of the GNU Library General Public License as published
273       by the Free Software Foundation; either version 2.1 of the License, or
274       (at your option) any later version.
275
276       This library is distributed in the hope that it will be useful, but
277       WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
278       CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library
279       General Public License for more details.
280
281       You should have received a copy of the GNU Library General Public
282       License along with this library; if not, write to the Free Software
283       Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307
284       USA.
285
286
287
288perl v5.8.8                       2007-02-26                        CodeGen(3)
Impressum