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

NAME

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

SYNOPSIS

9        # usually in Makefile.PL
10        use Gtk2::CodeGen;
11
12        # most common, use all defaults
13        Gtk2::CodeGen->parse_maps ('myprefix');
14        Gtk2::CodeGen->write_boot;
15
16        # 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

DESCRIPTION

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
31       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
35   METHODS
36       Gtk2::CodeGen->write_boot;
37       Gtk2::CodeGen->write_boot (KEY => VAL, ...)
38           Many GObject-based libraries to be bound to perl will be too large
39           to put in a single XS file; however, a single PM file typically
40           only bootstraps one XS file's code.  "write_boot" generates an XSH
41           file to be included from the BOOT section of that one bootstrapped
42           module, calling the boot code for all the other XS files in the
43           project.
44
45           Options are passed to the function in a set of key/val pairs, and
46           all options may default.
47
48             filename     the name of the output file to be created.
49                          the default is 'build/boot.xsh'.
50
51             glob         a glob pattern that specifies the names of
52                          the xs files to scan for MODULE lines.
53                          the default is 'xs/*.xs'.
54
55             xs_files     use this to supply an explicit list of file
56                          names (as an array reference) to use instead
57                          of a glob pattern.  the default is to use
58                          the glob pattern.
59
60             ignore       regular expression matching any and all
61                          module names which should be ignored, i.e.
62                          NOT included in the list of symbols to boot.
63                          this parameter is extremely important for
64                          avoiding infinite loops at startup; see the
65                          discussion for an explanation and rationale.
66                          the default is '^[^:]+$', or, any name that
67                          contains no colons, i.e., any toplevel
68                          package name.
69
70           This function performs a glob (using perl's builtin glob operator)
71           on the pattern specified by the 'glob' option to retrieve a list of
72           file names.  It then scans each file in that list for lines
73           matching the pattern "^MODULE" -- that is, the MODULE directive in
74           an XS file.  The module name is pulled out and matched against the
75           regular expression specified by the ignore parameter.  If this
76           module is not to be ignored, we next check to see if the name has
77           been seen.  If not, the name will be converted to a boot symbol
78           (basically, s/:/_/ and prepend "boot_") and this symbol will be
79           added to a call to GPERL_CALL_BOOT in the generated file; it is
80           then marked as seen so we don't call it again.
81
82           What is this all about, you ask?  In order to bind an XSub to perl,
83           the C function must be registered with the interpreter.  This is
84           the function of the "boot" code, which is typically called in the
85           bootstrapping process.  However, when multiple XS files are used
86           with only one PM file, some other mechanism must call the boot code
87           from each XS file before any of the function therein will be
88           available.
89
90           A typical setup for a multiple-XS, single-PM module will be to call
91           the various bits of boot code from the BOOT: section of the
92           toplevel module's XS file.
93
94           To use Gtk2 as an example, when you do 'use Gtk2', Gtk2.pm calls
95           bootstrap on Gtk2, which calls the C function boot_Gtk2.  This
96           function calls the boot symbols for all the other xs files in the
97           module.  The distinction is that the toplevel module, Gtk2, has no
98           colons in its name.
99
100           "xsubpp" generates the boot function's name by replacing the colons
101           in the MODULE name with underscores and prepending "boot_".  We
102           need to be careful not to include the boot code for the
103           bootstrapped module, (say Toplevel, or Gtk2, or whatever) because
104           the bootstrap code in Toplevel.pm will call boot_Toplevel when
105           loaded, and boot_Toplevel should actually include the file we are
106           creating here.
107
108           The default value for the ignore parameter ignores any name not
109           containing colons, because it is assumed that this will be a
110           toplevel module, and any other packages/modules it boots will be
111           below this namespace, i.e., they will contain colons.  This
112           assumption holds true for Gtk2 and Gnome2, but obviously fails for
113           something like Gnome2::Canvas.  To boot that module properly, you
114           must use a regular expression such as "^Gnome2::Canvas$".
115
116           Note that you can, of course, match more than just one name, e.g.
117           "^(Foo|Foo::Bar)$", if you wanted to have Foo::Bar be included in
118           the same dynamically loaded object but only be booted when
119           absolutely necessary.  (If you get that to work, more power to
120           you.)
121
122           Also, since this code scans for ^MODULE, you must comment the
123           MODULE section out with leading # marks if you want to hide it from
124           "write_boot".
125
126       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-
130           written code as well as the typemaps.  However, if you have a lot
131           of types in your library (such as the nearly 200 types in Gtk+
132           2.x), then writing those macros becomes incredibly tedious,
133           especially so when you factor in all of the variants and such.
134
135           So, this function can turn a flat file containing terse
136           descriptions of the types into a header containing all the cast
137           macros, a typemap file using them, and an XSH file containing the
138           proper code to register each of those types (to be included by your
139           module's BOOT code).
140
141           The PREFIX is mandatory, and is used in some of the resulting
142           filenames, You can also override the defaults by providing key=>val
143           pairs:
144
145             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
155           the maps file is a table of type descriptions, one per line, with
156           fields separated by whitespace.  the fields should be:
157
158             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
168           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
172             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
179       Gtk2::CodeGen->generate_constants_wrappers (KEY => VAL, ...)
180           Generates an XS file with XSUB wrappers for C constants.  The key-
181           value pairs may contain one or more of the following keys:
182
183           prefix: Specifies the package name the functions should be put
184           into.
185           lists: Reference to an array of filenames which specify the
186           constants that should be wrapped.
187           xs_file: The name of the XS file that should be created.
188           header: The name of the header file that should be included in the
189           generated XS file.
190           export_tag: The name of the Exporter tag that should be used for
191           the constants wrappers.
192
193           All of the keys have mostly sane defaults.
194
195           Don't forget to add the generated XS file to the list of XS files
196           to be compiled.
197
198           The lists describing the constants to be wrapped should have the
199           following format:
200
201             CONSTANT_NAME [ \t+ CONSTANT_CONVERTER ]
202
203           That is, the constant's name optionally followed by a tab and the
204           converter that is to be used to convert the constant to a Perl
205           scalar.  If CONSTANT_CONVERTER is a simple string like 'newSViv' it
206           will be used as follows to get a Perl scalar: CONSTANT_CONVERTER
207           (CONSTANT_NAME).  If it contains '$var', as in 'newSVpv ($var, 0)',
208           then '$var' will be replaced with CONSTANT_NAME and the resulting
209           string will be used for conversion.
210
211           The default for CONSTANT_CONVERTER is 'newSViv'.
212

SEE ALSO

214       Glib::CodeGen does the actual work; Gtk2::CodeGen is now just a wrapper
215       which adds support for gtk-specific types.
216

AUTHOR

218       muppet <scott at asofyet dot org>
219
221       Copyright (C) 2003-2005, 2013 by the gtk2-perl team (see the file
222       AUTHORS for the full list)
223
224       This library is free software; you can redistribute it and/or modify it
225       under the terms of the GNU Library General Public License as published
226       by the Free Software Foundation; either version 2.1 of the License, or
227       (at your option) any later version.
228
229       This library is distributed in the hope that it will be useful, but
230       WITHOUT ANY WARRANTY; without even the implied warranty of
231       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
232       Library General Public License for more details.
233
234       You should have received a copy of the GNU Library General Public
235       License along with this library; if not, write to the Free Software
236       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
237       02110-1301  USA.
238
239
240
241perl v5.32.0                      2020-07-28                  Gtk2::CodeGen(3)
Impressum