xsbuilder.osc2002.pod

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

=head1 XSBuilder - Autogenerating XS-glue Code


O'Reilly OpenSource Convention 2002 

Gerald Richter

ecos gmbh  

http://www.ecos.de

=head1 XSBuilder - What is it?


=head2 It's purpose is to automaticly generate a Perl interface to C Code

=head2 Solves the problem, that the Perl interface is not always uptodate with the C interface

=head2 Saves a lot of Copy&Paste work

=head2 Systematical changes have to be done only once

For example changes in the memory management of strings.

=head2 Is part of mod_perl 2.0 build system

Most code is developed by Doug MacEachern. Additionaly I have 

=over

=item abstracted the code from mod_perl so it's useable for any C code

=item added new features like callbacks and the ability to parse comments

=item Replaced C::Scan with a Parse::RecDescent to be platform and compiler independend

=back

Goal is to replace the current mod_perl XS generation code with XSBuilder

=head2 Inline versus XSBuilder

=over
 
=item Inline: embed C-Code into Perl

=item XSBuilder: Create interface for existing C-libraries/applicationen

=back

=head1 XSBuilder - What does it do?

=head2 Create Perl functions/methods for every C function

The function can be assigned to different packages, also automaticly
by inspecting the first parameter

=head2 Create a Perl class for every C structure

Every element of structure becomes a Perl method to get/set it's value.
The object can be either a scalar reference (used by mod_perl) or
a reference to a hash (use by Embperl), which allows to store extra 
data by the Perl code into this hash.

=head2 Create glue code to handle callbacks

There several sorts of callback, not all are implemented right now

=head2 Create Perl constant subs

Coming soon...

=head1 XSBuilder - How does it work?

=head2 Parse the C header files

Extract

=over

=item Functions, their arguments and return types

=item Structures and it's members

=item Constants

=item Callbacks

=back

and create four tables which contains the results

=head2 Create the XS code

Input is

=over

=item The source tables

=item Mapfiles which contains the mapping from C to Perl

=item Addtional C and Perl code that can be used to customize the interface

=back

Output is

=over

=item The XS files (one form every generated class)

=item Makefile.PL for every class

=item pm files

=back




=head1 Parse the source

=head2 Create your own ParseSource class and override methods...

    package Apache::DAV::ParseSource;

    use strict;
    use vars qw{@ISA $VERSION} ;
    use ExtUtils::XSBuilder::ParseSource  ;

    @ISA = ('ExtUtils::XSBuilder::ParseSource') ;
    $VERSION = '0.01';

    my $dav_dir = 'C:\perl\msrc\cvs\mod_dav' ;
    my $ap_dir  = 'c:\programme\apache group\apache' ;

    # ============================================================================
    sub find_includes {
        my $self = shift;
        return $self->{includes} if $self->{includes};
        my @includes = ("$ap_dir/include/ap_alloc.h", "$dav_dir/mod_dav.h") ;
        return $self->{includes} = $self -> sort_includes (\@includes) ;
        }

    # ============================================================================
    sub package     { 'Apache::DAV' } 

    # ============================================================================
    sub preprocess {
        my $self     = shift ;
        $_[0] =~ s/(?:API_EXPORT)(?:_NONSTD)?\s*\(\s*(.*?)\s*\)/$1/g ;
    }


    1;

=head2 ...run it

    use FindBin ;
    use lib ($FindBin::Bin) ;

    require ParseSource ; 

    Apache::DAV::ParseSource -> run ;

=head2 ...and you get

    C:\perl\msrc\davint>perl xsbuilder\source_scan.pl
    Will use mod_dav in C:\perl\msrc\cvs\mod_dav
    Will use Apache in c:\programme\apache group\apache
    Initialize parser
    scan c:\programme\apache group\apache/include/ap_alloc.h ...
    constant: APACHE_ALLOC_H
    func:     ap_init_alloc
    func:     ap_cleanup_alloc
    func:     ap_make_sub_pool
    func:     ap_destroy_pool
    constant: ap_pool_join
    func:     ap_pool_join
    func:     ap_find_pool
    func:     ap_pool_is_ancestor
    func:     ap_clear_pool
    func:     ap_cleanup_for_exec
    func:     ap_palloc
    func:     ap_pcalloc
    func:     ap_pstrdup
    func:     ap_pstrndup
    func:     ap_pstrcat
    func:     ap_pvsprintf
      valuefield: ap_pool * : pool
      valuefield: int : elt_size
      valuefield: int : nelts
      valuefield: int : nalloc
      valuefield: char * : elts
    struct:    (type=array_header)
    ...

=head2 The result is stored in four tables

=over

=item xsbuilder/tables/Apache/DAV/FuntionTable.pm

Contains all function, it arguments and comments

=item xsbuilder/tables/Apache/DAV/ConstantTable.pm

Contains all constants

=item xsbuilder/tables/Apache/DAV/StructureTable.pm

Contains all structures, it's members and their comments

=item xsbuilder/tables/Apache/DAV/CallbackTable.pm

Contains all callback function definitions

=back

=head1 Create the map files

=head2 Mapfiles are used to tell XSBuilder how C datatypes, structures
and function aruments should be mapped into Perl ones.

=head2 Create your own WrapXS class and override methods

    package Apache::DAV::WrapXS ;
    use strict;
    use vars qw{@ISA $VERSION} ;

    use ExtUtils::XSBuilder::WrapXS ;

    @ISA = ('ExtUtils::XSBuilder::WrapXS') ;
    $VERSION = '0.01';

    # ============================================================================
    sub new_parsesource  { [ Apache::DAV::ParseSource->new ] }

    # ============================================================================
    sub my_xs_prefix  { 'davxs_' }

    # ============================================================================
    sub h_filename_prefix  { 'moddav_xs_' }

    # ============================================================================
    sub xs_includes {
        my $self = shift ;
        my $i = $self -> SUPER::xs_includes ;
        my @i = grep (!/ap_alloc/, @$i) ;
        return \@i ;
    }


=head2 XSBuilder can create/update initial maps for you

    use FindBin ;
    use lib ($FindBin::Bin) ;

    require ParseSource ; 
    require WrapXS ; 

    Apache::DAV::WrapXS->checkmaps (' ');

=head2 run it

    C:\perl\msrc\davint>perl xsbuilder\xs_check.pl
    Will use mod_dav in C:\perl\msrc\cvs\mod_dav
    Will use Apache in c:\programme\apache group\apache
    Parse xsbuilder\maps/_types.map...
    WARNING: No *_function.map file found in xsbuilder\maps
    WARNING: No *_callback.map file found in xsbuilder\maps
    WARNING: No *_structure.map file found in xsbuilder\maps
    Write xsbuilder\maps/new_function.map...
    Write xsbuilder\maps/new_callback.map...
    Write xsbuilder\maps/new_structure.map...
    Write xsbuilder\maps/new_type.map...

=head2 Now we have four map files


=over 4

=item new_types.map

Contains the mapping from C type to Perl classes

=item new_functions.map

Contains the mapping form 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.

=item new_structures.map

Contains the mapping from C structures to Perl classes and defines for which
members a access methods should be created. You can also specify if you want a
C<new> method for the class.

=item new_callbacks.map

Contains the mapping form C callback functions to Perl callback 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.

=back

It's a good idea to rename the prefix from C<new_> to something unique, here we use C<dav>

Everytime you rerun checkmaps, XSBuilder will create new_* files with the items
that are not already part of the other maps.

=head2 Next step is to customize the maps...

=head1 type map

=head2 autogenerated dav_type.map

    DIR	|
    FILE	|
    HANDLE	|