dist/ExtUtils-ParseXS/lib/ExtUtils/xsubpp

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