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