Debian Codegraph @

upstream/mageia-cauldron/man3pm/ExtUtils::ParseXS.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (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 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "ExtUtils::ParseXS 3pm"
61 .TH ExtUtils::ParseXS 3pm 2025-06-24 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 ExtUtils::ParseXS \- converts Perl XS code into C code
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use ExtUtils::ParseXS;
72 \&
73 \& my $pxs = ExtUtils::ParseXS\->new;
74 \& $pxs\->process_file( filename => \*(Aqfoo.xs\*(Aq );
75 \&
76 \& $pxs\->process_file( filename => \*(Aqfoo.xs\*(Aq,
77 \& output => \*(Aqbar.c\*(Aq,
78 \& \*(AqC++\*(Aq => 1,
79 \& typemap => \*(Aqpath/to/typemap\*(Aq,
80 \& hiertype => 1,
81 \& except => 1,
82 \& versioncheck => 1,
83 \& linenumbers => 1,
84 \& optimize => 1,
85 \& prototypes => 1,
86 \& die_on_error => 0,
87 \& );
88 \&
89 \& # Legacy non\-OO interface using a singleton:
90 \& use ExtUtils::ParseXS qw(process_file);
91 \& process_file( filename => \*(Aqfoo.xs\*(Aq );
92 .Ve
93 .SH DESCRIPTION
94 .IX Header "DESCRIPTION"
95 \&\f(CW\*(C`ExtUtils::ParseXS\*(C'\fR will compile XS code into C code by embedding the constructs
96 necessary to let C functions manipulate Perl values and creates the glue
97 necessary to let Perl access those functions. The compiler uses typemaps to
98 determine how to map C function parameters and variables to Perl values.
99 .PP
100 The compiler will search for typemap files called \fItypemap\fR. It will use
101 the following search path to find default typemaps, with the rightmost
102 typemap taking precedence.
103 .PP
104 .Vb 1
105 \& ../../../typemap:../../typemap:../typemap:typemap
106 .Ve
107 .SH EXPORT
108 .IX Header "EXPORT"
109 None by default. \f(CWprocess_file()\fR and/or \f(CWreport_error_count()\fR
110 may be exported upon request. Using the functional interface is
111 discouraged.
112 .SH METHODS
113 .IX Header "METHODS"
114 .ie n .IP $pxs\->\fBnew()\fR 4
115 .el .IP \f(CW$pxs\fR\->\fBnew()\fR 4
116 .IX Item "$pxs->new()"
117 Returns a new, empty XS parser/compiler object.
118 .ie n .IP $pxs\->\fBprocess_file()\fR 4
119 .el .IP \f(CW$pxs\fR\->\fBprocess_file()\fR 4
120 .IX Item "$pxs->process_file()"
121 This method processes an XS file and sends output to a C file.
122 The method may be called as a function (this is the legacy
123 interface) and will then use a singleton as invocant.
124 .Sp
125 Named parameters control how the processing is done.
126 The following parameters are accepted:
127 .RS 4
128 .IP filename 4
129 .IX Item "filename"
130 This is the full pathname of the XS file to open and process.
131 \&\fBprocess_file()\fR will normally \fBchdir()\fR to the basename of the file.
132 .Sp
133 The filename may be a reference to a string, in which case the lines of
134 the string form the contents of the "input" file, using the standard
135 \&\f(CW\*(C`open $fh, \*(Aq<\*(Aq, \e$string\*(C'\fR mechanism.
136 .IP \fBC++\fR 4
137 .IX Item "C++"
138 Adds \f(CW\*(C`extern "C"\*(C'\fR to the C code. Default is false.
139 .IP \fBhiertype\fR 4
140 .IX Item "hiertype"
141 Retains \f(CW\*(C`::\*(C'\fR in type names so that C++ hierarchical types can be
142 mapped. Default is false.
143 .IP \fBexcept\fR 4
144 .IX Item "except"
145 Adds exception handling stubs to the C code. Default is false.
146 .IP \fBtypemap\fR 4
147 .IX Item "typemap"
148 Indicates that a user\-supplied typemap should take precedence over the
149 default typemaps. A single typemap may be specified as a string, or
150 multiple typemaps can be specified in an array reference, with the
151 last typemap having the highest precedence.
152 .IP \fBprototypes\fR 4
153 .IX Item "prototypes"
154 Generates prototype code for all xsubs. Default is false.
155 .IP \fBversioncheck\fR 4
156 .IX Item "versioncheck"
157 Makes sure at run time that the object file (derived from the \f(CW\*(C`.xs\*(C'\fR
158 file) and the \f(CW\*(C`.pm\*(C'\fR files have the same version number. Default is
159 true.
160 .IP \fBlinenumbers\fR 4
161 .IX Item "linenumbers"
162 Adds \f(CW\*(C`#line\*(C'\fR directives to the C output so error messages will look
163 like they came from the original XS file. Default is true.
164 .IP \fBoptimize\fR 4
165 .IX Item "optimize"
166 Enables certain optimizations. The only optimization that is currently
167 affected is the use of \fItarget\fRs by the output C code (see perlguts).
168 Not optimizing may significantly slow down the generated code, but this is the way
169 \&\fBxsubpp\fR of 5.005 and earlier operated. Default is to optimize.
170 .IP \fBinout\fR 4
171 .IX Item "inout"
172 Enable recognition of \f(CW\*(C`IN\*(C'\fR, \f(CW\*(C`OUT_LIST\*(C'\fR and \f(CW\*(C`INOUT_LIST\*(C'\fR
173 declarations. Default is true.
174 .IP \fBargtypes\fR 4
175 .IX Item "argtypes"
176 Enable recognition of ANSI\-like descriptions of function signature.
177 Default is true.
178 .IP \fBs\fR 4
179 .IX Item "s"
180 \&\fIMaintainer note:\fR I have no clue what this does. Strips function prefixes?
181 .IP \fBdie_on_error\fR 4
182 .IX Item "die_on_error"
183 Normally ExtUtils::ParseXS will terminate the program with an \f(CWexit(1)\fR after
184 printing the details of the exception to STDERR via (warn). This can be awkward
185 when it is used programmatically and not via xsubpp, so this option can be used
186 to cause it to die instead by providing a true value. When not provided this
187 defaults to the value of \f(CW$ExtUtils::ParseXS::DIE_ON_ERROR\fR which in turn
188 defaults to false.
189 .RE
190 .RS 4
191 .RE
192 .ie n .IP $pxs\->\fBreport_error_count()\fR 4
193 .el .IP \f(CW$pxs\fR\->\fBreport_error_count()\fR 4
194 .IX Item "$pxs->report_error_count()"
195 This method returns the number of [a certain kind of] errors
196 encountered during processing of the XS file.
197 .Sp
198 The method may be called as a function (this is the legacy
199 interface) and will then use a singleton as invocant.
200 .SH AUTHOR
201 .IX Header "AUTHOR"
202 Based on xsubpp code, written by Larry Wall.
203 .PP
204 Maintained by:
205 .IP \(bu 4
206 Ken Williams, <[email protected]>
207 .IP \(bu 4
208 David Golden, <[email protected]>
209 .IP \(bu 4
210 James Keenan, <[email protected]>
211 .IP \(bu 4
212 Steffen Mueller, <[email protected]>
213 .SH COPYRIGHT
214 .IX Header "COPYRIGHT"
215 Copyright 2002\-2014 by Ken Williams, David Golden and other contributors. All
216 rights reserved.
217 .PP
218 This library is free software; you can redistribute it and/or
219 modify it under the same terms as Perl itself.
220 .PP
221 Based on the \f(CW\*(C`ExtUtils::xsubpp\*(C'\fR code by Larry Wall and the Perl 5
222 Porters, which was released under the same license terms.
223 .SH "SEE ALSO"
224 .IX Header "SEE ALSO"
225 perl, ExtUtils::xsubpp, ExtUtils::MakeMaker, perlxs, perlxstut.