1=head1 NAME
2
3ExtUtils::ParseXS - converts Perl XS code into C code
4
5=head1 SYNOPSIS
6
7  use ExtUtils::ParseXS;
8
9  my $pxs = ExtUtils::ParseXS->new;
10  $pxs->process_file( filename => 'foo.xs' );
11
12  $pxs->process_file( filename => 'foo.xs',
13                      output => 'bar.c',
14                      'C++' => 1,
15                      typemap => 'path/to/typemap',
16                      hiertype => 1,
17                      except => 1,
18                      versioncheck => 1,
19                      linenumbers => 1,
20                      optimize => 1,
21                      prototypes => 1,
22                      die_on_error => 0,
23                    );
24
25  # Legacy non-OO interface using a singleton:
26  use ExtUtils::ParseXS qw(process_file);
27  process_file( filename => 'foo.xs' );
28
29=head1 DESCRIPTION
30
31C<ExtUtils::ParseXS> will compile XS code into C code by embedding the constructs
32necessary to let C functions manipulate Perl values and creates the glue
33necessary to let Perl access those functions.  The compiler uses typemaps to
34determine how to map C function parameters and variables to Perl values.
35
36The compiler will search for typemap files called I<typemap>.  It will use
37the following search path to find default typemaps, with the rightmost
38typemap taking precedence.
39
40    ../../../typemap:../../typemap:../typemap:typemap
41
42=head1 EXPORT
43
44None by default.  C<process_file()> and/or C<report_error_count()>
45may be exported upon request. Using the functional interface is
46discouraged.
47
48=head1 METHODS
49
50=over 4
51
52=item $pxs->new()
53
54Returns a new, empty XS parser/compiler object.
55
56=item $pxs->process_file()
57
58This method processes an XS file and sends output to a C file.
59The method may be called as a function (this is the legacy
60interface) and will then use a singleton as invocant.
61
62Named parameters control how the processing is done.
63The following parameters are accepted:
64
65=over 4
66
67=item B<C++>
68
69Adds C<extern "C"> to the C code.  Default is false.
70
71=item B<hiertype>
72
73Retains C<::> in type names so that C++ hierarchical types can be
74mapped.  Default is false.
75
76=item B<except>
77
78Adds exception handling stubs to the C code.  Default is false.
79
80=item B<typemap>
81
82Indicates that a user-supplied typemap should take precedence over the
83default typemaps.  A single typemap may be specified as a string, or
84multiple typemaps can be specified in an array reference, with the
85last typemap having the highest precedence.
86
87=item B<prototypes>
88
89Generates prototype code for all xsubs.  Default is false.
90
91=item B<versioncheck>
92
93Makes sure at run time that the object file (derived from the C<.xs>
94file) and the C<.pm> files have the same version number.  Default is
95true.
96
97=item B<linenumbers>
98
99Adds C<#line> directives to the C output so error messages will look
100like they came from the original XS file.  Default is true.
101
102=item B<optimize>
103
104Enables certain optimizations.  The only optimization that is currently
105affected is the use of I<target>s by the output C code (see L<perlguts>).
106Not optimizing may significantly slow down the generated code, but this is the way
107B<xsubpp> of 5.005 and earlier operated.  Default is to optimize.
108
109=item B<inout>
110
111Enable recognition of C<IN>, C<OUT_LIST> and C<INOUT_LIST>
112declarations.  Default is true.
113
114=item B<argtypes>
115
116Enable recognition of ANSI-like descriptions of function signature.
117Default is true.
118
119=item B<s>
120
121I<Maintainer note:> I have no clue what this does.  Strips function prefixes?
122
123=item B<die_on_error>
124
125Normally ExtUtils::ParseXS will terminate the program with an C<exit(1)> after
126printing the details of the exception to STDERR via (warn). This can be awkward
127when it is used programmatically and not via xsubpp, so this option can be used
128to cause it to die instead by providing a true value. When not provided this
129defaults to the value of C<$ExtUtils::ParseXS::DIE_ON_ERROR> which in turn
130defaults to false.
131
132=back
133
134=item $pxs->report_error_count()
135
136This method returns the number of [a certain kind of] errors
137encountered during processing of the XS file.
138
139The method may be called as a function (this is the legacy
140interface) and will then use a singleton as invocant.
141
142=back
143
144=head1 AUTHOR
145
146Based on xsubpp code, written by Larry Wall.
147
148Maintained by:
149
150=over 4
151
152=item *
153
154Ken Williams, <ken@mathforum.org>
155
156=item *
157
158David Golden, <dagolden@cpan.org>
159
160=item *
161
162James Keenan, <jkeenan@cpan.org>
163
164=item *
165
166Steffen Mueller, <smueller@cpan.org>
167
168=back
169
170=head1 COPYRIGHT
171
172Copyright 2002-2014 by Ken Williams, David Golden and other contributors.  All
173rights reserved.
174
175This library is free software; you can redistribute it and/or
176modify it under the same terms as Perl itself.
177
178Based on the C<ExtUtils::xsubpp> code by Larry Wall and the Perl 5
179Porters, which was released under the same license terms.
180
181=head1 SEE ALSO
182
183L<perl>, ExtUtils::xsubpp, ExtUtils::MakeMaker, L<perlxs>, L<perlxstut>.
184
185=cut
186
187
188