1CodeGen(3) User Contributed Perl Documentation CodeGen(3)
2
6 Glib::CodeGen - code generation utilities for Glib-based bindings.
7
9 # usually in Makefile.PL
10 use Glib::CodeGen;
11 # most common, use all defaults
13 Glib::CodeGen->parse_maps ('myprefix');
14 Glib::CodeGen->write_boot;
15 # 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 # 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
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 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 METHODS
40 Glib::CodeGen->write_boot;
41 Glib::CodeGen->write_boot (KEY => VAL, ...)
42 Many GObject-based libraries to be bound to perl will be too large
43 to put in a single XS file; however, a single PM file typically
44 only bootstraps one XS file's code. "write_boot" generates an XSH
45 file to be included from the BOOT section of that one bootstrapped
46 module, calling the boot code for all the other XS files in the
47 project.
48 Options are passed to the function in a set of key/val pairs, and
50 all options may default.
51 filename the name of the output file to be created.
53 the default is 'build/boot.xsh'.
54 glob a glob pattern that specifies the names of
56 the xs files to scan for MODULE lines.
57 the default is 'xs/*.xs'.
58 xs_files use this to supply an explicit list of file
60 names (as an array reference) to use instead
61 of a glob pattern. the default is to use
62 the glob pattern.
63 ignore regular expression matching any and all
65 module names which should be ignored, i.e.
66 NOT included in the list of symbols to boot.
67 this parameter is extremely important for
68 avoiding infinite loops at startup; see the
69 discussion for an explanation and rationale.
70 the default is '^[^:]+$', or, any name that
71 contains no colons, i.e., any toplevel
72 package name.
73 This function performs a glob (using perl's builtin glob operator)
75 on the pattern specified by the 'glob' option to retrieve a list of
76 file names. It then scans each file in that list for lines
77 matching the pattern "^MODULE" -- that is, the MODULE directive in
78 an XS file. The module name is pulled out and matched against the
79 regular expression specified by the ignore parameter. If this
80 module is not to be ignored, we next check to see if the name has
81 been seen. If not, the name will be converted to a boot symbol
82 (basically, s/:/_/ and prepend "boot_") and this symbol will be
83 added to a call to GPERL_CALL_BOOT in the generated file; it is
84 then marked as seen so we don't call it again.
85 What is this all about, you ask? In order to bind an XSub to perl,
87 the C function must be registered with the interpreter. This is
88 the function of the "boot" code, which is typically called in the
89 bootstrapping process. However, when multiple XS files are used
90 with only one PM file, some other mechanism must call the boot code
91 from each XS file before any of the function therein will be
92 available.
93 A typical setup for a multiple-XS, single-PM module will be to call
95 the various bits of boot code from the BOOT: section of the
96 toplevel module's XS file.
97 To use Gtk2 as an example, when you do 'use Gtk2', Gtk2.pm calls
99 bootstrap on Gtk2, which calls the C function boot_Gtk2. This
100 function calls the boot symbols for all the other xs files in the
101 module. The distinction is that the toplevel module, Gtk2, has no
102 colons in its name.
103 "xsubpp" generates the boot function's name by replacing the colons
105 in the MODULE name with underscores and prepending "boot_". We
106 need to be careful not to include the boot code for the
107 bootstrapped module, (say Toplevel, or Gtk2, or whatever) because
108 the bootstrap code in Toplevel.pm will call boot_Toplevel when
109 loaded, and boot_Toplevel should actually include the file we are
110 creating here.
111 The default value for the ignore parameter ignores any name not
113 containing colons, because it is assumed that this will be a
114 toplevel module, and any other packages/modules it boots will be
115 below this namespace, i.e., they will contain colons. This
116 assumption holds true for Gtk2 and Gnome2, but obviously fails for
117 something like Gnome2::Canvas. To boot that module properly, you
118 must use a regular expression such as "^Gnome2::Canvas$".
119 Note that you can, of course, match more than just one name, e.g.
121 "^(Foo|Foo::Bar)$", if you wanted to have Foo::Bar be included in
122 the same dynamically loaded object but only be booted when
123 absolutely necessary. (If you get that to work, more power to
124 you.)
125 Also, since this code scans for ^MODULE, you must comment the
127 MODULE section out with leading # marks if you want to hide it from
128 "write_boot".
129 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-
134 written code as well as the typemaps. However, if you have a lot
135 of types in your library (such as the nearly 200 types in Gtk+
136 2.x), then writing those macros becomes incredibly tedious,
137 especially so when you factor in all of the variants and such.
138 So, this function can turn a flat file containing terse
140 descriptions of the types into a header containing all the cast
141 macros, a typemap file using them, and an XSH file containing the
142 proper code to register each of those types (to be included by your
143 module's BOOT code).
144 The PREFIX is mandatory, and is used in some of the resulting
146 filenames, You can also override the defaults by providing key=>val
147 pairs:
148 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 the maps file is a table of type descriptions, one per line, with
160 fields separated by whitespace. the fields should be:
161 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 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 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
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
187 support 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 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 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 $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 For example:
205 Glib::CodeGen->add_type_handler (CoolThing => sub {
207 my ($typemacro, $classname, $base, $package) = @_;
208 # $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 ...
219 });
220 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 Example:
230 # 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 # 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 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 add_register "#ifdef $typemacro\n"
251 . "gperl_register_object ($typemacro, \"$package\");\n"
252 . "#endif /* $typemacro */";
253 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
260 GInterfaces are mostly just ignored.
261 The code is ugly.
263
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 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 This library is distributed in the hope that it will be useful, but
277 WITHOUT ANY WARRANTY; without even the implied warranty of
278 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
279 Library General Public License for more details.
280 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.
285perl v5.12.1 2010-05-30 CodeGen(3)