Spaces:
Running
Running
| =head1 NAME | |
| ExtUtils::ParseXS - converts Perl XS code into C code | |
| =head1 SYNOPSIS | |
| use ExtUtils::ParseXS; | |
| my $pxs = ExtUtils::ParseXS->new; | |
| $pxs->process_file( filename => 'foo.xs' ); | |
| $pxs->process_file( filename => 'foo.xs', | |
| output => 'bar.c', | |
| 'C++' => 1, | |
| typemap => 'path/to/typemap', | |
| hiertype => 1, | |
| except => 1, | |
| versioncheck => 1, | |
| linenumbers => 1, | |
| optimize => 1, | |
| prototypes => 1, | |
| ); | |
| # Legacy non-OO interface using a singleton: | |
| use ExtUtils::ParseXS qw(process_file); | |
| process_file( filename => 'foo.xs' ); | |
| =head1 DESCRIPTION | |
| C<ExtUtils::ParseXS> will compile XS code into C code by embedding the constructs | |
| necessary to let C functions manipulate Perl values and creates the glue | |
| necessary to let Perl access those functions. The compiler uses typemaps to | |
| determine how to map C function parameters and variables to Perl values. | |
| The compiler will search for typemap files called I<typemap>. It will use | |
| the following search path to find default typemaps, with the rightmost | |
| typemap taking precedence. | |
| ../../../typemap:../../typemap:../typemap:typemap | |
| =head1 EXPORT | |
| None by default. C<process_file()> and/or C<report_error_count()> | |
| may be exported upon request. Using the functional interface is | |
| discouraged. | |
| =head1 METHODS | |
| =over 4 | |
| =item $pxs->new() | |
| Returns a new, empty XS parser/compiler object. | |
| =item $pxs->process_file() | |
| This method processes an XS file and sends output to a C file. | |
| The method may be called as a function (this is the legacy | |
| interface) and will then use a singleton as invocant. | |
| Named parameters control how the processing is done. | |
| The following parameters are accepted: | |
| =over 4 | |
| =item B<C++> | |
| Adds C<extern "C"> to the C code. Default is false. | |
| =item B<hiertype> | |
| Retains C<::> in type names so that C++ hierarchical types can be | |
| mapped. Default is false. | |
| =item B<except> | |
| Adds exception handling stubs to the C code. Default is false. | |
| =item B<typemap> | |
| Indicates that a user-supplied typemap should take precedence over the | |
| default typemaps. A single typemap may be specified as a string, or | |
| multiple typemaps can be specified in an array reference, with the | |
| last typemap having the highest precedence. | |
| =item B<prototypes> | |
| Generates prototype code for all xsubs. Default is false. | |
| =item B<versioncheck> | |
| Makes sure at run time that the object file (derived from the C<.xs> | |
| file) and the C<.pm> files have the same version number. Default is | |
| true. | |
| =item B<linenumbers> | |
| Adds C<#line> directives to the C output so error messages will look | |
| like they came from the original XS file. Default is true. | |
| =item B<optimize> | |
| Enables certain optimizations. The only optimization that is currently | |
| affected is the use of I<target>s by the output C code (see L<perlguts>). | |
| Not optimizing may significantly slow down the generated code, but this is the way | |
| B<xsubpp> of 5.005 and earlier operated. Default is to optimize. | |
| =item B<inout> | |
| Enable recognition of C<IN>, C<OUT_LIST> and C<INOUT_LIST> | |
| declarations. Default is true. | |
| =item B<argtypes> | |
| Enable recognition of ANSI-like descriptions of function signature. | |
| Default is true. | |
| =item B<s> | |
| I<Maintainer note:> I have no clue what this does. Strips function prefixes? | |
| =back | |
| =item $pxs->report_error_count() | |
| This method returns the number of [a certain kind of] errors | |
| encountered during processing of the XS file. | |
| The method may be called as a function (this is the legacy | |
| interface) and will then use a singleton as invocant. | |
| =back | |
| =head1 AUTHOR | |
| Based on xsubpp code, written by Larry Wall. | |
| Maintained by: | |
| =over 4 | |
| =item * | |
| Ken Williams, <[email protected]> | |
| =item * | |
| David Golden, <[email protected]> | |
| =item * | |
| James Keenan, <[email protected]> | |
| =item * | |
| Steffen Mueller, <[email protected]> | |
| =back | |
| =head1 COPYRIGHT | |
| Copyright 2002-2014 by Ken Williams, David Golden and other contributors. All | |
| rights reserved. | |
| This library is free software; you can redistribute it and/or | |
| modify it under the same terms as Perl itself. | |
| Based on the C<ExtUtils::xsubpp> code by Larry Wall and the Perl 5 | |
| Porters, which was released under the same license terms. | |
| =head1 SEE ALSO | |
| L<perl>, ExtUtils::xsubpp, ExtUtils::MakeMaker, L<perlxs>, L<perlxstut>. | |
| =cut | |