summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/ExtUtils/ParseXS.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/ExtUtils/ParseXS.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/ExtUtils/ParseXS.pod177
1 files changed, 177 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/ExtUtils/ParseXS.pod b/Master/tlpkg/tlperl/lib/ExtUtils/ParseXS.pod
new file mode 100644
index 00000000000..6bec01482cf
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/ExtUtils/ParseXS.pod
@@ -0,0 +1,177 @@
+=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
+
+