stas 01/11/15 08:31:56
Modified: src/devel/core_explained core_explained.pod
Log:
- starting to work on the core guide
Revision Changes Path
1.5 +115 -23 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.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- core_explained.pod 2001/11/12 02:44:40 1.4
+++ core_explained.pod 2001/11/15 16:31:56 1.5
@@ -2,39 +2,131 @@
mod_perl 2.0 Source Code Explained
-=head1 Code Layout
+=head1 Project's Layout
-Apache-Test/ - test kit for mod_perl and Apache::* modules
-Changes - Changes file
-LICENSE - ASF LICENSE doc
-Makefile.PL - Generates all the needed Makefiles
-Makefile - autogenerated
-WrapXS/ - autogenerated
-lib/
-src/
-t/ - mod_perl tests
-todo/ - things to be done
-util/ - useful utilities for developers
-xs/
-
-
-=head1 ...
-
-most of the xs/ *.h files have code in them. they are .h because they are
-always #include-d, never compiled into their own object file. and only
-the file that #include-s a .h file from xs/ should be able to see what's
-in there. anything else belongs in a src/modules/perl/foo.c public api.
+In its pristine state the project is comprised of the following root
+directories and files:
+ Apache-Test/ - test kit for mod_perl and Apache::* modules
+ ModPerl-Registry/ - ModPerl::Registry sub-project
+ build/ - utilities used during project build
+ docs/ - documentation
+ lib/ - Perl modules
+ src/ - C code that builds libmodperl.so
+ t/ - mod_perl tests
+ todo/ - things to be done
+ util/ - useful utilities for developers
+ xs/ - source xs code and maps
+ Changes - Changes file
+ LICENSE - ASF LICENSE document
+ Makefile.PL - generates all the needed Makefiles
+
+After building the project, the following root directories and files
+get generated:
+
+ Makefile - Makefile
+ WrapXS/ - autogenerated XS code
+ blib/ - ready to install version of the package
+
+=head2 Directory xs/
+
+ Apache/ - Apache specific XS code
+ APR/ - APR specific XS code
+ ModPerl/ - ModPerl specific XS code
+ maps/ -
+ tables/ -
+ Makefile.PL -
+ modperl_xs_sv_convert.h -
+ modperl_xs_typedefs.h -
+ modperl_xs_util.h -
+ typemap -
+
+=head3 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
+they are always C<#include-d>, never compiled into their own object
+file. and only the file that C<#include-s> an I<.h> file from these
+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
+
+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:
+
+=over
+
+=item * Functions Mapping
+
+ apache_functions.map
+ modperl_functions.map
+ apr_functions.map
+
+=item * Structures Mapping
+
+apache_structures.map
+apr_structures.map
+
+=item * Types Mapping
+
+apache_types.map
+apr_types.map
+modperl_types.map
+
+=back
+
+The following sections describe the syntax of the files in each group
+
+=head4 Functions Mapping
+
+
+#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)
+
+# the alias will be created in the current PACKAGE
+
+# function names that do not begin with /^\w/ are skipped
+# for details see: %ModPerl::MapUtil::disabled_map
+
+
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
corrections and patches.
-Stas Bekman E<lt>[EMAIL PROTECTED]<gt>
+Stas Bekman E<lt>stas (at) stason.orgE<gt>
=head1 Authors
-Stas Bekman E<lt>[EMAIL PROTECTED]<gt>
+Stas Bekman E<lt>stas (at) stason.orgE<gt>
Philippe M. Chiasson E<lt>[EMAIL PROTECTED]<gt>
=cut
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
