git.maemo.org Git - pkg-perl/blob - deb-src/libextutils-parsexs-perl/libextutils-parsexs-perl-2.19/README

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