1CodeGen(3) User Contributed Perl Documentation CodeGen(3)
2
6 Gtk2::CodeGen - code generation utilities for Glib-based bindings.
7
9 # usually in Makefile.PL
10 use Gtk2::CodeGen;
11 # most common, use all defaults
13 Gtk2::CodeGen->parse_maps ('myprefix');
14 Gtk2::CodeGen->write_boot;
15 # more exotic, change everything
17 Gtk2::CodeGen->parse_maps ('foo',
18 input => 'foo.maps',
19 header => 'foo-autogen.h',
20 typemap => 'foo.typemap',
21 register => 'register-foo.xsh');
22 Gtk2::CodeGen->write_boot (filename => 'bootfoo.xsh',
23 glob => 'Foo*.xs',
24 ignore => '^(Foo⎪Foo::Bar)$');
25
27 This module packages some of the boilerplate code needed for performing
28 code generation typically used by perl bindings for gobject-based
29 libraries, using the Glib module as a base.
30 The default output filenames are in the subdirectory 'build', which
32 usually will be present if you are using ExtUtils::Depends (as most
33 Glib-based extensions probably should).
34 METHODS
36 Gtk2::CodeGen->write_boot;
38 Gtk2::CodeGen->write_boot (KEY => VAL, ...)
39 Many GObject-based libraries to be bound to perl will be too large
40 to put in a single XS file; however, a single PM file typically
41 only bootstraps one XS file's code. "write_boot" generates an XSH
42 file to be included from the BOOT section of that one bootstrapped
43 module, calling the boot code for all the other XS files in the
44 project.
45 Options are passed to the function in a set of key/val pairs, and
47 all options may default.
48 filename the name of the output file to be created.
50 the default is 'build/boot.xsh'.
51 glob a glob pattern that specifies the names of
53 the xs files to scan for MODULE lines.
54 the default is 'xs/*.xs'.
55 xs_files use this to supply an explicit list of file
57 names (as an array reference) to use instead
58 of a glob pattern. the default is to use
59 the glob pattern.
60 ignore regular expression matching any and all
62 module names which should be ignored, i.e.
63 NOT included in the list of symbols to boot.
64 this parameter is extremely important for
65 avoiding infinite loops at startup; see the
66 discussion for an explanation and rationale.
67 the default is '^[^:]+$', or, any name that
68 contains no colons, i.e., any toplevel
69 package name.
70 This function performs a glob (using perl's builtin glob operator)
72 on the pattern specified by the 'glob' option to retrieve a list of
73 file names. It then scans each file in that list for lines match‐
74 ing the pattern "^MODULE" -- that is, the MODULE directive in an XS
75 file. The module name is pulled out and matched against the regu‐
76 lar expression specified by the ignore parameter. If this module
77 is not to be ignored, we next check to see if the name has been
78 seen. If not, the name will be converted to a boot symbol (basi‐
79 cally, s/:/_/ and prepend "boot_") and this symbol will be added to
80 a call to GPERL_CALL_BOOT in the generated file; it is then marked
81 as seen so we don't call it again.
82 What is this all about, you ask? In order to bind an XSub to perl,
84 the C function must be registered with the interpreter. This is
85 the function of the "boot" code, which is typically called in the
86 bootstrapping process. However, when multiple XS files are used
87 with only one PM file, some other mechanism must call the boot code
88 from each XS file before any of the function therein will be avail‐
89 able.
90 A typical setup for a multiple-XS, single-PM module will be to call
92 the various bits of boot code from the BOOT: section of the
93 toplevel module's XS file.
94 To use Gtk2 as an example, when you do 'use Gtk2', Gtk2.pm calls
96 bootstrap on Gtk2, which calls the C function boot_Gtk2. This
97 function calls the boot symbols for all the other xs files in the
98 module. The distinction is that the toplevel module, Gtk2, has no
99 colons in its name.
100 "xsubpp" generates the boot function's name by replacing the colons
102 in the MODULE name with underscores and prepending "boot_". We
103 need to be careful not to include the boot code for the boot‐
104 strapped module, (say Toplevel, or Gtk2, or whatever) because the
105 bootstrap code in Toplevel.pm will call boot_Toplevel when loaded,
106 and boot_Toplevel should actually include the file we are creating
107 here.
108 The default value for the ignore parameter ignores any name not
110 containing colons, because it is assumed that this will be a
111 toplevel module, and any other packages/modules it boots will be
112 below this namespace, i.e., they will contain colons. This assump‐
113 tion holds true for Gtk2 and Gnome2, but obviously fails for some‐
114 thing like Gnome2::Canvas. To boot that module properly, you must
115 use a regular expression such as "^Gnome2::Canvas$".
116 Note that you can, of course, match more than just one name, e.g.
118 "^(Foo⎪Foo::Bar)$", if you wanted to have Foo::Bar be included in
119 the same dynamically loaded object but only be booted when abso‐
120 lutely necessary. (If you get that to work, more power to you.)
121 Also, since this code scans for ^MODULE, you must comment the MOD‐
123 ULE section out with leading # marks if you want to hide it from
124 "write_boot".
125 Gtk2::CodeGen->parse_maps (PREFIX, [KEY => VAL, ...])
127 Convention within Glib/Gtk2 and friends is to use preprocessor
128 macros in the style of SvMyType and newSVMyType to get values in
129 and out of perl, and to use those same macros from both hand-writ‐
130 ten code as well as the typemaps. However, if you have a lot of
131 types in your library (such as the nearly 200 types in Gtk+ 2.x),
132 then writing those macros becomes incredibly tedious, especially so
133 when you factor in all of the variants and such.
134 So, this function can turn a flat file containing terse descrip‐
136 tions of the types into a header containing all the cast macros, a
137 typemap file using them, and an XSH file containing the proper code
138 to register each of those types (to be included by your module's
139 BOOT code).
140 The PREFIX is mandatory, and is used in some of the resulting file‐
142 names, You can also override the defaults by providing key=>val
143 pairs:
144 input input file name. default is 'maps'. if this
146 key's value is an array reference, all the
147 filenames in the array will be scanned.
148 header name of the header file to create, default is
149 build/$prefix-autogen.h
150 typemap name of the typemap file to create, default is
151 build/$prefix.typemap
152 register name of the xsh file to contain all of the
153 type registrations, default is build/register.xsh
154 the maps file is a table of type descriptions, one per line, with
156 fields separated by whitespace. the fields should be:
157 TYPE macro e.g., GTK_TYPE_WIDGET
159 class name e.g. GtkWidget, name of the C type
160 base type one of GObject, GBoxed, GEnum, GFlags.
161 GtkObject is also supported, but the
162 distinction is no longer necessary as
163 of Glib 0.26.
164 package name of the perl package to which this
165 class name should be mapped, e.g.
166 Gtk2::Widget
167 As a special case, you can also use this same format to register
169 error domains; in this case two of the four columns take on
170 slightly different meanings:
171 domain macro e.g., GDK_PIXBUF_ERROR
173 enum type macro e.g., GDK_TYPE_PIXBUF_ERROR
174 base type GError
175 package name of the Perl package to which this
176 class name should be mapped, e.g.,
177 Gtk2::Gdk::Pixbuf::Error.
178
180 Glib::CodeGen does the actual work; Gtk2::CodeGen is now just a wrapper
181 which adds support for gtk-specific types.
182
184 muppet <scott at asofyet dot org>
185
187 Copyright (C) 2003-2005 by the gtk2-perl team (see the file AUTHORS for
188 the full list)
189 This library is free software; you can redistribute it and/or modify it
191 under the terms of the GNU Library General Public License as published
192 by the Free Software Foundation; either version 2.1 of the License, or
193 (at your option) any later version.
194 This library is distributed in the hope that it will be useful, but
196 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
197 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library
198 General Public License for more details.
199 You should have received a copy of the GNU Library General Public
201 License along with this library; if not, write to the Free Software
202 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307
203 USA.
204perl v5.8.8 2007-03-18 CodeGen(3)