This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
61d7698542795c77fd5e21ea2d7fcbf7d1ea83e9
[perl5.git] / 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<Maintainer note:> 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 =item *
135
136 James Keenan, <jkeenan@cpan.org>
137
138 =item *
139
140 Steffen Mueller, <smueller@cpan.org>
141
142 =back
143
144 =head1 COPYRIGHT
145
146 Copyright 2002-2011 by Ken Williams, David Golden and other contributors.  All
147 rights reserved.
148
149 This library is free software; you can redistribute it and/or
150 modify it under the same terms as Perl itself.
151
152 Based on the C<ExtUtils::xsubpp> code by Larry Wall and the Perl 5
153 Porters, which was released under the same license terms.
154
155 =head1 SEE ALSO
156
157 L<perl>, ExtUtils::xsubpp, ExtUtils::MakeMaker, L<perlxs>, L<perlxstut>.
158
159 =cut
160
161