local-lib5/man/man3/ExtUtils::ParseXS.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "ExtUtils::ParseXS 3"
 132 .TH ExtUtils::ParseXS 3 "2009-10-05" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 ExtUtils::ParseXS \- converts Perl XS code into C code
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&  use ExtUtils::ParseXS qw(process_file);
 139 .Ve
 140 .PP
 141 .Vb 1
 142 \&  process_file( filename => 'foo.xs' );
 143 .Ve
 144 .PP
 145 .Vb 13
 146 \&  process_file( filename => 'foo.xs',
 147 \&                output => 'bar.c',
 148 \&                'C++' => 1,
 149 \&                typemap => 'path/to/typemap',
 150 \&                hiertype => 1,
 151 \&                except => 1,
 152 \&                prototypes => 1,
 153 \&                versioncheck => 1,
 154 \&                linenumbers => 1,
 155 \&                optimize => 1,
 156 \&                prototypes => 1,
 157 \&              );
 158 \&=head1 DESCRIPTION
 159 .Ve
 160 .PP
 161 \&\f(CW\*(C`ExtUtils::ParseXS\*(C'\fR will compile \s-1XS\s0 code into C code by embedding the constructs
 162 necessary to let C functions manipulate Perl values and creates the glue
 163 necessary to let Perl access those functions.  The compiler uses typemaps to
 164 determine how to map C function parameters and variables to Perl values.
 165 .PP
 166 The compiler will search for typemap files called \fItypemap\fR.  It will use
 167 the following search path to find default typemaps, with the rightmost
 168 typemap taking precedence.
 169 .PP
 170 .Vb 1
 171 \&        ../../../typemap:../../typemap:../typemap:typemap
 172 .Ve
 173 .SH "EXPORT"
 174 .IX Header "EXPORT"
 175 None by default.  \f(CW\*(C`process_file()\*(C'\fR may be exported upon request.
 176 .SH "FUNCTIONS"
 177 .IX Header "FUNCTIONS"
 178 .IP "\fIprocess_xs()\fR" 4
 179 .IX Item "process_xs()"
 180 This function processes an \s-1XS\s0 file and sends output to a C file.
 181 Named parameters control how the processing is done.  The following
 182 parameters are accepted:
 183 .RS 4
 184 .IP "\fB\*(C+\fR" 4
 185 .IX Item ""
 186 Adds \f(CW\*(C`extern "C"\*(C'\fR to the C code.  Default is false.
 187 .IP "\fBhiertype\fR" 4
 188 .IX Item "hiertype"
 189 Retains \f(CW\*(C`::\*(C'\fR in type names so that \*(C+ hierachical types can be
 190 mapped.  Default is false.
 191 .IP "\fBexcept\fR" 4
 192 .IX Item "except"
 193 Adds exception handling stubs to the C code.  Default is false.
 194 .IP "\fBtypemap\fR" 4
 195 .IX Item "typemap"
 196 Indicates that a user-supplied typemap should take precedence over the
 197 default typemaps.  A single typemap may be specified as a string, or
 198 multiple typemaps can be specified in an array reference, with the
 199 last typemap having the highest precedence.
 200 .IP "\fBprototypes\fR" 4
 201 .IX Item "prototypes"
 202 Generates prototype code for all xsubs.  Default is false.
 203 .IP "\fBversioncheck\fR" 4
 204 .IX Item "versioncheck"
 205 Makes sure at run time that the object file (derived from the \f(CW\*(C`.xs\*(C'\fR
 206 file) and the \f(CW\*(C`.pm\*(C'\fR files have the same version number.  Default is
 207 true.
 208 .IP "\fBlinenumbers\fR" 4
 209 .IX Item "linenumbers"
 210 Adds \f(CW\*(C`#line\*(C'\fR directives to the C output so error messages will look
 211 like they came from the original \s-1XS\s0 file.  Default is true.
 212 .IP "\fBoptimize\fR" 4
 213 .IX Item "optimize"
 214 Enables certain optimizations.  The only optimization that is currently
 215 affected is the use of \fItarget\fRs by the output C code (see perlguts).
 216 Not optimizing may significantly slow down the generated code, but this is the way
 217 \&\fBxsubpp\fR of 5.005 and earlier operated.  Default is to optimize.
 218 .IP "\fBinout\fR" 4
 219 .IX Item "inout"
 220 Enable recognition of \f(CW\*(C`IN\*(C'\fR, \f(CW\*(C`OUT_LIST\*(C'\fR and \f(CW\*(C`INOUT_LIST\*(C'\fR
 221 declarations.  Default is true.
 222 .IP "\fBargtypes\fR" 4
 223 .IX Item "argtypes"
 224 Enable recognition of ANSI-like descriptions of function signature.
 225 Default is true.
 226 .IP "\fBs\fR" 4
 227 .IX Item "s"
 228 I have no clue what this does.  Strips function prefixes?
 229 .RE
 230 .RS 4
 231 .RE
 232 .IP "\fIerrors()\fR" 4
 233 .IX Item "errors()"
 234 This function returns the number of [a certain kind of] errors
 235 encountered during processing of the \s-1XS\s0 file.
 236 .SH "AUTHOR"
 237 .IX Header "AUTHOR"
 238 Based on xsubpp code, written by Larry Wall.
 239 .PP
 240 Maintained by:
 241 .IP "\(bu" 4
 242 Ken Williams, <ken@mathforum.org>
 243 .IP "\(bu" 4
 244 David Golden, <dagolden@cpan.org>
 245 .SH "COPYRIGHT"
 246 .IX Header "COPYRIGHT"
 247 Copyright 2002\-2009 by Ken Williams, David Golden and other contributors.  All
 248 rights reserved.
 249 .PP
 250 This library is free software; you can redistribute it and/or
 251 modify it under the same terms as Perl itself.
 252 .PP
 253 Based on the ExtUtils::xsubpp code by Larry Wall and the Perl 5
 254 Porters, which was released under the same license terms.
 255 .SH "SEE ALSO"
 256 .IX Header "SEE ALSO"
 257 perl, ExtUtils::xsubpp, ExtUtils::MakeMaker, perlxs, perlxstut.