1XSBuilder(3) User Contributed Perl Documentation XSBuilder(3)
2
6 ExtUtils::XSBuilder - Automatic Perl XS glue code generation
7
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 The creation process takes place in the following steps:
19 Derive a class from ExtUtils::XSBuilder::ParseSource
21 This class must override some methods to tell XSBuilder which C header
23 files to parse and some other necessary parameters. You need at least
24 to override the "package" method to give the name of the package you
25 want to create and either the "find_includes" method which returns all
26 C header files to parse, or the "include_dirs" method to return a list
27 of all directories which should be scanned for C header files.
28 Of course there are more methods you can overide. See ExtU‐
30 tils::XSBuilder::ParseSource for a full list of overrideable methods.
31 Scan the source files
33 If your derived class is called MyClass::ParseSource you simply start
35 the source scan with
36 perl -MMyClass::ParseSource -e 'MyClass::ParseSource->run'
38 You may also put this into a small script to ease usage, set the Perl
40 libpath, etc.
41 During the source scan, XSBuilder creates a set of tables which contain
43 the results of parsing. If you haven't changed the default locations in
44 your subclass, these tables are created under "xs/tables", followed by
45 the name of the module returned by the "package" method you created.
46 There you will find four generated modules: "FunctionTable.pm", which
47 holds the function declarations; "StructureTable.pm", which holds the
48 structures; "ConstantTable.pm", which contains constants found in the
49 header files; and "CallbackTable.pm", which contains definitions for
50 callback types.
51 Since source scanning may take some time, we create intermediate tables
53 and transform them into XS code later, rather than creating XS code
54 directly. Since we save the result, we can avoid rescanning the source
55 files as long as they don't change.
56 Derive a class from ExtUtils::XSBuilder::WrapXS
58 The WrapXS class is responsible for taking the information generated
60 both from the source files and from the map files (see below) to create
61 the XS code. As with the ParseSource class, you must override this
62 method with your own implementaion, to tell WrapXS what to do.
63 See ExtUtils::XSBuilder::WrapXS for a list of overrideable methods.
65 Create map files
67 XSBuilder will not automaticly create XS functions for all C functions
69 and structures. You must provide hints in order for the XS files to be
70 created properly. The map files are the mechanism to provide these
71 hints. By default, the map files are found under "xs/maps". There are
72 four map types, "types", "functions", "structures", and "callbacks".
73 Each map file is named with a user selectable prefix (e.g. "foo",) fol‐
74 lowed by an underscore, the map type name, and the map extension
75 ".map". For example, hints for functions relating to error processing
76 in your source may be contained in a map file named "error_func‐
77 tions.map".
78 foo_types.map
80 Contains the mapping from C types to Perl classes.
81 foo_functions.map
83 Contains the mapping from C functions to Perl functions. Can be
84 used to reorder arguments, tell XSBuilder which arguments are actu‐
85 aly return values and in which Perl package the function will be
86 created.
87 foo_structures.map
89 Contains the mapping from C structures to Perl classes and defines
90 for which classes the access methods should be created. You can
91 also specify if you want a "new" method for the class.
92 foo_callbacks.map
94 Contains the mapping form C callback functions to Perl callback
95 functions. Can be used to reorder arguments, tell XSBuilder which
96 arguments are return values, and in which Perl package the func‐
97 tions will be created.
98 For a detailed description of the map file formats see below.
100 To have a starting point, XSBuilder is able to create default map files
102 which simply include all types, functions and structures. You can
103 recreate the map files anytime and XSBuilder will append all items
104 which are not already in the map files.
105 First copy the _types.map file from the xsbuilder directory to your
107 maps directory. This file contains the standard mapping for some basic
108 types.
109 If, for example, your derived class is called MyClass::WrapXS, you sim‐
111 ply start the creation/update of the map files with
112 perl -MMyClass::WrapXS -e 'MyClass::WrapXS->checkmaps(" ")'
114 The argument to checkmaps supplies a character to be prepended to the
116 first column of the new map entries. If you do not pass an argument to
117 checkmaps, no map files are written, and checkmaps will only compare
118 what is missing. (You need to print the result somehow e.g. by using
119 Data::Dumper). You may also put this into a small script to ease usage,
120 set the Perl libpath, etc.
121 After you have created your default maps, you must edit the
123 "xs/maps/new_type.map" file, which contains all types that were found
124 in the source. Append a pipe ("⎪") followed by the class or type name,
125 e.g.
126 int ⎪ IV
128 struct request_rec ⎪ Apache::RequestRec
129 .
131 Create the XS files
133 Now we can create the code. By running
135 perl -MMyClass::WrapXS -e 'MyClass::WrapXS->run'
137 XSBuilder will create the XS, pm and Makefile.PL files for every module
139 that is mentioned in the maps. The result is placed as a directory
140 hierarchy under WrapXS. To control the content of the "Makefile.PL" and
141 the "pm" file, you can override the "makefilepl_text" and "pm_text"
142 methods. You can include additional code in the XS files by writing an
143 include file which is included at the top of the XS file. This file can
144 contain helper functions that can't be automatically generated. The
145 files must be placed under the "xs" directory, with the correct path
146 and name. For example, to have a header file included for the module
147 Apache::DAV, create a file named "xs/Apache/DAV/Apache__DAV.h". The
148 same can be done for inclusion in the pm file. Following the example
149 above, the file name would be "xs/Apache/DAV/DAV_pm".
150
152 For all map files blank lines are ignored and lines starting with a "#"
153 are treated as comments and are also ignored.
154 Types map file
156 Contains the mapping from C type to Perl classes.
158 Format is the name of the C type followed by the name of the Perl class
160 or the XS type specifier, separated by a "⎪". Example:
161 int ⎪ IV
163 struct request_rec ⎪ Apache::RequestRec
164 If you have a Perl class with a single-level namespace (e.g. Apache)
166 you need to postfix it with two colons (e.g. "Apache::"). When both a
167 typedef and a structure share the same name, structures must be written
168 as with a "struct " prefix (e.g. "struct foo".) Addionally, you can
169 give the id for the typemap if you need a special conversion and one or
170 more other names for the struct:
171 struct request_rec ⎪ Apache::RequestRec ⎪ T_APACHEOBJ ⎪ r
173 An optional fifth parameter specifies that the data needs to be copied
175 when assigned to a struct member and selects the way how memory is
176 allocated:
177 char * ⎪ PV ⎪ ⎪ ⎪ strdup
179 The actual code for memory allocation is provided inside the structure
181 map, for example:
182 MALLOC=strdup:$dest = ($type)ap_pstrdup(obj -> pool, $src)
184 MALLOC=malloc:ap_palloc(obj -> pool, $src, sizeof($type)) ; memcpy($dest,$src,sizeof($type))
185 This gives two ways to allocate memory and copy the data into it. The
187 fifth parameter in the type map selects which of these two should be
188 used. $src, $dest and $type are replaced by the source, the destination
189 and the type. "obj" is a pointer to the C-structure.
190 Special Types
192 String, PV and PVnull
194 A string is represented in C as a pointer to an null terminated
195 range of characters. In Perl the it is called "PV" (pointer value).
196 When converting a Perl "undef" to a C string Perl by default con‐
197 verts it to an empty string. While this is save, this is not
198 always what is required, because many C interfaces treat NULL as a
199 special case. For this reason the "PVnull" type is introduced,
200 which converts "undef" to "NULL" and "NULL" to "undef".
201 To make it work you need the following line in your type map file:
203 PVnull ⎪ PVnull ⎪ ⎪ ⎪ strdup
205 Now you can defines any type, structure memeber or function argu‐
207 ment as type "PVnull".
208 Functions map file
210 Contains the mapping from C functions to Perl functions. This can be
212 used to reorder arguments, tell XSBuilder which arguments are return
213 values, and in which Perl package the function will be created.
214 There are some directives which affect the function mappings that fol‐
216 low it. Each directive may appear in the file more than once.
217 MODULE
219 the module name (file name) where the function should be defined,
220 e.g.
221 MODULE=Apache::Connection
223 will define the functions that follow in files named Apache/Connec‐
225 tion.{pm,xs}
226 PACKAGE
228 The name of the package that functions are defined in. If unde‐
229 fined, PACKAGE defaults to the value of MODULE. A value of 'guess'
230 indicates that package name should be guessed based on first argu‐
231 ment found that maps to a Perl class. Falls back on the prefix (ap_
232 -> Apache, apr_ -> APR).
233 PREFIX
235 The prefix to be stripped from C functions when creating the XS
236 stubs. Defaults to the value of PACKAGE, converted to C naming
237 convention. For example,
238 PREFIX=APR::Base64
240 will strip "apr_base64_" from the C functions. If the prefix does
242 not match, it defaults to "ap_" or "apr_".
243 NOTE: You must have at least one "MODULE" definition otherwise all
245 functions will be ignored.
246 The format of entries is:
248 C function name ⎪ dispatch function name (dispatch argspec) ⎪ argspec ⎪ Perl alias
250 The "dispatch function name" (the C function that is actually called)
252 defaults to C function name. If the dispatch function name is just a
253 prefix (mpxs_, MPXS_), the "C function name" is appended to it. The
254 return type may be specified before the "C function name", and defaults
255 to the "return_type" in the "{foo}::FunctionTable" module generated by
256 the "ParseSource" module.
257 The "dispatch argspec" is optional. If supplied, it can be used to pass
259 different parameters to the dispatch function then to the XS function.
260 If the function name begins with "DEFINE_", a new function is defined
261 (for defining functions that are not parsed from the source). "argspec"
262 must be supplied. "DEFINE_" is not included in the generated function
263 name.
264 The "argspec" defaults to arguments in "{foo}::FunctionTable", as gen‐
266 erated by the "ParseSource" module. Argument types can be specified to
267 override those in the "{foo}::FunctionTable". Default values can also
268 be specified, e.g. arg=default_value
269 For example:
271 ap_get_client_block ⎪ mpxs_ ⎪ r, SV *:buffer, bufsiz
272 ap_setup_client_block ⎪ ⎪ r, read_policy=REQUEST_CHUNKED_ERROR
273 ap_make_array ⎪ ap_make_array(r->pool, nelts, elt_size) ⎪
274 request_rec *:r, nelts, elt_size
275 argspec of '...' indicates passthru, calling the function with
277 (aTHX_ I32 items, SP **sp, SV **MARK)
279 To mark an argument as return only you can prefix it with < e.g.
281 dav_open_lockdb ⎪ ⎪ r, ro, <lockdb
283 will be called as ($error get the return value of the C function)
285 ($error, $lockdb) = $r -> open_lockdb (0) ;
287 The return argument (e.g. lockdb) will always be passed by address to
289 the function.
290 The function alias, if defined, will be created in the current "PACK‐
292 AGE".
293 Function names on lines that do not begin with a word character or a
295 single space are skipped. Function names can be prefixed with the fol‐
296 lowing symbols:
297 '!' => 'disabled or not yet implemented',
299 '~' => 'implemented but not auto-generated',
300 '-' => 'likely never be available to Perl',
301 '>' => '"private" to your C library',
302 '?' => 'unclassified',
303 Structures map file
305 Contains the mapping from C structures to Perl classes and defines the
307 members for which access methods should be created. A "new" method may
308 be specified, if desired. The format looks like the following:
309 <struct_name>
311 member1
312 member2
313 new
314 </struct_name>
315 An optional module name can be given, to specify in which module the
317 code should be placed. To place the structure in My::Module, for exam‐
318 ple, specify:
319 <struct_name MODULE=My::Module>
321 For all members that are listed here, XSBuilder will generate an access
323 method to read and write it's content. If you want to name the perl
324 access method differently than the C member, you can write
325 cMemberValue ⎪ member_value ⎪ type
327 this will map the "cMemberValue" structure member to the access func‐
329 tion "member_value". The default is to use the same name in Perl as in
330 C. As third argument you can give a typename. This defaults to the
331 type of the variable. It can be used to specify a different type, for
332 special conversion needs. (e.g. PV versus PVnull) If you give the
333 "new" member, XSBuilder will create a new method for that class, which
334 can be used to create a new instance and initialize it with data.
335 Callbacks map file
337 The format of entries is:
339 C function name ⎪ argspec
341 The content is the same as function map, it but contains the callbacks.
343
345 For structures, XSBuilder will generate two additional methods: "new",
346 and "init_callbacks".
347 new ($initialvalue)
349 With "new" you can create a new Perl object for an C structure. Option‐
351 ally, you can pass either a hashref with initial data, or another
352 object, who's data will be copied into the new object.
353 init_callbacks
355 "init_callbacks" should be called during object initialization. It will
357 fill in all callback members of a structure with pointers that cause a
358 method call into the object, when the callback is called from C.
359 You can call it either with
361 $obj -> init_callbacks
363 or
365 MyModule -> init_callbacks ($obj) ;
367
369 A callback which is part of a structure will cause a call to the method
370 with the same name as the structure member, prefixed with "cb_". For
371 example, if you have a structure member named "open", then the Perl
372 method "cb_open" will be called whenever the C code calls the callback.
373 If you want to call the callback on your own you need to call the
375 method which is called like the structure member, e.g. "open".
376 NOTE: You need to call "init_callbacks" during your method initialza‐
378 tion to be able to call callbacks.
379perl v5.8.8 2005-08-31 XSBuilder(3)