Commit | Line | Data |
---|---|---|
a65c06db S |
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 | ||
c667e096 | 45 | =item process_file() |
a65c06db S |
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 | ||
629b8367 | 59 | Retains C<::> in type names so that C++ hierarchical types can be |
a65c06db S |
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 | ||
c870602e | 107 | I<Maintainer note:> I have no clue what this does. Strips function prefixes? |
a65c06db S |
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 | ||
a65c06db S |
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 | ||
c870602e S |
134 | =item * |
135 | ||
136 | James Keenan, <jkeenan@cpan.org> | |
137 | ||
138 | =item * | |
139 | ||
140 | Steffen Mueller, <smueller@cpan.org> | |
141 | ||
a65c06db S |
142 | =back |
143 | ||
144 | =head1 COPYRIGHT | |
145 | ||
c870602e | 146 | Copyright 2002-2011 by Ken Williams, David Golden and other contributors. All |
a65c06db S |
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 | ||
c870602e | 152 | Based on the C<ExtUtils::xsubpp> code by Larry Wall and the Perl 5 |
a65c06db S |
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 |