extutils::xsbuilder.3

视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.

.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "XSBuilder 3"
.TH XSBuilder 3 "2005-08-30" "perl v5.10.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
ExtUtils::XSBuilder \- Automatic Perl XS glue code generation
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
ExtUtils::XSBuilder is a set modules to parse C header files and create \s-1XS\s0
glue code and documentation out of it. Idealy this allows to \*(L"write\*(R" an
interface to a C library without coding a line. Since no C \s-1API\s0 is ideal,
some adjuments are necessary most of the time. So to use this module you
must still be familiar with C and \s-1XS\s0 programming, but it removes a lot of
stupid work and copy & paste from you. Also when the C \s-1API\s0 changes, most
of the time you only have to rerun XSBuilder to get your new Perl \s-1API\s0.
.PP
The creation process takes place in the following steps:
.Sh "Derive a class from ExtUtils::XSBuilder::ParseSource"
.IX Subsection "Derive a class from ExtUtils::XSBuilder::ParseSource"
This class must override some methods to tell XSBuilder which C header files
to parse and some other necessary parameters. You need at least to override
the \f(CW\*(C`package\*(C'\fR method to give the name of the package you want to create and 
either the \f(CW\*(C`find_includes\*(C'\fR method which returns all C header files to parse,
or the \f(CW\*(C`include_dirs\*(C'\fR method to return a list of all directories which
should be scanned for C header files.
.PP
Of course there are more methods you can overide. See 
ExtUtils::XSBuilder::ParseSource for a full list of overrideable methods.
.Sh "Scan the source files"
.IX Subsection "Scan the source files"
If your derived class is called MyClass::ParseSource you simply start the 
source scan with
.PP
.Vb 1
\&    perl \-MMyClass::ParseSource \-e \*(AqMyClass::ParseSource\->run\*(Aq
.Ve
.PP
You may also put this into a small script to ease usage, set the Perl libpath,
etc.
.PP
During the source scan, XSBuilder creates a set of tables which contain the
results of parsing. If you haven't changed the default locations in your
subclass, these tables are created under \f(CW\*(C`xs/tables\*(C'\fR, followed by the
name of the module returned by the \f(CW\*(C`package\*(C'\fR method you created. There you
will find four generated modules: \f(CW\*(C`FunctionTable.pm\*(C'\fR, which holds the
function declarations; \f(CW\*(C`StructureTable.pm\*(C'\fR, which holds the structures;
\&\f(CW\*(C`ConstantTable.pm\*(C'\fR, which contains constants found in the header files; and
\&\f(CW\*(C`CallbackTable.pm\*(C'\fR, which contains definitions for callback types.
.PP
Since source scanning may take some time, we create intermediate tables and
transform them into \s-1XS\s0 code later, rather than creating \s-1XS\s0 code directly.
Since we save the result, we can avoid rescanning the source files as long as
they don't change.
.Sh "Derive a class from ExtUtils::XSBuilder::WrapXS"
.IX Subsection "Derive a class from ExtUtils::XSBuilder::WrapXS"
The WrapXS class is responsible for taking the information generated both from
the source files and from the map files (see below) to create the \s-1XS\s0 code.
As with the ParseSource class, you must override this method with your own
implementaion, to tell WrapXS what to do.
.PP
See ExtUtils::XSBuilder::WrapXS for a list of overrideable methods.
.Sh "Create map files"
.IX Subsection "Create map files"
XSBuilder will not automaticly create \s-1XS\s0 functions for all C functions and
structures. You must provide hints in order for the \s-1XS\s0 files to be created
properly. The map files are the mechanism to provide these hints. By default,
the map files are found under \f(CW\*(C`xs/maps\*(C'\fR. There are four map types, \f(CW\*(C`types\*(C'\fR,
\&\f(CW\*(C`functions\*(C'\fR, \f(CW\*(C`structures\*(C'\fR, and \f(CW\*(C`callbacks\*(C'\fR. Each map file is named with
a user selectable prefix (e.g. \f(CW\*(C`foo\*(C'\fR,) followed by an underscore, the map
type name, and the map extension \f(CW\*(C`.map\*(C'\fR. For example, hints for functions
relating to error processing in your source may be contained in a map file
named \f(CW\*(C`error_functions.map\*(C'\fR.
.IP "foo_types.map" 4
.IX Item "foo_types.map"
Contains the mapping from C types to Perl classes.
.IP "foo_functions.map" 4
.IX Item "foo_functions.map"
Contains the mapping from C functions to Perl functions. Can be used to 
reorder arguments, tell XSBuilder which arguments are actualy return values 
and in which Perl package the function will be created.
.IP "foo_structures.map" 4
.IX Item "foo_structures.map"
Contains the mapping from C structures to Perl classes and defines for which
classes the access methods should be created. You can also specify if you want
a \f(CW\*(C`new\*(C'\fR method for the class.
.IP "foo_callbacks.map" 4
.IX Item "foo_callbacks.map"
Contains the mapping form C callback functions to Perl callback functions. Can
be used to reorder arguments, tell XSBuilder which arguments are return
values, and in which Perl package the functions will be created.
.PP
For a detailed description of the map file formats see below.
.PP
To have a starting point, XSBuilder is able to create default map files which
simply include all types, functions and structures. You can recreate the map
files anytime and XSBuilder will append all items which are not already in the
map files.
.PP
First copy the _types.map file from the xsbuilder directory to your maps
directory. This file contains the standard mapping for some basic types.
.PP
If, for example, your derived class is called MyClass::WrapXS, you simply
start the creation/update of the map files with
.PP
.Vb 1
\&    perl \-MMyClass::WrapXS \-e \*(AqMyClass::WrapXS\->checkmaps(" ")\*(Aq
.Ve
.PP
The argument to checkmaps supplies a character to be prepended to the first
column of the new map entries. If you do not pass an argument to checkmaps, no
map files are written, and checkmaps will only compare what is missing. (You
need to print the result somehow e.g. by using Data::Dumper). You may also put
this into a small script to ease usage, set the Perl libpath, etc.
.PP
After you have created your default maps, you must edit the 
\&\f(CW\*(C`xs/maps/new_type.map\*(C'\fR file, which contains all types that were found in the
source. Append a pipe (\f(CW\*(C`|\*(C'\fR) followed by the class or type name, e.g.
.PP
.Vb 2
\&    int                 | IV
\&    struct request_rec  | Apache::RequestRec
.Ve
.PP
\&.
.Sh "Create the \s-1XS\s0 files"
.IX Subsection "Create the XS files"
Now we can create the code. By running
.PP
.Vb 1