.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Gtk2::CodeGen 3pm" .TH Gtk2::CodeGen 3pm "2019-09-16" "perl v5.28.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Gtk2::CodeGen \- code generation utilities for Glib\-based bindings. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& # usually in Makefile.PL \& use Gtk2::CodeGen; \& \& # most common, use all defaults \& Gtk2::CodeGen\->parse_maps (\*(Aqmyprefix\*(Aq); \& Gtk2::CodeGen\->write_boot; \& \& # more exotic, change everything \& Gtk2::CodeGen\->parse_maps (\*(Aqfoo\*(Aq, \& input => \*(Aqfoo.maps\*(Aq, \& header => \*(Aqfoo\-autogen.h\*(Aq, \& typemap => \*(Aqfoo.typemap\*(Aq, \& register => \*(Aqregister\-foo.xsh\*(Aq); \& Gtk2::CodeGen\->write_boot (filename => \*(Aqbootfoo.xsh\*(Aq, \& glob => \*(AqFoo*.xs\*(Aq, \& ignore => \*(Aq^(Foo|Foo::Bar)$\*(Aq); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module packages some of the boilerplate code needed for performing code generation typically used by perl bindings for gobject-based libraries, using the Glib module as a base. .PP The default output filenames are in the subdirectory 'build', which usually will be present if you are using ExtUtils::Depends (as most Glib-based extensions probably should). .SS "\s-1METHODS\s0" .IX Subsection "METHODS" .IP "Gtk2::CodeGen\->write_boot;" 4 .IX Item "Gtk2::CodeGen->write_boot;" .PD 0 .IP "Gtk2::CodeGen\->write_boot (\s-1KEY\s0 => \s-1VAL, ...\s0)" 4 .IX Item "Gtk2::CodeGen->write_boot (KEY => VAL, ...)" .PD Many GObject-based libraries to be bound to perl will be too large to put in a single \s-1XS\s0 file; however, a single \s-1PM\s0 file typically only bootstraps one \&\s-1XS\s0 file's code. \f(CW\*(C`write_boot\*(C'\fR generates an \s-1XSH\s0 file to be included from the \s-1BOOT\s0 section of that one bootstrapped module, calling the boot code for all the other \s-1XS\s0 files in the project. .Sp Options are passed to the function in a set of key/val pairs, and all options may default. .Sp .Vb 2 \& filename the name of the output file to be created. \& the default is \*(Aqbuild/boot.xsh\*(Aq. \& \& glob a glob pattern that specifies the names of \& the xs files to scan for MODULE lines. \& the default is \*(Aqxs/*.xs\*(Aq. \& \& xs_files use this to supply an explicit list of file \& names (as an array reference) to use instead \& of a glob pattern. the default is to use \& the glob pattern. \& \& ignore regular expression matching any and all \& module names which should be ignored, i.e. \& NOT included in the list of symbols to boot. \& this parameter is extremely important for \& avoiding infinite loops at startup; see the \& discussion for an explanation and rationale. \& the default is \*(Aq^[^:]+$\*(Aq, or, any name that \& contains no colons, i.e., any toplevel \& package name. .Ve .Sp This function performs a glob (using perl's 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 \&\*(L"^MODULE\*(R" \*(-- that is, the \s-1MODULE\s0 directive in an \s-1XS\s0 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 \*(L"boot_\*(R") and this symbol will be added to a call to \s-1GPERL_CALL_BOOT\s0 in the generated file; it is then marked as seen so we don't call it again. .Sp 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 \&\*(L"boot\*(R" code, which is typically called in the bootstrapping process. However, when multiple \s-1XS\s0 files are used with only one \s-1PM\s0 file, some other mechanism must call the boot code from each \s-1XS\s0 file before any of the function therein will be available. .Sp A typical setup for a multiple-XS, single-PM module will be to call the various bits of boot code from the \s-1BOOT:\s0 section of the toplevel module's \&\s-1XS\s0 file. .Sp 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. .Sp \&\f(CW\*(C`xsubpp\*(C'\fR generates the boot function's name by replacing the colons in the \s-1MODULE\s0 name with underscores and prepending \*(L"boot_\*(R". 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. .Sp 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 \fIbelow\fR 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 \*(L"^Gnome2::Canvas$\*(R". .Sp Note that you can, of course, match more than just one name, e.g. \&\*(L"^(Foo|Foo::Bar)$\*(R", 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.) .Sp Also, since this code scans for ^MODULE, you must comment the \s-1MODULE\s0 section out with leading # marks if you want to hide it from \f(CW\*(C`write_boot\*(C'\fR. .IP "Gtk2::CodeGen\->parse_maps (\s-1PREFIX,\s0 [\s-1KEY\s0 => \s-1VAL, ...\s0])" 4 .IX Item "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. .Sp 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 \s-1XSH\s0 file containing the proper code to register each of those types (to be included by your module's \s-1BOOT\s0 code). .Sp The \fI\s-1PREFIX\s0\fR is mandatory, and is used in some of the resulting filenames, You can also override the defaults by providing key=>val pairs: .Sp .Vb 9 \& input input file name. default is \*(Aqmaps\*(Aq. if this \& key\*(Aqs value is an array reference, all the \& filenames in the array will be scanned. \& header name of the header file to create, default is \& build/$prefix\-autogen.h \& typemap name of the typemap file to create, default is \& build/$prefix.typemap \& register name of the xsh file to contain all of the \& type registrations, default is build/register.xsh .Ve .Sp the maps file is a table of type descriptions, one per line, with fields separated by whitespace. the fields should be: .Sp .Vb 9 \& TYPE macro e.g., GTK_TYPE_WIDGET \& class name e.g. GtkWidget, name of the C type \& base type one of GObject, GBoxed, GEnum, GFlags. \& GtkObject is also supported, but the \& distinction is no longer necessary as \& of Glib 0.26. \& package name of the perl package to which this \& class name should be mapped, e.g. \& Gtk2::Widget .Ve .Sp 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: .Sp .Vb 6 \& domain macro e.g., GDK_PIXBUF_ERROR \& enum type macro e.g., GDK_TYPE_PIXBUF_ERROR \& base type GError \& package name of the Perl package to which this \& class name should be mapped, e.g., \& Gtk2::Gdk::Pixbuf::Error. .Ve .IP "Gtk2::CodeGen\->generate_constants_wrappers (\s-1KEY\s0 => \s-1VAL, ...\s0)" 4 .IX Item "Gtk2::CodeGen->generate_constants_wrappers (KEY => VAL, ...)" Generates an \s-1XS\s0 file with \s-1XSUB\s0 wrappers for C constants. The key-value pairs may contain one or more of the following keys: .RS 4 .IP "\fIprefix\fR: Specifies the package name the functions should be put into." 4 .IX Item "prefix: Specifies the package name the functions should be put into." .PD 0 .IP "\fIlists\fR: Reference to an array of filenames which specify the constants that should be wrapped." 4 .IX Item "lists: Reference to an array of filenames which specify the constants that should be wrapped." .IP "\fIxs_file\fR: The name of the \s-1XS\s0 file that should be created." 4 .IX Item "xs_file: The name of the XS file that should be created." .IP "\fIheader\fR: The name of the header file that should be included in the generated \s-1XS\s0 file." 4 .IX Item "header: The name of the header file that should be included in the generated XS file." .IP "\fIexport_tag\fR: The name of the Exporter tag that should be used for the constants wrappers." 4 .IX Item "export_tag: The name of the Exporter tag that should be used for the constants wrappers." .RE .RS 4 .PD .Sp All of the keys have mostly sane defaults. .Sp Don't forget to add the generated \s-1XS\s0 file to the list of \s-1XS\s0 files to be compiled. .Sp The lists describing the constants to be wrapped should have the following format: .Sp .Vb 1 \& CONSTANT_NAME [ \et+ CONSTANT_CONVERTER ] .Ve .Sp That is, the constant's name optionally followed by a tab and the converter that is to be used to convert the constant to a Perl scalar. If \&\s-1CONSTANT_CONVERTER\s0 is a simple string like 'newSViv' it will be used as follows to get a Perl scalar: \s-1CONSTANT_CONVERTER\s0 (\s-1CONSTANT_NAME\s0). If it contains \&'$var', as in 'newSVpv ($var, 0)', then '$var' will be replaced with \&\s-1CONSTANT_NAME\s0 and the resulting string will be used for conversion. .Sp The default for \s-1CONSTANT_CONVERTER\s0 is 'newSViv'. .RE .SH "SEE ALSO" .IX Header "SEE ALSO" Glib::CodeGen does the actual work; Gtk2::CodeGen is now just a wrapper which adds support for gtk-specific types. .SH "AUTHOR" .IX Header "AUTHOR" muppet .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 2003\-2005, 2013 by the gtk2\-perl team (see the file \s-1AUTHORS\s0 for the full list) .PP This library is free software; you can redistribute it and/or modify it under the terms of the \s-1GNU\s0 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. .PP This library is distributed in the hope that it will be useful, but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 See the \s-1GNU\s0 Library General Public License for more details. .PP You should have received a copy of the \s-1GNU\s0 Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, \s-1MA\s0 02110\-1301 \s-1USA.\s0