178 lines
4.3 KiB
Plaintext
178 lines
4.3 KiB
Plaintext
=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, <ken@mathforum.org>
|
|
|
|
=item *
|
|
|
|
David Golden, <dagolden@cpan.org>
|
|
|
|
=item *
|
|
|
|
James Keenan, <jkeenan@cpan.org>
|
|
|
|
=item *
|
|
|
|
Steffen Mueller, <smueller@cpan.org>
|
|
|
|
=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
|
|
|
|
|