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