perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject cvs commit: modperl-docs/src/devel/core_explained core_explained.pod
Date Wed, 21 Nov 2001 04:39:52 GMT
stas        01/11/20 20:39:52

  Modified:    src/devel/core_explained core_explained.pod
  Log:
  - partial covering of the maps files
  
  Revision  Changes    Path
  1.6       +180 -44   modperl-docs/src/devel/core_explained/core_explained.pod
  
  Index: core_explained.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/devel/core_explained/core_explained.pod,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- core_explained.pod	2001/11/15 16:31:56	1.5
  +++ core_explained.pod	2001/11/21 04:39:52	1.6
  @@ -28,7 +28,7 @@
     WrapXS/      - autogenerated XS code
     blib/        - ready to install version of the package
   
  -=head2 Directory xs/
  +=head1 Directory xs/
   
     Apache/                 - Apache specific XS code
     APR/                    - APR specific XS code
  @@ -41,7 +41,7 @@
     modperl_xs_util.h       - 
     typemap                 - 
   
  -=head3 xs/Apache, xs/APR and xs/ModPerl
  +=head2 xs/Apache, xs/APR and xs/ModPerl
   
   The I<xs/Apache>, I<xs/APR> and I<xs/ModPerl> directories include I<.h>
files which
   have C and XS code in them. They all have the I<.h> extension because
  @@ -50,14 +50,56 @@
   directories should be able to see what's in there.  Anything else
   belongs in a I<src/modules/perl/foo.c> public API.
   
  -=head3 xs/maps
  +=head2 xs/maps
   
   The I<xs/maps> directory includes mapping files which describe how
  -Apache Perl API should be constructed and various XS typemapping. The
  -map files are comprised of three groups:
  +Apache Perl API should be constructed and various XS typemapping.
   
  +These files get modified whenever:
  +
   =over
   
  +=item *
  +
  +a new function is added or the API of the existing one is modified.
  +
  +=item *
  +
  +a new struct is added or the existing one is modified
  +
  +=item *
  +
  +a new C datatype or Perl typemap is added or an existing one is
  +modified.
  +
  +=back
  +
  +The execution of:
  +
  +  % make source_scan
  +
  +converts these map files into their Perl table representation in the
  +I<xs/tables/current/> directory. This Perl representation is then used
  +during C<perl Makefile.PL> to generate the XS code in the I<./WrapXS/>
  +directory by the xs_generate() function. This XS code is combined of
  +the Apache API Perl glue and mod_perl specific extensions.
  +
  +Notice that I<source_scan> target is normally not run during the
  +project build process, since the source scanning is not stable yet,
  +therefore everytime the map files change, C<make source_scan> should
  +be run manually and the updated files ending up in the
  +I<xs/tables/current/> directory should be committed to the cvs
  +repository.
  +
  +The I<source_scan> make target is actually to run
  +I<build/source_scan.pl>, which can be run directly without needing to
  +create I<Makefile> first.
  +
  +There are three different types of map files in the I<xs/maps/>
  +directory:
  +
  +=over
  +
   =item * Functions Mapping
   
     apache_functions.map
  @@ -66,57 +108,148 @@
   
   =item * Structures Mapping
   
  -apache_structures.map
  -apr_structures.map
  +  apache_structures.map
  +  apr_structures.map
   
   =item * Types Mapping
   
  -apache_types.map
  -apr_types.map
  -modperl_types.map
  +  apache_types.map
  +  apr_types.map
  +  modperl_types.map
   
   =back
   
   The following sections describe the syntax of the files in each group
  +
  +=head3 Functions Mapping
  +
  +The functions mapping file is comprised of groups of function
  +definitions. Each group starts with a header similar to XS syntax:
  +
  +  MODULE=... PACKAGE=... PREFIX=... BOOT=... ISA=...
  +
  +where:
  +
  +=over
  +
  +=item * C<MODULE>
  +
  +the module name where the functions should be put.  e.g. C<MODULE
  +Apache::Connection> will place the functions into 
  +I<WrapXS/Apache/Connection.{pm,xs}>.
  +
  +=item * C<PACKAGE>
  +
  +the package name functions belong to, defaults to C<MODULE>.  The
  +value of I<guess> indicates that package name should be guessed based
  +on first argument found that maps to a Perl class.  If the value is
  +not defined and the function's name starts with I<ap_> the C<Apache>
  +package will be used, if it starts with I<apr_> then the C<APR>
  +package is used.
  +
  +=item * C<PREFIX>
  +
  +prefix string to be stripped from the function name.  If not specified
  +it defaults to C<PACKAGE>, converted to C name convention, e.g.
  +C<APR::Base64> makes the prefix: I<apr_base64_>.  If the converted
  +prefix does not match, defaults to I<ap_> or I<apr_>.
  +
  +=item * C<BOOT>
  +
  +META: complete
  +
  +=item * C<ISA>
  +
  +META: complete
  +
  +=back
  +
  +Every function definition is declared on a separate line, using the
  +following format:
   
  -=head4 Functions Mapping
  +  C function name | Dispatch function name | Argspec | Perl alias
   
  +where:
   
  -#keywords:
  -# MODULE  = the module name
  -#           e.g. Apache::Connection -> Apache/Connection.{pm,xs}
  -#
  -# PACKAGE = the package name functions belong to, defaults to MODULE
  -#           value of 'guess' indicates that package name should be
  -#           guessed based on first argument found that maps to a Perl class
  -#           fallsback on the prefix (ap_ -> Apache, apr_ -> APR)
  -#
  -# PREFIX  = prefix to be stripped
  -#           defaults to PACKAGE, converted to C name convention, e.g.
  -#           APR::Base64 -> apr_base64_
  -#           if the converted prefix does not match, defaults to ap_ or apr_
  -
  -#format of entries:
  -# C function name | dispatch function name | argspec | Perl alias
  -
  -# dispatch function name defaults to C function name
  -# if the dispatch name is just a prefix (mpxs_, MPXS_)
  -# the C function name is appended to it
  -# the return type can be specified before the C function name,
  -# defaults to return_type in {Apache,ModPerl}::FunctionTable
  -
  -# the argspec defaults to arguments in {Apache,ModPerl}::FunctionTable
  -# argument types can be specified to override those in the FunctionTable
  -# default values can be specified, e.g. arg=default_value
  -# argspec of '...' indicates passthru, calling the function with
  -# (aTHX_ I32 items, SP **sp, SV **MARK)
  +=over
  +
  +=item * C function name
  +
  +The name of the real C function.
  +
  +Function names that do not begin with C</^\w/> are skipped. For
  +details see: C<%ModPerl::MapUtil::disabled_map>.
  +
  +The return type can be specified before the C function name. It
  +defaults to I<return_type> in C<{Apache,ModPerl}::FunctionTable>.
  +
  +META: DEFINE nuances
  +
  +=item * Dispatch function name
  +
  +Dispatch function name defaults to C function name. If the dispatch
  +name is just a prefix (I<mpxs_>, I<MPXS_>) the C function name is
  +appended to it.
  +
  +
  +=item * Argspec
  +
  +The argspec defaults to arguments in
  +C<{Apache,ModPerl}::FunctionTable>.  Argument types can be specified
  +to override those in the C<FunctionTable>.  Default values can be
  +specified, e.g. C<arg=default_value>. Argspec of C<...> indicates
  +I<passthru>, calling the function with C<(aTHX_ I32 items, SP **sp, SV
  +**MARK)>.
  +
  +=item * Perl alias
  +
  +the Perl alias will be created in the current C<PACKAGE>.
  +
  +=back
  +
  +=head3 Structures Mapping
  +
  +META: complete
   
  -# the alias will be created in the current PACKAGE
  +=head3 Types Mapping
   
  -# function names that do not begin with /^\w/ are skipped
  -# for details see: %ModPerl::MapUtil::disabled_map
  +META: complete
   
  +=head3 Modifying Maps
   
  +As explained in the beginning of this section, whenever the map file
  +is modified you need first to run:
  +
  +  % make source_scan
  +
  +Next check that the conversion to Perl tables is properly done by
  +verifying the resulting corresponding file in
  +I<xs/tables/current>. For example I<xs/maps/modperl_functions.map> is
  +converted into I<xs/tables/current/ModPerl/FunctionTable.pm>.
  +
  +If you don't want to do a visual check on how XS code will be
  +generated, just rebuild the project starting with C<perl
  +Makefile.PL>. Otherwise run:
  +
  +  % make xs_generate
  +
  +and verify that the autogenerated XS code under the I<./Wrap>
  +directory is correct.
  +
  +=head2 XS generation process
  +
  +As mentioned before XS code is generated in the I<WrapXS> directory
  +either during C<perl Makefile.PL> via xs_generate() or explicitly via:
  +
  +  % make xs_generate
  +
  +In addition it creates a number of files in the I<xs/> directory:
  +
  +  modperl_xs_sv_convert.h
  +  modperl_xs_typedefs.h
  +
  +
  +
   =head1 Maintainers
   
   Maintainer is the person(s) you should contact with updates,
  @@ -126,7 +259,10 @@
   
   =head1 Authors
   
  -Stas Bekman E<lt>stas (at) stason.orgE<gt>
  -Philippe M. Chiasson E<lt>gozer@cpan.orgE<gt>
  +=over 
  +
  +=item * Stas Bekman E<lt>stas (at) stason.orgE<gt>
  +
  +=back
   
   =cut
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org


Mime
View raw message