Debian Codegraph @

upstream/mageia-cauldron/man1/xsubpp.1

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 "XSUBPP 1"
61 .TH XSUBPP 1 2026-05-26 "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 xsubpp \- compiler to convert Perl XS code into C code
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 \&\fBxsubpp\fR [\fB\-v\fR] [\fB\-except\fR] [\fB\-s pattern\fR] [\fB\-prototypes\fR] [\fB\-noversioncheck\fR] [\fB\-nolinenumbers\fR] [\fB\-nooptimize\fR] [\fB\-typemap typemap\fR] [\fB\-output filename\fR]... file.xs
71 .SH DESCRIPTION
72 .IX Header "DESCRIPTION"
73 This compiler is typically run by the makefiles created by ExtUtils::MakeMaker
74 or by Module::Build or other Perl module build tools.
75 .PP
76 \&\fIxsubpp\fR will compile XS code into C code by embedding the constructs
77 necessary to let C functions manipulate Perl values and creates the glue
78 necessary to let Perl access those functions. The compiler uses typemaps to
79 determine how to map C function parameters and variables to Perl values.
80 .PP
81 The compiler will search for typemap files called \fItypemap\fR. It will use
82 the following search path to find default typemaps, with the rightmost
83 typemap taking precedence.
84 .PP
85 .Vb 1
86 \& ../../../typemap:../../typemap:../typemap:typemap
87 .Ve
88 .PP
89 It will also use a default typemap installed as \f(CW\*(C`ExtUtils::typemap\*(C'\fR.
90 .SH OPTIONS
91 .IX Header "OPTIONS"
92 Note that the \f(CW\*(C`XSOPT\*(C'\fR MakeMaker option may be used to add these options to
93 any makefiles generated by MakeMaker.
94 .IP \fB\-hiertype\fR 5
95 .IX Item "-hiertype"
96 Retains \*(Aq::\*(Aq in type names so that C++ hierarchical types can be mapped.
97 .IP \fB\-except\fR 5
98 .IX Item "-except"
99 Adds exception handling stubs to the C code.
100 .IP "\fB\-typemap typemap\fR" 5
101 .IX Item "-typemap typemap"
102 Indicates that a user\-supplied typemap should take precedence over the
103 default typemaps. This option may be used multiple times, with the last
104 typemap having the highest precedence.
105 .IP "\fB\-output filename\fR" 5
106 .IX Item "-output filename"
107 Specifies the name of the output file to generate. If no file is
108 specified, output will be written to standard output.
109 .IP \fB\-v\fR 5
110 .IX Item "-v"
111 Prints the \fIxsubpp\fR version number to standard output, then exits.
112 .IP \fB\-prototypes\fR 5
113 .IX Item "-prototypes"
114 By default \fIxsubpp\fR will not automatically generate prototype code for
115 all xsubs. This flag will enable prototypes.
116 .IP \fB\-noversioncheck\fR 5
117 .IX Item "-noversioncheck"
118 Disables the run time test that determines if the object file (derived
119 from the \f(CW\*(C`.xs\*(C'\fR file) and the \f(CW\*(C`.pm\*(C'\fR files have the same version
120 number.
121 .IP \fB\-nolinenumbers\fR 5
122 .IX Item "-nolinenumbers"
123 Prevents the inclusion of \*(Aq#line\*(Aq directives in the output.
124 .IP \fB\-nooptimize\fR 5
125 .IX Item "-nooptimize"
126 Disables certain optimizations. The only optimization that is currently
127 affected is the use of \fItarget\fRs by the output C code (see perlguts).
128 This may significantly slow down the generated code, but this is the way
129 \&\fBxsubpp\fR of 5.005 and earlier operated.
130 .IP \fB\-noinout\fR 5
131 .IX Item "-noinout"
132 Disable recognition of \f(CW\*(C`IN\*(C'\fR, \f(CW\*(C`OUT_LIST\*(C'\fR and \f(CW\*(C`INOUT_LIST\*(C'\fR declarations.
133 .IP \fB\-noargtypes\fR 5
134 .IX Item "-noargtypes"
135 Disable recognition of ANSI\-like descriptions of function signature.
136 .IP \fB\-C++\fR 5
137 .IX Item "-C++"
138 Currently doesn\*(Aqt do anything at all. This flag has been a no\-op for
139 many versions of perl, at least as far back as perl5.003_07. It\*(Aqs
140 allowed here for backwards compatibility.
141 .IP "\fB\-s=...\fR or \fB\-strip=...\fR" 5
142 .IX Item "-s=... or -strip=..."
143 \&\fIThis option is obscure and discouraged.\fR
144 .Sp
145 If specified, the given string will be stripped off from the beginning
146 of the C function name in the generated XS functions (if it starts with that prefix).
147 This only applies to XSUBs without \f(CW\*(C`CODE\*(C'\fR or \f(CW\*(C`PPCODE\*(C'\fR blocks.
148 For example, the XS:
149 .Sp
150 .Vb 1
151 \& void foo_bar(int i);
152 .Ve
153 .Sp
154 when \f(CW\*(C`xsubpp\*(C'\fR is invoked with \f(CW\*(C`\-s foo_\*(C'\fR will install a \f(CW\*(C`foo_bar\*(C'\fR
155 function in Perl, but really call \f(CWbar(i)\fR in C. Most of the time,
156 this is the opposite of what you want and failure modes are somewhat
157 obscure, so please avoid this option where possible.
158 .SH ENVIRONMENT
159 .IX Header "ENVIRONMENT"
160 No environment variables are used.
161 .SH AUTHOR
162 .IX Header "AUTHOR"
163 Originally by Larry Wall. Turned into the \f(CW\*(C`ExtUtils::ParseXS\*(C'\fR module
164 by Ken Williams.
165 .SH "MODIFICATION HISTORY"
166 .IX Header "MODIFICATION HISTORY"
167 See the file \fIChanges\fR.
168 .SH "SEE ALSO"
169 .IX Header "SEE ALSO"
170 \&\fBperl\fR\|(1), \fBperlxs\fR\|(1), \fBperlxstut\fR\|(1), ExtUtils::ParseXS