Debian Codegraph @

dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS.pod

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