Penguin
Recent Changes
Annotated edit history of h2xs(1) version 2, including all changes. View license author blame.
Rev Author # Line
1 perry 1 H2XS
2 !!!H2XS
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 OPTIONS
7 EXAMPLES
8 ENVIRONMENT
9 AUTHOR
10 SEE ALSO
11 DIAGNOSTICS
12 LIMITATIONS of -x
13 ----
14 !!NAME
15
16
17 h2xs - convert .h C header files to Perl extensions
18 !!SYNOPSIS
19
20
21 __h2xs__ [[__-ACOPXacdfkmx__] [[__-F__ addflags]
22 [[__-M__ fmask] [[__-n__ module_name] [[__-o__ tmask]
23 [[__-p__ prefix] [[__-s__ subs] [[__-v__ version]
24 [[headerfile ... [[extra_libraries]]
25
26
27 __h2xs -h__
28 !!DESCRIPTION
29
30
31 ''h2xs'' builds a Perl extension from C header files. The
32 extension will include functions which can be used to
33 retrieve the value of any #define statement which was in the
34 C header files.
35
36
37 The ''module_name'' will be used for the name of the
38 extension. If module_name is not supplied then the name of
39 the first header file will be used, with the first character
40 capitalized.
41
42
43 If the extension might need extra libraries, they should be
44 included here. The extension Makefile.PL will take care of
45 checking whether the libraries actually exist and how they
46 should be loaded. The extra libraries should be specified in
47 the form -lm -lposix, etc, just as on the cc command line.
48 By default, the Makefile.PL will search through the library
49 path determined by Configure. That path can be augmented by
50 including arguments of the form
51 __-L/another/library/path__ in the extra-libraries
52 argument.
53 !!OPTIONS
54
55
56 __-A__
57
58
59 Omit all autoload facilities. This is the same as __-c__
2 perry 60 but also removes the use !AutoLoader statement from
1 perry 61 the .pm file.
62
63
64 __-C__
65
66
67 Omits creation of the ''Changes'' file, and adds a
68 HISTORY section to the POD
69 template.
70
71
72 __-F__ ''addflags''
73
74
75 Additional flags to specify to C preprocessor when scanning
76 header for function declarations. Should not be used without
77 __-x__.
78
79
80 __-M__ ''regular expression''
81
82
83 selects functions/macros to process.
84
85
86 __-O__
87
88
89 Allows a pre-existing extension directory to be
90 overwritten.
91
92
93 __-P__
94
95
96 Omit the autogenerated stub POD
97 section.
98
99
100 __-X__
101
102
103 Omit the XS portion. Used to generate
104 templates for a module which is not XS-based. -c
105 and -f are implicitly enabled.
106
107
108 __-a__
109
110
111 Generate an accessor method for each element of structs and
112 unions. The generated methods are named after the element
113 name; will return the current value of the element if called
114 without additional arguments; and will set the element to
115 the supplied value (and return the new value) if called with
116 an additional argument. Embedded structures and unions are
117 returned as a pointer rather than the complete structure, to
118 facilitate chained calls.
119
120
121 These methods all apply to the Ptr type for the structure;
122 additionally two methods are constructed for the structure
123 type itself, _to_ptr which returns a Ptr type
124 pointing to the same structure, and a new method to
125 construct and return a new structure, initialised to
126 zeroes.
127
128
129 __-c__
130
131
132 Omit constant() from the .xs file and corresponding
133 specialised AUTOLOAD from the .pm
134 file.
135
136
137 __-d__
138
139
140 Turn on debugging messages.
141
142
143 __-f__
144
145
146 Allows an extension to be created for a header even if that
147 header is not found in standard include
148 directories.
149
150
151 __-h__
152
153
154 Print the usage, help and version for this h2xs and
155 exit.
156
157
158 __-k__
159
160
161 For function arguments declared as const, omit the
162 const attribute in the generated XS
163 code.
164
165
166 __-m__
167
168
169 __Experimental__: for each variable declared in the
170 header file(s), declare a perl variable of the same name
171 magically tied to the C variable.
172
173
174 __-n__ ''module_name''
175
176
177 Specifies a name to be used for the extension, e.g., -n
178 RPC::DCE
179
180
181 __-o__ ''regular expression''
182
183
184 Use ``opaque'' data type for the C types matched by the
185 regular expression, even if these types are
186 typedef-equivalent to types from typemaps. Should
187 not be used without __-x__.
188
189
190 This may be useful since, say, types which are
191 typedef-equivalent to integers may represent
192 OS-related handles, and one may want to work with these
193 handles in OO-way, as in
194 $handle-. Use -o . if
195 you want to handle all the typedefed types as
196 opaque types.
197
198
199 The type-to-match is whitewashed (except for commas, which
200 have no whitespace before them, and multiple *
201 which have no whitespace between them).
202
203
204 __-p__ ''prefix''
205
206
207 Specify a prefix which should be removed from the Perl
208 function names, e.g., -p sec_rgy_ This sets up the XS
209 __PREFIX__ keyword and removes the prefix from
210 functions that are autoloaded via the constant()
211 mechanism.
212
213
214 __-s__ ''sub1,sub2''
215
216
217 Create a perl subroutine for the specified macros rather
218 than autoload with the ''constant()'' subroutine. These
219 macros are assumed to have a return type of __char *__,
220 e.g., -s
221 sec_rgy_wildcard_name,sec_rgy_wildcard_sid.
222
223
224 __-v__ ''version''
225
226
227 Specify a version number for this extension. This version
228 number is added to the templates. The default is
229 0.01.
230
231
232 __-x__
233
234
235 Automatically generate XSUBs basing on function declarations
236 in the header file. The package C::Scan should be
237 installed. If this option is specified, the name of the
238 header file may look like NAME1,NAME2. In this case
239 NAME1 is used instead of the specified
240 string, but XSUBs are emitted only for the declarations
241 included from file NAME2 .
242
243
244 Note that some types of arguments/return-values for
245 functions may result in XSUB-declarations/typemap-entries
246 which need hand-editing. Such may be objects which cannot be
247 converted from/to a pointer (like long long),
248 pointers to functions, or arrays. See also the section on
249 LIMITATIONS of
250 __-x____
251
252
253 __-b__ ''version''
254
255
256 Generates a .pm file which is backwards compatible with the
257 specified perl version.
258
259
260 For versions
261
262
263 Specifying a compatibility version higher than the version
264 of perl you are using to run h2xs will have no
265 effect.
266 !!EXAMPLES
267
268
269 # Default behavior, extension is Rusers
270 h2xs rpcsvc/rusers
271 # Same, but extension is RUSERS
272 h2xs -n RUSERS rpcsvc/rusers
273 # Extension is rpcsvc::rusers. Still finds
274 # Extension is ONC::RPC. Still finds
275 # Without constant() or AUTOLOAD
276 h2xs -c rpcsvc/rusers
277 # Creates templates for an extension named RPC
278 h2xs -cfn RPC
279 # Extension is ONC::RPC.
280 h2xs -cfn ONC::RPC
281 # Makefile.PL will look for library -lrpc in
282 # additional directory /opt/net/lib
283 h2xs rpcsvc/rusers -L/opt/net/lib -lrpc
284 # Extension is DCE::rgynbase
285 # prefix
286 # Extension is DCE::rgynbase
287 # prefix
288 # Make XS without defines in perl.h, but with function declarations
289 # visible from perl.h. Name of the extension is perl1.
290 # When scanning perl.h, define -DEXT=extern -DdEXT= -DINIT(x)=
291 # Extra backslashes below because the string is passed to shell.
292 # Note that a directory with perl header files would
293 # be added automatically to include path.
294 h2xs -xAn perl1 -F
295 # Same with function declaration in proto.h as visible from perl.h.
296 h2xs -xAn perl2 perl.h,proto.h
297 # Same but select only functions which match /^av_/
298 h2xs -M '^av_' -xAn perl2 perl.h,proto.h
299 # Same but treat SV* etc as
300
301
302 __Extension based on__ ''.h'' __and__ ''.c''
303 __files__
304
305
306 Suppose that you have some C files implementing some
307 functionality, and the corresponding header files. How to
308 create an extension which makes this functionality
309 accessable in Perl? The example below assumes that the
310 header files are ''interface_simple.h'' and
311 ''interface_hairy.h'', and you want the perl module be
312 named as Ext::Ension. If you need some preprocessor
313 directives and/or linking with external libraries, see the
314 flags -F, -L and -l in ``
315 OPTIONS ''.
316
317
318 Find the directory name
319
320
321 Start with a dummy run of h2xs:
322
323
324 h2xs -Afn Ext::Ension
325 The only purpose of this step is to create the needed directories, and let you know the names of these directories. From the output you can see that the directory for the extension is ''Ext/Ension''.
326
327
328 Copy C files
329
330
331 Copy your header files and C files to this directory
332 ''Ext/Ension''.
333
334
335 Create the extension
336
337
338 Run h2xs, overwriting older autogenerated
339 files:
340
341
342 h2xs -Oxan Ext::Ension interface_simple.h interface_hairy.h
343 h2xs looks for header files ''after'' changing to the extension directory, so it will find your header files OK .
344
345
346 Archive and test
347
348
349 As usual, run
350
351
352 cd Ext/Ension
353 perl Makefile.PL
354 make dist
355 make
356 make test
357
358
359 Hints
360
361
362 It is important to do make dist as early as
363 possible. This way you can easily merge(1) your
364 changes to autogenerated files if you decide to edit your
365 .h files and rerun h2xs.
366
367
368 Do not forget to edit the documentation in the generated
369 ''.pm'' file.
370
371
372 Consider the autogenerated files as skeletons only, you may
373 invent better interfaces than what h2xs could
374 guess.
375
376
377 Consider this section as a guideline only, some other
378 options of h2xs may better suit your needs.
379 !!ENVIRONMENT
380
381
382 No environment variables are used.
383 !!AUTHOR
384
385
386 Larry Wall and others
387 !!SEE ALSO
388
389
2 perry 390 perl, perlxstut, !ExtUtils::!MakeMaker, and
391 !AutoLoader.
1 perry 392 !!DIAGNOSTICS
393
394
395 The usual warnings if it cannot read or write the files
396 involved.
397 !!LIMITATIONS of -x
398
399
400 ''h2xs'' would not distinguish whether an argument to a C
401 function which is of the form, say, int *, is an
402 input, output, or input/output parameter. In particular,
403 argument declarations of the form
404
405
406 int
407 foo(n)
408 int *n
409 should be better rewritten as
410
411
412 int
413 foo(n)
414 int
415 if n is an input parameter.
416
417
418 Additionally, ''h2xs'' has no facilities to intuit that a
419 function
420
421
422 int
423 foo(addr,l)
424 char *addr
425 int l
426 takes a pair of address and length of data at this address, so it is better to rewrite this function as
427
428
429 int
430 foo(sv)
431 SV *addr
432 PREINIT:
433 STRLEN len;
434 char *s;
435 CODE:
436 s = SvPV(sv,len);
437 RETVAL = foo(s, len);
438 OUTPUT:
439 RETVAL
440 or alternately
441
442
443 static int
444 my_foo(SV *sv)
445 {
446 STRLEN len;
447 char *s = SvPV(sv,len);
448 return foo(s, len);
449 }
450 MODULE = foo PACKAGE = foo PREFIX = my_
451 int
452 foo(sv)
453 SV *sv
454 See perlxs and perlxstut for additional details.
455 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.