Debian Codegraph @

upstream/debian-unstable/man1/xsubpp.1

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