Debian Codegraph @

dist/ExtUtils-ParseXS/lib/ExtUtils/xsubpp

raw
1 #!perl
2 use 5.006;
3 BEGIN { pop @INC if $INC[-1] eq '.' }
4 use strict;
5 eval {
6 require ExtUtils::ParseXS;
7 1;
8 }
9 or do {
10 my $err = $@ || 'Zombie error';
11 my $v = $ExtUtils::ParseXS::VERSION;
12 $v = '<undef>' if not defined $v;
13 die "Failed to load or import from ExtUtils::ParseXS (version $v). Please check that ExtUtils::ParseXS is installed correctly and that the newest version will be found in your \@INC path: $err";
14 };
15
16 use Getopt::Long;
17
18 my %args = ();
19
20 my $usage = "Usage: xsubpp [-v] [-csuffix csuffix] [-except] [-prototypes] [-noversioncheck] [-nolinenumbers] [-nooptimize] [-noinout] [-noargtypes] [-strip|s pattern] [-typemap typemap]... file.xs\n";
21
22 Getopt::Long::Configure qw(no_auto_abbrev no_ignore_case);
23
24 @ARGV = grep {$_ ne '-C++'} @ARGV; # Allow -C++ for backward compatibility
25 GetOptions(\%args, qw(hiertype!
26 prototypes!
27 versioncheck!
28 linenumbers!
29 optimize!
30 inout!
31 argtypes!
32 object_capi!
33 except!
34 v
35 typemap=s@
36 output=s
37 s|strip=s
38 csuffix=s
39 ))
40 or die $usage;
41
42 if ($args{v}) {
43 print "xsubpp version $ExtUtils::ParseXS::VERSION\n";
44 exit;
45 }
46
47 @ARGV == 1 or die $usage;
48
49 $args{filename} = shift @ARGV;
50
51 my $pxs = ExtUtils::ParseXS->new;
52 $pxs->process_file(%args);
53 exit( $pxs->report_error_count() ? 1 : 0 );
54
55 __END__
56
57 =head1 NAME
58
59 xsubpp - compiler to convert Perl XS code into C code
60
61 =head1 SYNOPSIS
62
63 B<xsubpp> [B<-v>] [B<-except>] [B<-s pattern>] [B<-prototypes>] [B<-noversioncheck>] [B<-nolinenumbers>] [B<-nooptimize>] [B<-typemap typemap>] [B<-output filename>]... file.xs
64
65 =head1 DESCRIPTION
66
67 This compiler is typically run by the makefiles created by L<ExtUtils::MakeMaker>
68 or by L<Module::Build> or other Perl module build tools.
69
70 I<xsubpp> will compile XS code into C code by embedding the constructs
71 necessary to let C functions manipulate Perl values and creates the glue
72 necessary to let Perl access those functions. The compiler uses typemaps to
73 determine how to map C function parameters and variables to Perl values.
74
75 The compiler will search for typemap files called I<typemap>. It will use
76 the following search path to find default typemaps, with the rightmost
77 typemap taking precedence.
78
79 ../../../typemap:../../typemap:../typemap:typemap
80
81 It will also use a default typemap installed as C<ExtUtils::typemap>.
82
83 =head1 OPTIONS
84
85 Note that the C<XSOPT> MakeMaker option may be used to add these options to
86 any makefiles generated by MakeMaker.
87
88 =over 5
89
90 =item B<-hiertype>
91
92 Retains '::' in type names so that C++ hierarchical types can be mapped.
93
94 =item B<-except>
95
96 Adds exception handling stubs to the C code.
97
98 =item B<-typemap typemap>
99
100 Indicates that a user-supplied typemap should take precedence over the
101 default typemaps. This option may be used multiple times, with the last
102 typemap having the highest precedence.
103
104 =item B<-output filename>
105
106 Specifies the name of the output file to generate. If no file is
107 specified, output will be written to standard output.
108
109 =item B<-v>
110
111 Prints the I<xsubpp> version number to standard output, then exits.
112
113 =item B<-prototypes>
114
115 By default I<xsubpp> will not automatically generate prototype code for
116 all xsubs. This flag will enable prototypes.
117
118 =item B<-noversioncheck>
119
120 Disables the run time test that determines if the object file (derived
121 from the C<.xs> file) and the C<.pm> files have the same version
122 number.
123
124 =item B<-nolinenumbers>
125
126 Prevents the inclusion of '#line' directives in the output.
127
128 =item B<-nooptimize>
129
130 Disables certain optimizations. The only optimization that is currently
131 affected is the use of I<target>s by the output C code (see L<perlguts>).
132 This may significantly slow down the generated code, but this is the way
133 B<xsubpp> of 5.005 and earlier operated.
134
135 =item B<-noinout>
136
137 Disable recognition of C<IN>, C<OUT_LIST> and C<INOUT_LIST> declarations.
138
139 =item B<-noargtypes>
140
141 Disable recognition of ANSI-like descriptions of function signature.
142
143 =item B<-C++>
144
145 Currently doesn't do anything at all. This flag has been a no-op for
146 many versions of perl, at least as far back as perl5.003_07. It's
147 allowed here for backwards compatibility.
148
149 =item B<-s=...> or B<-strip=...>
150
151 I<This option is obscure and discouraged.>
152
153 If specified, the given string will be stripped off from the beginning
154 of the C function name in the generated XS functions (if it starts with that prefix).
155 This only applies to XSUBs without C<CODE> or C<PPCODE> blocks.
156 For example, the XS:
157
158 void foo_bar(int i);
159
160 when C<xsubpp> is invoked with C<-s foo_> will install a C<foo_bar>
161 function in Perl, but really call C<bar(i)> in C. Most of the time,
162 this is the opposite of what you want and failure modes are somewhat
163 obscure, so please avoid this option where possible.
164
165 =back
166
167 =head1 ENVIRONMENT
168
169 No environment variables are used.
170
171 =head1 AUTHOR
172
173 Originally by Larry Wall. Turned into the C<ExtUtils::ParseXS> module
174 by Ken Williams.
175
176 =head1 MODIFICATION HISTORY
177
178 See the file F<Changes>.
179
180 =head1 SEE ALSO
181
182 perl(1), perlxs(1), perlxstut(1), ExtUtils::ParseXS
183
184 =cut
185