.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 "XSBuilder 3"
.TH XSBuilder 3 2024-07-13 "perl v5.38.2" "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
ExtUtils::XSBuilder \- Automatic Perl XS glue code generation
.SH DESCRIPTION
.IX Header "DESCRIPTION"
ExtUtils::XSBuilder is a set modules to parse C header files and create XS
glue code and documentation out of it. Idealy this allows to "write" an
interface to a C library without coding a line. Since no C API is ideal,
some adjuments are necessary most of the time. So to use this module you
must still be familiar with C and XS programming, but it removes a lot of
stupid work and copy & paste from you. Also when the C API changes, most
of the time you only have to rerun XSBuilder to get your new Perl API.
.PP
The creation process takes place in the following steps:
.SS "Derive a class from ExtUtils::XSBuilder::ParseSource"
.IX Subsection "Derive a class from ExtUtils::XSBuilder::ParseSource"
This class must override some methods to tell XSBuilder which C header files
to parse and some other necessary parameters. You need at least to override
the \f(CW\*(C`package\*(C'\fR method to give the name of the package you want to create and 
either the \f(CW\*(C`find_includes\*(C'\fR method which returns all C header files to parse,
or the \f(CW\*(C`include_dirs\*(C'\fR method to return a list of all directories which
should be scanned for C header files.
.PP
Of course there are more methods you can overide. See 
ExtUtils::XSBuilder::ParseSource for a full list of overrideable methods.
.SS "Scan the source files"
.IX Subsection "Scan the source files"
If your derived class is called MyClass::ParseSource you simply start the 
source scan with
.PP
.Vb 1
\&    perl \-MMyClass::ParseSource \-e \*(AqMyClass::ParseSource\->run\*(Aq
.Ve
.PP
You may also put this into a small script to ease usage, set the Perl libpath,
etc.
.PP
During the source scan, XSBuilder creates a set of tables which contain the
results of parsing. If you haven't changed the default locations in your
subclass, these tables are created under \f(CW\*(C`xs/tables\*(C'\fR, followed by the
name of the module returned by the \f(CW\*(C`package\*(C'\fR method you created. There you
will find four generated modules: \f(CW\*(C`FunctionTable.pm\*(C'\fR, which holds the
function declarations; \f(CW\*(C`StructureTable.pm\*(C'\fR, which holds the structures;
\&\f(CW\*(C`ConstantTable.pm\*(C'\fR, which contains constants found in the header files; and
\&\f(CW\*(C`CallbackTable.pm\*(C'\fR, which contains definitions for callback types.
.PP
Since source scanning may take some time, we create intermediate tables and
transform them into XS code later, rather than creating XS code directly.
Since we save the result, we can avoid rescanning the source files as long as
they don't change.
.SS "Derive a class from ExtUtils::XSBuilder::WrapXS"
.IX Subsection "Derive a class from ExtUtils::XSBuilder::WrapXS"
The WrapXS class is responsible for taking the information generated both from
the source files and from the map files (see below) to create the XS code.
As with the ParseSource class, you must override this method with your own
implementaion, to tell WrapXS what to do.
.PP
See ExtUtils::XSBuilder::WrapXS for a list of overrideable methods.
.SS "Create map files"
.IX Subsection "Create map files"
XSBuilder will not automaticly create XS functions for all C functions and
structures. You must provide hints in order for the XS files to be created
properly. The map files are the mechanism to provide these hints. By default,
the map files are found under \f(CW\*(C`xs/maps\*(C'\fR. There are four map types, \f(CW\*(C`types\*(C'\fR,
\&\f(CW\*(C`functions\*(C'\fR, \f(CW\*(C`structures\*(C'\fR, and \f(CW\*(C`callbacks\*(C'\fR. Each map file is named with
a user selectable prefix (e.g. \f(CW\*(C`foo\*(C'\fR,) followed by an underscore, the map
type name, and the map extension \f(CW\*(C`.map\*(C'\fR. For example, hints for functions
relating to error processing in your source may be contained in a map file
named \f(CW\*(C`error_functions.map\*(C'\fR.
.IP foo_types.map 4
.IX Item "foo_types.map"
Contains the mapping from C types to Perl classes.
.IP foo_functions.map 4
.IX Item "foo_functions.map"
Contains the mapping from C functions to Perl functions. Can be used to 
reorder arguments, tell XSBuilder which arguments are actualy return values 
and in which Perl package the function will be created.
.IP foo_structures.map 4
.IX Item "foo_structures.map"
Contains the mapping from C structures to Perl classes and defines for which
classes the access methods should be created. You can also specify if you want
a \f(CW\*(C`new\*(C'\fR method for the class.
.IP foo_callbacks.map 4
.IX Item "foo_callbacks.map"
Contains the mapping form C callback functions to Perl callback functions. Can
be used to reorder arguments, tell XSBuilder which arguments are return
values, and in which Perl package the functions will be created.
.PP
For a detailed description of the map file formats see below.
.PP
To have a starting point, XSBuilder is able to create default map files which
simply include all types, functions and structures. You can recreate the map
files anytime and XSBuilder will append all items which are not already in the
map files.
.PP
First copy the _types.map file from the xsbuilder directory to your maps
directory. This file contains the standard mapping for some basic types.
.PP
If, for example, your derived class is called MyClass::WrapXS, you simply
start the creation/update of the map files with
.PP
.Vb 1
\&    perl \-MMyClass::WrapXS \-e \*(AqMyClass::WrapXS\->checkmaps(" ")\*(Aq
.Ve
.PP
The argument to checkmaps supplies a character to be prepended to the first
column of the new map entries. If you do not pass an argument to checkmaps, no
map files are written, and checkmaps will only compare what is missing. (You
need to print the result somehow e.g. by using Data::Dumper). You may also put
this into a small script to ease usage, set the Perl libpath, etc.
.PP
After you have created your default maps, you must edit the 
\&\f(CW\*(C`xs/maps/new_type.map\*(C'\fR file, which contains all types that were found in the
source. Append a pipe (\f(CW\*(C`|\*(C'\fR) followed by the class or type name, e.g.
.PP
.Vb 2
\&    int                 | IV
\&    struct request_rec  | Apache::RequestRec
.Ve
.PP
\&.
.SS "Create the XS files"
.IX Subsection "Create the XS files"
Now we can create the code. By running
.PP
.Vb 1
\&    perl \-MMyClass::WrapXS \-e \*(AqMyClass::WrapXS\->run\*(Aq
.Ve
.PP
XSBuilder will create the XS, pm and Makefile.PL files for every module that 
is mentioned in the maps. The result is placed as a directory hierarchy under
WrapXS. To control the content of the \f(CW\*(C`Makefile.PL\*(C'\fR and the \f(CW\*(C`pm\*(C'\fR file, you
can override the \f(CW\*(C`makefilepl_text\*(C'\fR and \f(CW\*(C`pm_text\*(C'\fR methods. You can include
additional code in the XS files by writing an include file which is included
at the top of the XS file. This file can contain helper functions that can't
be automatically generated. The files must be placed under the \f(CW\*(C`xs\*(C'\fR
directory, with the correct path and name. For example, to have a header file
included for the module Apache::DAV, create a file named
\&\f(CW\*(C`xs/Apache/DAV/Apache_\|_DAV.h\*(C'\fR. The same can be done for inclusion in the pm
file. Following the example above, the file name would be 
\&\f(CW\*(C`xs/Apache/DAV/DAV_pm\*(C'\fR.
.SH "Format of the map files"
.IX Header "Format of the map files"
For all map files blank lines are ignored and lines starting with a \f(CW\*(C`#\*(C'\fR are
treated as comments and are also ignored.
.SS "Types map file"
.IX Subsection "Types map file"
Contains the mapping from C type to Perl classes.
.PP
Format is the name of the C type followed by the name of the Perl class
or the XS type specifier, separated by a \f(CW\*(C`|\*(C'\fR. Example:
.PP
.Vb 2
\&    int                 | IV
\&    struct request_rec  | Apache::RequestRec
.Ve
.PP
If you have a Perl class with a single-level namespace (e.g. Apache) you need
to postfix it with two colons (e.g. "Apache::"). When both a typedef and a
structure share the same name, structures must be written as with a "struct "
prefix (e.g. "struct foo".) Addionally, you can give the id for the typemap if
you need a special conversion and one or more other names for the struct:
.PP
.Vb 1
\&    struct request_rec  | Apache::RequestRec | T_APACHEOBJ | r
.Ve
.PP
An optional fifth parameter specifies that the data needs to be copied
when assigned to a struct member and selects the way how memory is allocated:
.PP
.Vb 1
\&    char *   | PV | | | strdup
.Ve
.PP
The actual code for memory allocation is provided inside the structure map,
for example:
.PP
.Vb 2
\&    MALLOC=strdup:$dest = ($type)ap_pstrdup(obj \-> pool, $src)
\&    MALLOC=malloc:ap_palloc(obj \-> pool, $src, sizeof($type)) ; memcpy($dest,$src,sizeof($type))
.Ve
.PP
This gives two ways to allocate memory and copy the data into it. The fifth
parameter in the type map selects which of these two should be used. \f(CW$src\fR,
\&\f(CW$dest\fR and \f(CW$type\fR are replaced by the source, the destination and the type.
\&\f(CW\*(C`obj\*(C'\fR is a pointer to the C\-structure.
.PP
\fISpecial Types\fR
.IX Subsection "Special Types"
.IP "String, PV and PVnull" 4
.IX Item "String, PV and PVnull"
A string is represented in C as a pointer to an null terminated range of
characters. In Perl the it is called \f(CW\*(C`PV\*(C'\fR (pointer value). When converting
a Perl \f(CW\*(C`undef\*(C'\fR to a C string Perl by default converts it to an empty string.
While this is save, this is not always what is required, because many
C interfaces treat NULL as a special case. For this reason the \f(CW\*(C`PVnull\*(C'\fR type
is introduced, which converts \f(CW\*(C`undef\*(C'\fR to \f(CW\*(C`NULL\*(C'\fR and \f(CW\*(C`NULL\*(C'\fR to \f(CW\*(C`undef\*(C'\fR.
.Sp
To make it work you need the following line in your type map file:
.Sp
.Vb 1
\&        PVnull          | PVnull | | | strdup
.Ve
.Sp
Now you can defines any type, structure memeber or function argument
as type \f(CW\*(C`PVnull\*(C'\fR.
.SS "Functions map file"
.IX Subsection "Functions map file"
Contains the mapping from C functions to Perl functions. This can be used to 
reorder arguments, tell XSBuilder which arguments are return values, and in
which Perl package the function will be created.
.PP
There are some directives which affect the function mappings that follow it.
Each directive may appear in the file more than once.
.IP MODULE 4
.IX Item "MODULE"
the module name (file name) where the function should be defined, e.g.
.Sp
.Vb 1
\&    MODULE=Apache::Connection
.Ve
.Sp
will define the functions that follow in files named Apache/Connection.{pm,xs}
.IP PACKAGE 4
.IX Item "PACKAGE"
The name of the package that functions are defined in. If undefined, PACKAGE
defaults to the value of MODULE. A value of 'guess' indicates that package
name should be guessed based on first argument found that maps to a Perl
class. Falls back on the prefix (ap_ \-> Apache, apr_ \-> APR).
.IP PREFIX 4
.IX Item "PREFIX"
The prefix to be stripped from C functions when creating the XS stubs.
Defaults to the value of PACKAGE, converted to C naming convention. For
example,
.Sp
.Vb 1
\&    PREFIX=APR::Base64
.Ve
.Sp
will strip \f(CW\*(C`apr_base64_\*(C'\fR from the C functions. If the prefix does not match,
it defaults to \f(CW\*(C`ap_\*(C'\fR or \f(CW\*(C`apr_\*(C'\fR.
.PP
\&\fBNOTE:\fR You must have at least one \f(CW\*(C`MODULE\*(C'\fR definition
otherwise all functions will be ignored.
.PP
The format of entries is:
.PP
.Vb 1
\&    C function name | dispatch function name (dispatch argspec) | argspec | Perl alias
.Ve
.PP
The \f(CW\*(C`dispatch function name\*(C'\fR (the C function that is actually called)
defaults to C function name. If the dispatch function name is just a prefix
(mpxs_, MPXS_), the \f(CW\*(C`C function name\*(C'\fR is appended to it. The return type may
be specified before the \f(CW\*(C`C function name\*(C'\fR, and defaults to the \f(CW\*(C`return_type\*(C'\fR
in the \f(CW\*(C`{foo}::FunctionTable\*(C'\fR module generated by the \f(CW\*(C`ParseSource\*(C'\fR module.
.PP
The \f(CW\*(C`dispatch argspec\*(C'\fR is optional. If supplied, it can be used to pass
different parameters to the dispatch function then to the XS function. If the
function name begins with \f(CW\*(C`DEFINE_\*(C'\fR, a new function is defined (for defining
functions that are not parsed from the source). \f(CW\*(C`argspec\*(C'\fR must be supplied.
\&\f(CW\*(C`DEFINE_\*(C'\fR is not included in the generated function name.
.PP
The \f(CW\*(C`argspec\*(C'\fR defaults to arguments in \f(CW\*(C`{foo}::FunctionTable\*(C'\fR, as generated
by the \f(CW\*(C`ParseSource\*(C'\fR module. Argument types can be specified to override
those in the \f(CW\*(C`{foo}::FunctionTable\*(C'\fR. Default values can also be specified,
e.g. arg=default_value
.PP
For example:
  ap_get_client_block   | mpxs_ | r, SV *:buffer, bufsiz
  ap_setup_client_block |       | r, read_policy=REQUEST_CHUNKED_ERROR
  ap_make_array      | ap_make_array(r\->pool, nelts, elt_size) | request_rec *:r, nelts, elt_size
.PP
argspec of '...' indicates passthru, calling the function with
.PP
.Vb 1
\&    (aTHX_ I32 items, SP **sp, SV **MARK)
.Ve
.PP
To mark an argument as return only you can prefix it with < e.g.
.PP
.Vb 1
\&    dav_open_lockdb | | r, ro, <lockdb
.Ve
.PP
will be called as ($error get the return value of the C function)
.PP
.Vb 1
\&    ($error, $lockdb) = $r \-> open_lockdb (0) ;
.Ve
.PP
The return argument (e.g. lockdb) will always be passed by address 
to the function.
.PP
The function alias, if defined, will be created in the current \f(CW\*(C`PACKAGE\*(C'\fR.
.PP
Function names on lines that do not begin with a word character or a single
space are skipped. Function names can be prefixed with the following symbols:
.PP
.Vb 5
\&    \*(Aq!\*(Aq => \*(Aqdisabled or not yet implemented\*(Aq,
\&    \*(Aq~\*(Aq => \*(Aqimplemented but not auto\-generated\*(Aq,
\&    \*(Aq\-\*(Aq => \*(Aqlikely never be available to Perl\*(Aq,
\&    \*(Aq>\*(Aq => \*(Aq"private" to your C library\*(Aq,
\&    \*(Aq?\*(Aq => \*(Aqunclassified\*(Aq,
.Ve
.SS "Structures map file"
.IX Subsection "Structures map file"
Contains the mapping from C structures to Perl classes and defines the members
for which access methods should be created. A \f(CW\*(C`new\*(C'\fR method may be specified,
if desired. The format looks like the following:
.PP
.Vb 5
\&    <struct_name>
\&      member1
\&      member2
\&      new
\&    </struct_name>
.Ve
.PP
An optional module name can be given, to specify in which module the code
should be placed. To place the structure in My::Module, for example, specify:
.PP
.Vb 1
\&    <struct_name MODULE=My::Module>
.Ve
.PP
For all members that are listed here, XSBuilder will generate an access method
to read and write it's content. If you want to name the perl access method
differently than the C member, you can write
.PP
.Vb 1
\&   cMemberValue | member_value | type
.Ve
.PP
this will map the \f(CW\*(C`cMemberValue\*(C'\fR structure member to the access function 
\&\f(CW\*(C`member_value\*(C'\fR. The default is to use the same name in Perl as in C.
As third argument you can give a typename. This defaults to the type of the 
variable. It can be used to specify a different type, for special conversion needs.
(e.g. PV versus PVnull)
If you give the \f(CW\*(C`new\*(C'\fR member, XSBuilder will create a new method for that
class, which can be used to create a new instance and initialize it with data.
.SS "Callbacks map file"
.IX Subsection "Callbacks map file"
The format of entries is:
.PP
.Vb 1
\&    C function name | argspec
.Ve
.PP
The content is the same as function map, it but contains the callbacks.
.SH "Additional generated methods"
.IX Header "Additional generated methods"
For structures, XSBuilder will generate two additional methods: \f(CW\*(C`new\*(C'\fR, and
\&\f(CW\*(C`init_callbacks\*(C'\fR.
.SS "new ($initialvalue)"
.IX Subsection "new ($initialvalue)"
With \f(CW\*(C`new\*(C'\fR you can create a new Perl object for an C structure. Optionally,
you can pass either a hashref with initial data, or another object, who's
data will be copied into the new object.
.SS init_callbacks
.IX Subsection "init_callbacks"
\&\f(CW\*(C`init_callbacks\*(C'\fR should be called during object initialization. It will fill
in all callback members of a structure with pointers that cause a method call
into the object, when the callback is called from C.
.PP
You can call it either with
.PP
.Vb 1
\&    $obj \-> init_callbacks
.Ve
.PP
or
.PP
.Vb 1
\&    MyModule \-> init_callbacks ($obj) ;
.Ve
.SH Callbacks
.IX Header "Callbacks"
A callback which is part of a structure will cause a call to the method with
the same name as the structure member, prefixed with \f(CW\*(C`cb_\*(C'\fR. For example, if
you have a structure member named \f(CW\*(C`open\*(C'\fR, then the Perl method \f(CW\*(C`cb_open\*(C'\fR
will be called whenever the C code calls the callback.
.PP
If you want to call the callback on your own you need to call the method which
is called like the structure member, e.g. \f(CW\*(C`open\*(C'\fR.
.PP
NOTE: You need to call \f(CW\*(C`init_callbacks\*(C'\fR during your method initialzation to
be able to call callbacks.