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
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 Of course there are more methods you can overide. See
29 ExtUtils::XSBuilder::ParseSource for a full list of overrideable
30 methods.
31 Scan the source files
33 If your derived class is called MyClass::ParseSource you simply start
34 the source scan with
35 perl -MMyClass::ParseSource -e 'MyClass::ParseSource->run'
37 You may also put this into a small script to ease usage, set the Perl
39 libpath, etc.
40 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 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 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 See ExtUtils::XSBuilder::WrapXS for a list of overrideable methods.
63 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 foo_types.map
77 Contains the mapping from C types to Perl classes.
78 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 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 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 For a detailed description of the map file formats see below.
97 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 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 If, for example, your derived class is called MyClass::WrapXS, you
108 simply start the creation/update of the map files with
109 perl -MMyClass::WrapXS -e 'MyClass::WrapXS->checkmaps(" ")'
111 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 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 int | IV
125 struct request_rec | Apache::RequestRec
126 .
128 Create the XS files
130 Now we can create the code. By running
131 perl -MMyClass::WrapXS -e 'MyClass::WrapXS->run'
133 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
148 For all map files blank lines are ignored and lines starting with a "#"
149 are treated as comments and are also ignored.
150 Types map file
152 Contains the mapping from C type to Perl classes.
153 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 int | IV
158 struct request_rec | Apache::RequestRec
159 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 struct request_rec | Apache::RequestRec | T_APACHEOBJ | r
168 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 char * | PV | | | strdup
174 The actual code for memory allocation is provided inside the structure
176 map, for example:
177 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 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 Special Types
187 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 To make it work you need the following line in your type map file:
198 PVnull | PVnull | | | strdup
200 Now you can defines any type, structure memeber or function
202 argument as type "PVnull".
203 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 There are some directives which affect the function mappings that
210 follow it. Each directive may appear in the file more than once.
211 MODULE
213 the module name (file name) where the function should be defined,
214 e.g.
215 MODULE=Apache::Connection
217 will define the functions that follow in files named
219 Apache/Connection.{pm,xs}
220 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 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 PREFIX=APR::Base64
234 will strip "apr_base64_" from the C functions. If the prefix does
236 not match, it defaults to "ap_" or "apr_".
237 NOTE: You must have at least one "MODULE" definition otherwise all
239 functions will be ignored.
240 The format of entries is:
242 C function name | dispatch function name (dispatch argspec) | argspec | Perl alias
244 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 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 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 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 argspec of '...' indicates passthru, calling the function with
271 (aTHX_ I32 items, SP **sp, SV **MARK)
273 To mark an argument as return only you can prefix it with < e.g.
275 dav_open_lockdb | | r, ro, <lockdb
277 will be called as ($error get the return value of the C function)
279 ($error, $lockdb) = $r -> open_lockdb (0) ;
281 The return argument (e.g. lockdb) will always be passed by address to
283 the function.
284 The function alias, if defined, will be created in the current
286 "PACKAGE".
287 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 '!' => '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 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 <struct_name>
304 member1
305 member2
306 new
307 </struct_name>
308 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 <struct_name MODULE=My::Module>
314 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 cMemberValue | member_value | type
320 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 Callbacks map file
330 The format of entries is:
331 C function name | argspec
333 The content is the same as function map, it but contains the callbacks.
335
337 For structures, XSBuilder will generate two additional methods: "new",
338 and "init_callbacks".
339 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 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 You can call it either with
351 $obj -> init_callbacks
353 or
355 MyModule -> init_callbacks ($obj) ;
357
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 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 NOTE: You need to call "init_callbacks" during your method
368 initialzation to be able to call callbacks.
369perl v5.32.0 2020-07-28 XSBuilder(3)