ExtUtils::ParseXS(3pm)

1ExtUtils::ParseXS(3)  User Contributed Perl Documentation ExtUtils::ParseXS(3)
2
3
4

NAME

6       ExtUtils::ParseXS - converts Perl XS code into C code
7

SYNOPSIS

9         use ExtUtils::ParseXS;
10
11         my $pxs = ExtUtils::ParseXS->new;
12         $pxs->process_file( filename => 'foo.xs' );
13
14         $pxs->process_file( filename => 'foo.xs',
15                             output => 'bar.c',
16                             'C++' => 1,
17                             typemap => 'path/to/typemap',
18                             hiertype => 1,
19                             except => 1,
20                             versioncheck => 1,
21                             linenumbers => 1,
22                             optimize => 1,
23                             prototypes => 1,
24                             die_on_error => 0,
25                           );
26
27         # Legacy non-OO interface using a singleton:
28         use ExtUtils::ParseXS qw(process_file);
29         process_file( filename => 'foo.xs' );
30

DESCRIPTION

32       "ExtUtils::ParseXS" will compile XS code into C code by embedding the
33       constructs necessary to let C functions manipulate Perl values and
34       creates the glue necessary to let Perl access those functions.  The
35       compiler uses typemaps to determine how to map C function parameters
36       and variables to Perl values.
37
38       The compiler will search for typemap files called typemap.  It will use
39       the following search path to find default typemaps, with the rightmost
40       typemap taking precedence.
41
42           ../../../typemap:../../typemap:../typemap:typemap
43

EXPORT

45       None by default.  process_file() and/or report_error_count() may be
46       exported upon request. Using the functional interface is discouraged.
47

METHODS

49       $pxs->new()
50           Returns a new, empty XS parser/compiler object.
51
52       $pxs->process_file()
53           This method processes an XS file and sends output to a C file.  The
54           method may be called as a function (this is the legacy interface)
55           and will then use a singleton as invocant.
56
57           Named parameters control how the processing is done.  The following
58           parameters are accepted:
59
60           C++ Adds "extern "C"" to the C code.  Default is false.
61
62           hiertype
63               Retains "::" in type names so that C++ hierarchical types can
64               be mapped.  Default is false.
65
66           except
67               Adds exception handling stubs to the C code.  Default is false.
68
69           typemap
70               Indicates that a user-supplied typemap should take precedence
71               over the default typemaps.  A single typemap may be specified
72               as a string, or multiple typemaps can be specified in an array
73               reference, with the last typemap having the highest precedence.
74
75           prototypes
76               Generates prototype code for all xsubs.  Default is false.
77
78           versioncheck
79               Makes sure at run time that the object file (derived from the
80               ".xs" file) and the ".pm" files have the same version number.
81               Default is true.
82
83           linenumbers
84               Adds "#line" directives to the C output so error messages will
85               look like they came from the original XS file.  Default is
86               true.
87
88           optimize
89               Enables certain optimizations.  The only optimization that is
90               currently affected is the use of targets by the output C code
91               (see perlguts).  Not optimizing may significantly slow down the
92               generated code, but this is the way xsubpp of 5.005 and earlier
93               operated.  Default is to optimize.
94
95           inout
96               Enable recognition of "IN", "OUT_LIST" and "INOUT_LIST"
97               declarations.  Default is true.
98
99           argtypes
100               Enable recognition of ANSI-like descriptions of function
101               signature.  Default is true.
102
103           s   Maintainer note: I have no clue what this does.  Strips
104               function prefixes?
105
106           die_on_error
107               Normally ExtUtils::ParseXS will terminate the program with an
108               exit(1) after printing the details of the exception to STDERR
109               via (warn). This can be awkward when it is used
110               programmatically and not via xsubpp, so this option can be used
111               to cause it to die instead by providing a true value. When not
112               provided this defaults to the value of
113               $ExtUtils::ParseXS::DIE_ON_ERROR which in turn defaults to
114               false.
115
116       $pxs->report_error_count()
117           This method returns the number of [a certain kind of] errors
118           encountered during processing of the XS file.
119
120           The method may be called as a function (this is the legacy
121           interface) and will then use a singleton as invocant.
122

AUTHOR

124       Based on xsubpp code, written by Larry Wall.
125
126       Maintained by:
127
128       •   Ken Williams, <ken@mathforum.org>
129
130       •   David Golden, <dagolden@cpan.org>
131
132       •   James Keenan, <jkeenan@cpan.org>
133
134       •   Steffen Mueller, <smueller@cpan.org>
135

COPYRIGHT

137       Copyright 2002-2014 by Ken Williams, David Golden and other
138       contributors.  All rights reserved.
139
140       This library is free software; you can redistribute it and/or modify it
141       under the same terms as Perl itself.
142
143       Based on the "ExtUtils::xsubpp" code by Larry Wall and the Perl 5
144       Porters, which was released under the same license terms.
145