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>[EMAIL PROTECTED]<gt>
+=over
+
+=item * Stas Bekman E<lt>stas (at) stason.orgE<gt>
+
+=back
=cut
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
