Debian Codegraph @

upstream/debian-unstable/man3/ExtUtils::ParseXS.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "ExtUtils::ParseXS 3perl"
58 .TH ExtUtils::ParseXS 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 ExtUtils::ParseXS \- converts Perl XS code into C code
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& use ExtUtils::ParseXS;
69 \&
70 \& my $pxs = ExtUtils::ParseXS\->new;
71 \& $pxs\->process_file( filename => \*(Aqfoo.xs\*(Aq );
72 \&
73 \& $pxs\->process_file( filename => \*(Aqfoo.xs\*(Aq,
74 \& output => \*(Aqbar.c\*(Aq,
75 \& \*(AqC++\*(Aq => 1,
76 \& typemap => \*(Aqpath/to/typemap\*(Aq,
77 \& hiertype => 1,
78 \& except => 1,
79 \& versioncheck => 1,
80 \& linenumbers => 1,
81 \& optimize => 1,
82 \& prototypes => 1,
83 \& die_on_error => 0,
84 \& );
85 \&
86 \& # Legacy non\-OO interface using a singleton:
87 \& use ExtUtils::ParseXS qw(process_file);
88 \& process_file( filename => \*(Aqfoo.xs\*(Aq );
89 .Ve
90 .SH DESCRIPTION
91 .IX Header "DESCRIPTION"
92 \&\f(CW\*(C`ExtUtils::ParseXS\*(C'\fR will compile XS code into C code by embedding the constructs
93 necessary to let C functions manipulate Perl values and creates the glue
94 necessary to let Perl access those functions. The compiler uses typemaps to
95 determine how to map C function parameters and variables to Perl values.
96 .PP
97 The compiler will search for typemap files called \fItypemap\fR. It will use
98 the following search path to find default typemaps, with the rightmost
99 typemap taking precedence.
100 .PP
101 .Vb 1
102 \& ../../../typemap:../../typemap:../typemap:typemap
103 .Ve
104 .SH EXPORT
105 .IX Header "EXPORT"
106 None by default. \f(CWprocess_file()\fR and/or \f(CWreport_error_count()\fR
107 may be exported upon request. Using the functional interface is
108 discouraged.
109 .SH METHODS
110 .IX Header "METHODS"
111 .ie n .IP $pxs\->\fBnew()\fR 4
112 .el .IP \f(CW$pxs\fR\->\fBnew()\fR 4
113 .IX Item "$pxs->new()"
114 Returns a new, empty XS parser/compiler object.
115 .ie n .IP $pxs\->\fBprocess_file()\fR 4
116 .el .IP \f(CW$pxs\fR\->\fBprocess_file()\fR 4
117 .IX Item "$pxs->process_file()"
118 This method processes an XS file and sends output to a C file.
119 The method may be called as a function (this is the legacy
120 interface) and will then use a singleton as invocant.
121 .Sp
122 Named parameters control how the processing is done.
123 The following parameters are accepted:
124 .RS 4
125 .IP \fBC++\fR 4
126 .IX Item "C++"
127 Adds \f(CW\*(C`extern "C"\*(C'\fR to the C code. Default is false.
128 .IP \fBhiertype\fR 4
129 .IX Item "hiertype"
130 Retains \f(CW\*(C`::\*(C'\fR in type names so that C++ hierarchical types can be
131 mapped. Default is false.
132 .IP \fBexcept\fR 4
133 .IX Item "except"
134 Adds exception handling stubs to the C code. Default is false.
135 .IP \fBtypemap\fR 4
136 .IX Item "typemap"
137 Indicates that a user-supplied typemap should take precedence over the
138 default typemaps. A single typemap may be specified as a string, or
139 multiple typemaps can be specified in an array reference, with the
140 last typemap having the highest precedence.
141 .IP \fBprototypes\fR 4
142 .IX Item "prototypes"
143 Generates prototype code for all xsubs. Default is false.
144 .IP \fBversioncheck\fR 4
145 .IX Item "versioncheck"
146 Makes sure at run time that the object file (derived from the \f(CW\*(C`.xs\*(C'\fR
147 file) and the \f(CW\*(C`.pm\*(C'\fR files have the same version number. Default is
148 true.
149 .IP \fBlinenumbers\fR 4
150 .IX Item "linenumbers"
151 Adds \f(CW\*(C`#line\*(C'\fR directives to the C output so error messages will look
152 like they came from the original XS file. Default is true.
153 .IP \fBoptimize\fR 4
154 .IX Item "optimize"
155 Enables certain optimizations. The only optimization that is currently
156 affected is the use of \fItarget\fRs by the output C code (see perlguts).
157 Not optimizing may significantly slow down the generated code, but this is the way
158 \&\fBxsubpp\fR of 5.005 and earlier operated. Default is to optimize.
159 .IP \fBinout\fR 4
160 .IX Item "inout"
161 Enable recognition of \f(CW\*(C`IN\*(C'\fR, \f(CW\*(C`OUT_LIST\*(C'\fR and \f(CW\*(C`INOUT_LIST\*(C'\fR
162 declarations. Default is true.
163 .IP \fBargtypes\fR 4
164 .IX Item "argtypes"
165 Enable recognition of ANSI-like descriptions of function signature.
166 Default is true.
167 .IP \fBs\fR 4
168 .IX Item "s"
169 \&\fIMaintainer note:\fR I have no clue what this does. Strips function prefixes?
170 .IP \fBdie_on_error\fR 4
171 .IX Item "die_on_error"
172 Normally ExtUtils::ParseXS will terminate the program with an \f(CWexit(1)\fR after
173 printing the details of the exception to STDERR via (warn). This can be awkward
174 when it is used programmatically and not via xsubpp, so this option can be used
175 to cause it to die instead by providing a true value. When not provided this
176 defaults to the value of \f(CW$ExtUtils::ParseXS::DIE_ON_ERROR\fR which in turn
177 defaults to false.
178 .RE
179 .RS 4
180 .RE
181 .ie n .IP $pxs\->\fBreport_error_count()\fR 4
182 .el .IP \f(CW$pxs\fR\->\fBreport_error_count()\fR 4
183 .IX Item "$pxs->report_error_count()"
184 This method returns the number of [a certain kind of] errors
185 encountered during processing of the XS file.
186 .Sp
187 The method may be called as a function (this is the legacy
188 interface) and will then use a singleton as invocant.
189 .SH AUTHOR
190 .IX Header "AUTHOR"
191 Based on xsubpp code, written by Larry Wall.
192 .PP
193 Maintained by:
194 .IP \(bu 4
195 Ken Williams, <[email protected]>
196 .IP \(bu 4
197 David Golden, <[email protected]>
198 .IP \(bu 4
199 James Keenan, <[email protected]>
200 .IP \(bu 4
201 Steffen Mueller, <[email protected]>
202 .SH COPYRIGHT
203 .IX Header "COPYRIGHT"
204 Copyright 2002\-2014 by Ken Williams, David Golden and other contributors. All
205 rights reserved.
206 .PP
207 This library is free software; you can redistribute it and/or
208 modify it under the same terms as Perl itself.
209 .PP
210 Based on the \f(CW\*(C`ExtUtils::xsubpp\*(C'\fR code by Larry Wall and the Perl 5
211 Porters, which was released under the same license terms.
212 .SH "SEE ALSO"
213 .IX Header "SEE ALSO"
214 perl, ExtUtils::xsubpp, ExtUtils::MakeMaker, perlxs, perlxstut.