This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Move ExtUtils::ParseXS from cpan/ to dist/
[perl5.git] / dist / ExtUtils-ParseXS / lib / ExtUtils / xsubpp
CommitLineData
2304df62 1#!./miniperl
75f92628 2
6b09c160
YST
3require 5.002;
4use ExtUtils::ParseXS qw(process_file);
5use Getopt::Long;
6
7my %args = ();
8
008fb49c 9my $usage = "Usage: xsubpp [-v] [-csuffix csuffix] [-except] [-prototypes] [-noversioncheck] [-nolinenumbers] [-nooptimize] [-noinout] [-noargtypes] [-s pattern] [-typemap typemap]... file.xs\n";
6b09c160
YST
10
11Getopt::Long::Configure qw(no_auto_abbrev no_ignore_case);
12
13@ARGV = grep {$_ ne '-C++'} @ARGV; # Allow -C++ for backward compatibility
14GetOptions(\%args, qw(hiertype!
15 prototypes!
16 versioncheck!
17 linenumbers!
18 optimize!
19 inout!
20 argtypes!
21 object_capi!
22 except!
23 v
24 typemap=s@
25 output=s
26 s=s
008fb49c 27 csuffix=s
6b09c160
YST
28 ))
29 or die $usage;
30
31if ($args{v}) {
32 print "xsubpp version $ExtUtils::ParseXS::VERSION\n";
33 exit;
34}
35
36@ARGV == 1 or die $usage;
37
38$args{filename} = shift @ARGV;
39
40process_file(%args);
41exit( ExtUtils::ParseXS::errors() ? 1 : 0 );
42
43__END__
44
75f92628
AD
45=head1 NAME
46
47xsubpp - compiler to convert Perl XS code into C code
48
49=head1 SYNOPSIS
50
6b09c160 51B<xsubpp> [B<-v>] [B<-except>] [B<-s pattern>] [B<-prototypes>] [B<-noversioncheck>] [B<-nolinenumbers>] [B<-nooptimize>] [B<-typemap typemap>] [B<-output filename>]... file.xs
75f92628
AD
52
53=head1 DESCRIPTION
54
b26a54d0
GS
55This compiler is typically run by the makefiles created by L<ExtUtils::MakeMaker>.
56
75f92628
AD
57I<xsubpp> will compile XS code into C code by embedding the constructs
58necessary to let C functions manipulate Perl values and creates the glue
59necessary to let Perl access those functions. The compiler uses typemaps to
60determine how to map C function parameters and variables to Perl values.
61
62The compiler will search for typemap files called I<typemap>. It will use
63the following search path to find default typemaps, with the rightmost
64typemap taking precedence.
65
66 ../../../typemap:../../typemap:../typemap:typemap
67
6b09c160
YST
68It will also use a default typemap installed as C<ExtUtils::typemap>.
69
75f92628
AD
70=head1 OPTIONS
71
b26a54d0
GS
72Note that the C<XSOPT> MakeMaker option may be used to add these options to
73any makefiles generated by MakeMaker.
74
75f92628
AD
75=over 5
76
0ab125c1
NIS
77=item B<-hiertype>
78
863b2ca0 79Retains '::' in type names so that C++ hierarchical types can be mapped.
0ab125c1 80
75f92628
AD
81=item B<-except>
82
83Adds exception handling stubs to the C code.
84
85=item B<-typemap typemap>
86
87Indicates that a user-supplied typemap should take precedence over the
88default typemaps. This option may be used multiple times, with the last
89typemap having the highest precedence.
90
6b09c160
YST
91=item B<-output filename>
92
93Specifies the name of the output file to generate. If no file is
94specified, output will be written to standard output.
95
8e07c86e
AD
96=item B<-v>
97
98Prints the I<xsubpp> version number to standard output, then exits.
99
8fc38fda 100=item B<-prototypes>
382b8d97 101
8fc38fda
PP
102By default I<xsubpp> will not automatically generate prototype code for
103all xsubs. This flag will enable prototypes.
104
105=item B<-noversioncheck>
106
107Disables the run time test that determines if the object file (derived
108from the C<.xs> file) and the C<.pm> files have the same version
109number.
382b8d97 110
6f1abe2b
JT
111=item B<-nolinenumbers>
112
113Prevents the inclusion of `#line' directives in the output.
114
b26a54d0
GS
115=item B<-nooptimize>
116
117Disables certain optimizations. The only optimization that is currently
118affected is the use of I<target>s by the output C code (see L<perlguts>).
119This may significantly slow down the generated code, but this is the way
120B<xsubpp> of 5.005 and earlier operated.
121
11416672
GS
122=item B<-noinout>
123
124Disable recognition of C<IN>, C<OUT_LIST> and C<INOUT_LIST> declarations.
125
126=item B<-noargtypes>
127
128Disable recognition of ANSI-like descriptions of function signature.
129
6b09c160
YST
130=item B<-C++>
131
132Currently doesn't do anything at all. This flag has been a no-op for
133many versions of perl, at least as far back as perl5.003_07. It's
134allowed here for backwards compatibility.
135
c5be433b 136=back
75f92628
AD
137
138=head1 ENVIRONMENT
139
140No environment variables are used.
141
142=head1 AUTHOR
143
6b09c160
YST
144Originally by Larry Wall. Turned into the C<ExtUtils::ParseXS> module
145by Ken Williams.
75f92628 146
f06db76b
AD
147=head1 MODIFICATION HISTORY
148
6b09c160 149See the file F<Changes>.
e50aee73 150
75f92628
AD
151=head1 SEE ALSO
152
6b09c160 153perl(1), perlxs(1), perlxstut(1), ExtUtils::ParseXS
75f92628
AD
154
155=cut
93a17b20 156