dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS.pod

   1 =head1 NAME
   2
   3 ExtUtils::ParseXS - converts Perl XS code into C code
   4
   5 =head1 SYNOPSIS
   6
   7   use ExtUtils::ParseXS qw(process_file);
   8
   9   process_file( filename => 'foo.xs' );
  10
  11   process_file( filename => 'foo.xs',
  12                 output => 'bar.c',
  13                 'C++' => 1,
  14                 typemap => 'path/to/typemap',
  15                 hiertype => 1,
  16                 except => 1,
  17                 prototypes => 1,
  18                 versioncheck => 1,
  19                 linenumbers => 1,
  20                 optimize => 1,
  21                 prototypes => 1,
  22               );
  23
  24 =head1 DESCRIPTION
  25
  26 C<ExtUtils::ParseXS> will compile XS code into C code by embedding the constructs
  27 necessary to let C functions manipulate Perl values and creates the glue
  28 necessary to let Perl access those functions.  The compiler uses typemaps to
  29 determine how to map C function parameters and variables to Perl values.
  30
  31 The compiler will search for typemap files called I<typemap>.  It will use
  32 the following search path to find default typemaps, with the rightmost
  33 typemap taking precedence.
  34
  35     ../../../typemap:../../typemap:../typemap:typemap
  36
  37 =head1 EXPORT
  38
  39 None by default.  C<process_file()> may be exported upon request.
  40
  41 =head1 FUNCTIONS
  42
  43 =over 4
  44
  45 =item process_xs()
  46
  47 This function processes an XS file and sends output to a C file.
  48 Named parameters control how the processing is done.  The following
  49 parameters are accepted:
  50
  51 =over 4
  52
  53 =item B<C++>
  54
  55 Adds C<extern "C"> to the C code.  Default is false.
  56
  57 =item B<hiertype>
  58
  59 Retains C<::> in type names so that C++ hierarchical types can be
  60 mapped.  Default is false.
  61
  62 =item B<except>
  63
  64 Adds exception handling stubs to the C code.  Default is false.
  65
  66 =item B<typemap>
  67
  68 Indicates that a user-supplied typemap should take precedence over the
  69 default typemaps.  A single typemap may be specified as a string, or
  70 multiple typemaps can be specified in an array reference, with the
  71 last typemap having the highest precedence.
  72
  73 =item B<prototypes>
  74
  75 Generates prototype code for all xsubs.  Default is false.
  76
  77 =item B<versioncheck>
  78
  79 Makes sure at run time that the object file (derived from the C<.xs>
  80 file) and the C<.pm> files have the same version number.  Default is
  81 true.
  82
  83 =item B<linenumbers>
  84
  85 Adds C<#line> directives to the C output so error messages will look
  86 like they came from the original XS file.  Default is true.
  87
  88 =item B<optimize>
  89
  90 Enables certain optimizations.  The only optimization that is currently
  91 affected is the use of I<target>s by the output C code (see L<perlguts>).
  92 Not optimizing may significantly slow down the generated code, but this is the way
  93 B<xsubpp> of 5.005 and earlier operated.  Default is to optimize.
  94
  95 =item B<inout>
  96
  97 Enable recognition of C<IN>, C<OUT_LIST> and C<INOUT_LIST>
  98 declarations.  Default is true.
  99
 100 =item B<argtypes>
 101
 102 Enable recognition of ANSI-like descriptions of function signature.
 103 Default is true.
 104
 105 =item B<s>
 106
 107 I have no clue what this does.  Strips function prefixes?
 108
 109 =back
 110
 111 =item errors()
 112
 113 This function returns the number of [a certain kind of] errors
 114 encountered during processing of the XS file.
 115
 116 =back
 117
 118 =head1 AUTHOR
 119
 120 Based on xsubpp code, written by Larry Wall.
 121
 122 Maintained by:
 123
 124 =over 4
 125
 126 =item *
 127
 128 Ken Williams, <ken@mathforum.org>
 129
 130 =item *
 131
 132 David Golden, <dagolden@cpan.org>
 133
 134 =back
 135
 136 =head1 COPYRIGHT
 137
 138 Copyright 2002-2009 by Ken Williams, David Golden and other contributors.  All
 139 rights reserved.
 140
 141 This library is free software; you can redistribute it and/or
 142 modify it under the same terms as Perl itself.
 143
 144 Based on the ExtUtils::xsubpp code by Larry Wall and the Perl 5
 145 Porters, which was released under the same license terms.
 146
 147 =head1 SEE ALSO
 148
 149 L<perl>, ExtUtils::xsubpp, ExtUtils::MakeMaker, L<perlxs>, L<perlxstut>.
 150
 151 =cut
 152
 153