1XSBuilder(3)          User Contributed Perl Documentation         XSBuilder(3)
2
3
4

NAME

6       ExtUtils::XSBuilder - Automatic Perl XS glue code generation
7

DESCRIPTION

9       ExtUtils::XSBuilder is a set modules to parse C header files and create
10       XS glue code and documentation out of it. Idealy this allows to "write"
11       an interface to a C library without coding a line. Since no C API is
12       ideal, some adjuments are necessary most of the time. So to use this
13       module you must still be familiar with C and XS programming, but it
14       removes a lot of stupid work and copy & paste from you. Also when the C
15       API changes, most of the time you only have to rerun XSBuilder to get
16       your new Perl API.
17
18       The creation process takes place in the following steps:
19
20   Derive a class from ExtUtils::XSBuilder::ParseSource
21       This class must override some methods to tell XSBuilder which C header
22       files to parse and some other necessary parameters. You need at least
23       to override the "package" method to give the name of the package you
24       want to create and either the "find_includes" method which returns all
25       C header files to parse, or the "include_dirs" method to return a list
26       of all directories which should be scanned for C header files.
27
28       Of course there are more methods you can overide. See
29       ExtUtils::XSBuilder::ParseSource for a full list of overrideable
30       methods.
31
32   Scan the source files
33       If your derived class is called MyClass::ParseSource you simply start
34       the source scan with
35
36           perl -MMyClass::ParseSource -e 'MyClass::ParseSource->run'
37
38       You may also put this into a small script to ease usage, set the Perl
39       libpath, etc.
40
41       During the source scan, XSBuilder creates a set of tables which contain
42       the results of parsing. If you haven't changed the default locations in
43       your subclass, these tables are created under "xs/tables", followed by
44       the name of the module returned by the "package" method you created.
45       There you will find four generated modules: "FunctionTable.pm", which
46       holds the function declarations; "StructureTable.pm", which holds the
47       structures; "ConstantTable.pm", which contains constants found in the
48       header files; and "CallbackTable.pm", which contains definitions for
49       callback types.
50
51       Since source scanning may take some time, we create intermediate tables
52       and transform them into XS code later, rather than creating XS code
53       directly.  Since we save the result, we can avoid rescanning the source
54       files as long as they don't change.
55
56   Derive a class from ExtUtils::XSBuilder::WrapXS
57       The WrapXS class is responsible for taking the information generated
58       both from the source files and from the map files (see below) to create
59       the XS code.  As with the ParseSource class, you must override this
60       method with your own implementaion, to tell WrapXS what to do.
61
62       See ExtUtils::XSBuilder::WrapXS for a list of overrideable methods.
63
64   Create map files
65       XSBuilder will not automaticly create XS functions for all C functions
66       and structures. You must provide hints in order for the XS files to be
67       created properly. The map files are the mechanism to provide these
68       hints. By default, the map files are found under "xs/maps". There are
69       four map types, "types", "functions", "structures", and "callbacks".
70       Each map file is named with a user selectable prefix (e.g. "foo",)
71       followed by an underscore, the map type name, and the map extension
72       ".map". For example, hints for functions relating to error processing
73       in your source may be contained in a map file named
74       "error_functions.map".
75
76       foo_types.map
77           Contains the mapping from C types to Perl classes.
78
79       foo_functions.map
80           Contains the mapping from C functions to Perl functions. Can be
81           used to reorder arguments, tell XSBuilder which arguments are
82           actualy return values and in which Perl package the function will
83           be created.
84
85       foo_structures.map
86           Contains the mapping from C structures to Perl classes and defines
87           for which classes the access methods should be created. You can
88           also specify if you want a "new" method for the class.
89
90       foo_callbacks.map
91           Contains the mapping form C callback functions to Perl callback
92           functions. Can be used to reorder arguments, tell XSBuilder which
93           arguments are return values, and in which Perl package the
94           functions will be created.
95
96       For a detailed description of the map file formats see below.
97
98       To have a starting point, XSBuilder is able to create default map files
99       which simply include all types, functions and structures. You can
100       recreate the map files anytime and XSBuilder will append all items
101       which are not already in the map files.
102
103       First copy the _types.map file from the xsbuilder directory to your
104       maps directory. This file contains the standard mapping for some basic
105       types.
106
107       If, for example, your derived class is called MyClass::WrapXS, you
108       simply start the creation/update of the map files with
109
110           perl -MMyClass::WrapXS -e 'MyClass::WrapXS->checkmaps(" ")'
111
112       The argument to checkmaps supplies a character to be prepended to the
113       first column of the new map entries. If you do not pass an argument to
114       checkmaps, no map files are written, and checkmaps will only compare
115       what is missing. (You need to print the result somehow e.g. by using
116       Data::Dumper). You may also put this into a small script to ease usage,
117       set the Perl libpath, etc.
118
119       After you have created your default maps, you must edit the
120       "xs/maps/new_type.map" file, which contains all types that were found
121       in the source. Append a pipe ("|") followed by the class or type name,
122       e.g.
123
124           int                 | IV
125           struct request_rec  | Apache::RequestRec
126
127       .
128
129   Create the XS files
130       Now we can create the code. By running
131
132           perl -MMyClass::WrapXS -e 'MyClass::WrapXS->run'
133
134       XSBuilder will create the XS, pm and Makefile.PL files for every module
135       that is mentioned in the maps. The result is placed as a directory
136       hierarchy under WrapXS. To control the content of the "Makefile.PL" and
137       the "pm" file, you can override the "makefilepl_text" and "pm_text"
138       methods. You can include additional code in the XS files by writing an
139       include file which is included at the top of the XS file. This file can
140       contain helper functions that can't be automatically generated. The
141       files must be placed under the "xs" directory, with the correct path
142       and name. For example, to have a header file included for the module
143       Apache::DAV, create a file named "xs/Apache/DAV/Apache__DAV.h". The
144       same can be done for inclusion in the pm file. Following the example
145       above, the file name would be "xs/Apache/DAV/DAV_pm".
146

Format of the map files

148       For all map files blank lines are ignored and lines starting with a "#"
149       are treated as comments and are also ignored.
150
151   Types map file
152       Contains the mapping from C type to Perl classes.
153
154       Format is the name of the C type followed by the name of the Perl class
155       or the XS type specifier, separated by a "|". Example:
156
157           int                 | IV
158           struct request_rec  | Apache::RequestRec
159
160       If you have a Perl class with a single-level namespace (e.g. Apache)
161       you need to postfix it with two colons (e.g. "Apache::"). When both a
162       typedef and a structure share the same name, structures must be written
163       as with a "struct " prefix (e.g. "struct foo".) Addionally, you can
164       give the id for the typemap if you need a special conversion and one or
165       more other names for the struct:
166
167           struct request_rec  | Apache::RequestRec | T_APACHEOBJ | r
168
169       An optional fifth parameter specifies that the data needs to be copied
170       when assigned to a struct member and selects the way how memory is
171       allocated:
172
173           char *   | PV | | | strdup
174
175       The actual code for memory allocation is provided inside the structure
176       map, for example:
177
178           MALLOC=strdup:$dest = ($type)ap_pstrdup(obj -> pool, $src)
179           MALLOC=malloc:ap_palloc(obj -> pool, $src, sizeof($type)) ; memcpy($dest,$src,sizeof($type))
180
181       This gives two ways to allocate memory and copy the data into it. The
182       fifth parameter in the type map selects which of these two should be
183       used. $src, $dest and $type are replaced by the source, the destination
184       and the type.  "obj" is a pointer to the C-structure.
185
186       Special Types
187
188       String, PV and PVnull
189           A string is represented in C as a pointer to an null terminated
190           range of characters. In Perl the it is called "PV" (pointer value).
191           When converting a Perl "undef" to a C string Perl by default
192           converts it to an empty string.  While this is save, this is not
193           always what is required, because many C interfaces treat NULL as a
194           special case. For this reason the "PVnull" type is introduced,
195           which converts "undef" to "NULL" and "NULL" to "undef".
196
197           To make it work you need the following line in your type map file:
198
199                   PVnull          | PVnull | | | strdup
200
201           Now you can defines any type, structure memeber or function
202           argument as type "PVnull".
203
204   Functions map file
205       Contains the mapping from C functions to Perl functions. This can be
206       used to reorder arguments, tell XSBuilder which arguments are return
207       values, and in which Perl package the function will be created.
208
209       There are some directives which affect the function mappings that
210       follow it.  Each directive may appear in the file more than once.
211
212       MODULE
213           the module name (file name) where the function should be defined,
214           e.g.
215
216               MODULE=Apache::Connection
217
218           will define the functions that follow in files named
219           Apache/Connection.{pm,xs}
220
221       PACKAGE
222           The name of the package that functions are defined in. If
223           undefined, PACKAGE defaults to the value of MODULE. A value of
224           'guess' indicates that package name should be guessed based on
225           first argument found that maps to a Perl class. Falls back on the
226           prefix (ap_ -> Apache, apr_ -> APR).
227
228       PREFIX
229           The prefix to be stripped from C functions when creating the XS
230           stubs.  Defaults to the value of PACKAGE, converted to C naming
231           convention. For example,
232
233               PREFIX=APR::Base64
234
235           will strip "apr_base64_" from the C functions. If the prefix does
236           not match, it defaults to "ap_" or "apr_".
237
238       NOTE: You must have at least one "MODULE" definition otherwise all
239       functions will be ignored.
240
241       The format of entries is:
242
243           C function name | dispatch function name (dispatch argspec) | argspec | Perl alias
244
245       The "dispatch function name" (the C function that is actually called)
246       defaults to C function name. If the dispatch function name is just a
247       prefix (mpxs_, MPXS_), the "C function name" is appended to it. The
248       return type may be specified before the "C function name", and defaults
249       to the "return_type" in the "{foo}::FunctionTable" module generated by
250       the "ParseSource" module.
251
252       The "dispatch argspec" is optional. If supplied, it can be used to pass
253       different parameters to the dispatch function then to the XS function.
254       If the function name begins with "DEFINE_", a new function is defined
255       (for defining functions that are not parsed from the source). "argspec"
256       must be supplied.  "DEFINE_" is not included in the generated function
257       name.
258
259       The "argspec" defaults to arguments in "{foo}::FunctionTable", as
260       generated by the "ParseSource" module. Argument types can be specified
261       to override those in the "{foo}::FunctionTable". Default values can
262       also be specified, e.g. arg=default_value
263
264       For example:
265         ap_get_client_block   | mpxs_ | r, SV *:buffer, bufsiz
266         ap_setup_client_block |       | r, read_policy=REQUEST_CHUNKED_ERROR
267         ap_make_array      | ap_make_array(r->pool, nelts, elt_size) |
268       request_rec *:r, nelts, elt_size
269
270       argspec of '...' indicates passthru, calling the function with
271
272           (aTHX_ I32 items, SP **sp, SV **MARK)
273
274       To mark an argument as return only you can prefix it with < e.g.
275
276           dav_open_lockdb | | r, ro, <lockdb
277
278       will be called as ($error get the return value of the C function)
279
280           ($error, $lockdb) = $r -> open_lockdb (0) ;
281
282       The return argument (e.g. lockdb) will always be passed by address to
283       the function.
284
285       The function alias, if defined, will be created in the current
286       "PACKAGE".
287
288       Function names on lines that do not begin with a word character or a
289       single space are skipped. Function names can be prefixed with the
290       following symbols:
291
292           '!' => 'disabled or not yet implemented',
293           '~' => 'implemented but not auto-generated',
294           '-' => 'likely never be available to Perl',
295           '>' => '"private" to your C library',
296           '?' => 'unclassified',
297
298   Structures map file
299       Contains the mapping from C structures to Perl classes and defines the
300       members for which access methods should be created. A "new" method may
301       be specified, if desired. The format looks like the following:
302
303           <struct_name>
304             member1
305             member2
306             new
307           </struct_name>
308
309       An optional module name can be given, to specify in which module the
310       code should be placed. To place the structure in My::Module, for
311       example, specify:
312
313           <struct_name MODULE=My::Module>
314
315       For all members that are listed here, XSBuilder will generate an access
316       method to read and write it's content. If you want to name the perl
317       access method differently than the C member, you can write
318
319          cMemberValue | member_value | type
320
321       this will map the "cMemberValue" structure member to the access
322       function "member_value". The default is to use the same name in Perl as
323       in C.  As third argument you can give a typename. This defaults to the
324       type of the variable. It can be used to specify a different type, for
325       special conversion needs.  (e.g. PV versus PVnull) If you give the
326       "new" member, XSBuilder will create a new method for that class, which
327       can be used to create a new instance and initialize it with data.
328
329   Callbacks map file
330       The format of entries is:
331
332           C function name | argspec
333
334       The content is the same as function map, it but contains the callbacks.
335

Additional generated methods

337       For structures, XSBuilder will generate two additional methods: "new",
338       and "init_callbacks".
339
340   new ($initialvalue)
341       With "new" you can create a new Perl object for an C structure.
342       Optionally, you can pass either a hashref with initial data, or another
343       object, who's data will be copied into the new object.
344
345   init_callbacks
346       "init_callbacks" should be called during object initialization. It will
347       fill in all callback members of a structure with pointers that cause a
348       method call into the object, when the callback is called from C.
349
350       You can call it either with
351
352           $obj -> init_callbacks
353
354       or
355
356           MyModule -> init_callbacks ($obj) ;
357

Callbacks

359       A callback which is part of a structure will cause a call to the method
360       with the same name as the structure member, prefixed with "cb_". For
361       example, if you have a structure member named "open", then the Perl
362       method "cb_open" will be called whenever the C code calls the callback.
363
364       If you want to call the callback on your own you need to call the
365       method which is called like the structure member, e.g. "open".
366
367       NOTE: You need to call "init_callbacks" during your method
368       initialzation to be able to call callbacks.
369
370
371
372perl v5.28.0                      2005-08-30                      XSBuilder(3)
Impressum