cvs commit: modperl-docs/src/api/mod_perl-2.0 - New directory
stas01/10/02 07:56:59 modperl-docs/src/api/mod_perl-2.0 - New directory - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/api/mod_perl-2.0/APR - New directory
stas01/10/02 07:57:14 modperl-docs/src/api/mod_perl-2.0/APR - New directory - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/api/mod_perl-2.0/Apache - New directory
stas01/10/02 07:57:14 modperl-docs/src/api/mod_perl-2.0/Apache - New directory - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/api/mod_perl-2.0/APR Table.pod
stas01/10/02 07:59:18 Added: src/api/mod_perl-2.0/APR Table.pod Log: - starting APR/Table.pod - documenting APR::Table methods Revision ChangesPath 1.1 modperl-docs/src/api/mod_perl-2.0/APR/Table.pod Index: Table.pod === =head1 NAME C -- A Perl API for manipulating paque string-content table =head1 SYNOPSIS use APR::Table; $table = make($pool, $nelts); $table_copy = $table->copy($pool); $table->clear(); $table->set($key => $val); $table->unset($key); $table->add($key, $val); $val = $table->get($key); @val = $table->get($key); $table->merge($key => $val); overlap($table_a, $table_b, $flags); $new_table = overlay($table_base, $table_overlay, $pool); =head1 DESCRIPTION C allows its users to manipulate opaque string-content tables. The table is somewhat similar to the Perl hash, but allows multiply values for the same key. An access to the records stored in the table always requires a key. The key-value pairs are stored in the order they are added. The keys are case-insensitive. However as of the current implementation if more than value for the same key is requested, the whole table it lineary searched, which is very inefficient unless the table is very small. C provides a L. See I in ASF's I project for low level details. =head1 API The variables used in the API definition have the following I<"types">: =over =item * APR::Table C<$table_*> =item * APR::Pool C<$pool> =item * scalars: unsigned integers only (SVIV) (as C expects them) C<$nelts>, C<$flags> =item * scalars: (numerical (SVIV/SVNV) and strings (SVPV)) C<$key>, C<$val> =back Function arguments (if any) and return values are shown in the function's synopsis. =over =item * make() $table = make($pool, $nelts); Make a new table. param C<$pool>: The pool to allocate the pool out of. param C<$nelts>: The number of elements in the initial table. return: a new table. warning: This table can only store text data =item * copy() $table_copy = $table->copy($pool); Create a new table and copy another table into it param C<$pool>: The pool to allocate the new table out of param C<$table>: The table to copy return: A copy of the table passed in =item * clear() $table->clear(); Delete all of the elements from a table. param C<$table>: A copy of the table passed in =item * set(); $table->set($key => $val); Add a key/value pair to a table, if another element already exists with the same key, this will over-write the old data. param C<$table>: The table to add the data to. param C<$key>: The key fo use. param C<$val>: The value to add. =item * add() $table->add($key, $val); Add data to a table, regardless of whether there is another element with the same key. param C<$table>: The table to add to param C<$key>: The key to use param C<$val>: The value to add. =item * do() META: ??? =item * get() $val = $table->get($key); @val = $table->get($key); Get the value(s) associated with a given key. After this call, the data is still in the table. param C<$table>: The table to search for the key param C<$key>: The key to search for return: In the scalar context the first matching value returned. (The oldest in the table, if there is more than one value.) In the list context the whole table is traversed and all matching values are returned. If nothing matches I is returned. =item * unset(); $table->unset($key); Remove data from the table param C<$table>: The table to remove data from param C<$key>: The key of the data being removed =item * merge() $table->merge($key => $val); Add data to a table by merging the value with data that has already been stored param C<$table>: The table to search for the data param C<$key>: The key to merge data for param C<$val>: The data to add remark: If the key is not found, then this function acts like add() =item * overlap() overlap($table_a, $table_b, $flags); For each key/value pair in C<$table_b>, add the data to C<$table_a>. The definition of C<$flags> explains how C<$flags> define the overlapping method. param C<$table_a>: The table to add the data to. param C<$table_b>: The table to iterate over, adding its data to C<%table_a&g
cvs commit: modperl-docs/src/api/mod_perl-2.0/Apache compat.pod
stas01/10/02 07:59:57 Added: src/api/mod_perl-2.0/Apache compat.pod Log: - starting Apache/compat.pod - documenting header_in|out Revision ChangesPath 1.1 modperl-docs/src/api/mod_perl-2.0/Apache/compat.pod Index: compat.pod === =head1 NAME Apache::compat -- 1.x backward compatibility functions deprecated in 2.x =head1 SYNOPSIS use Apache::compat; =head1 DESCRIPTION C includes all the functions that are deprecated in mod_perl 2.x. If you code uses any of these functions you should just include this module in your code and everything should work. However, certain functionality is not optimized and therefore it's the best to try to port your code not to use deprecated functions and stop using the compatibility layer. =head1 API META: complete Function arguments (if any) and return values are shown in the function's synopsis. =over =item * $r->header_in() $r->header_in( $header_name, [$value] ) Return the value of a client header: $ct = $r->header_in($key); Set or modify the value of a client header: $r->header_in($key, $val); =item * $r->header_out() $r->header_out( $header, $value ) Return the value of a response header: $ct = $r->header_out($key); Set or modify the value of a response header: $r->header_out($key, $val); You should not define any I<"Content-XXX"> headers by calling this method, because these headers use their own specific methods. =item * =back =cut - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/api/mod_perl-2.0/Apache RequestRec.pod
stas01/10/02 08:00:46
Added: src/api/mod_perl-2.0/Apache RequestRec.pod
Log:
- starting Apache::RequestRec
- document dir_config()
Revision ChangesPath
1.1 modperl-docs/src/api/mod_perl-2.0/Apache/RequestRec.pod
Index: RequestRec.pod
===
=head1 NAME
Apache::RequestRec -- A Perl API for Apache request object
=head1 SYNOPSIS
sub handler{
my $r = shift;
# now the API can be used on $r
}
=head1 DESCRIPTION
META: complete
=head1 API
Function arguments (if any) and return values are shown in the
function's synopsis.
=over
=item * dir_config()
dir_config() provides an interface for the per-directory variable
specified by the C and C directives, and also
can be manipulated via the C methods.
The keys are case-insensitive.
$apr_table = $r->dir_config();
dir_config() called in a scalar context without the C<$key> argument
returns a I reference blessed into the I class. This
object can be manipulated via the I methods. For available
methods see I.
@values = $r->dir_config( $key );
If the C<$key> argument is passed in the list context a list of all
matching values will be returned. This method is ineffective for big
tables, as it does a linear search of the table. Thefore avoid using
this way of calling dir_config() unless you know that there could be
more than one value for the wanted key and all the values are wanted.
$value = $r->dir_config( $key );
If the C<$key> argument is passed in the scalar context only a single
value will be returned. Since the table preserves the insertion order,
if there is more than one value for the same key, the oldest value
assosiated with the desired key is returned. Calling in the scalar
context is also much faster, as it'll stop searching the table as soon
as the first match happens.
$r->dir_config( $key => $val );
If the C<$key> and the C<$val> arguments are used, the set() operation
will happen: all existing values associated with the key C<$key> (and
the key itself) will be deleted and C<$value> will be placed instead.
$r->dir_config( $key => undef );
If C<$val> is I the unset() operation will happen: all existing
values associated with the key C<$key> (and the key itself) will be
deleted.
=item *
=back
=cut
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/api README
stas01/10/02 08:26:29 Added: src/api README Log: document the explanation of what goes where in the API docs structure Revision ChangesPath 1.1 modperl-docs/src/api/README Index: README === The files under this directory document the API of mod_perl project and its sub-projects. Since for mod_perl 2.0 most of the code is autogenerated it's much easier to keep the documentation in a separate place. Each sub-project will have its own directory under docs/src/api Here is an example: docs/src/api: mod_perl-2.0/APR/Table.pod mod_perl-2.0/Apache/RequestRec.pod mod_perl-2.0/Apache/compat.pod Apache-Test/Apache/Test.pod Apache-Registry/Apache/Registry.pod Keeping all the docs under the same directory makes it easy to distribute only the documentation, especially simplify the build, since they all live in a separate modperl-docs project. So modperl-2.0's API goes into docs/src/api/mod_perl-2.0, Apache-Test's into docs/src/api/Apache-Test and etc. If later on we want to move directories around, this is very easy to do without losing cvs history. That's said, when you send in new patches, from now on please don't forget to send documentation patches. It's much easier and nicer to document as we go, then doing this at then end. If you create a new pod file, try to follow the conventions used in other pod files under the same tree. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/devel/modperl_style modperl_style.pod
stas01/10/02 08:27:02
Modified:src/devel/modperl_style modperl_style.pod
Log:
style fix
Revision ChangesPath
1.3 +1 -1 modperl-docs/src/devel/modperl_style/modperl_style.pod
Index: modperl_style.pod
===
RCS file: /home/cvs/modperl-docs/src/devel/modperl_style/modperl_style.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- modperl_style.pod 2001/09/19 01:52:03 1.2
+++ modperl_style.pod 2001/10/02 15:27:02 1.3
@@ -65,7 +65,7 @@
Do:
sub foo {
- my ($self, $cond, $baz, $taz) = @_;
+ my($self, $cond, $baz, $taz) = @_;
if ($cond) {
bar();
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/api/mod_perl-2.0 Makefile.PL
stas01/10/04 03:53:20
Added: src/api/mod_perl-2.0 Makefile.PL
Log:
- add the mod_perl-2.0 API docs Makefile.PL
- modperl-2.0's Makefile.PL will automatically locate and install its API
docs now.
Revision ChangesPath
1.1 modperl-docs/src/api/mod_perl-2.0/Makefile.PL
Index: Makefile.PL
===
require 5.6.1;
use File::Find;
use File::Spec;
use ExtUtils::MakeMaker;
my $rel_path = File::Spec->catfile(('..') x 4);
WriteMakefile(
NAME => 'API',
VERSION => '0.01',
PM => get_pods(),
);
sub get_pods {
my @pods = ();
finddepth(sub{ push @pods, "$File::Find::dir/$_" if /\.pod$/ }, '.');
return { map { s|^\./||; $_ => "\$(INST_LIB)/$_"} @pods };
}
package MY;
# when called from top mod_perl dir, it gets ../blib for all pathes,
# so we want to point it back to the top blib.
sub MY::constants {
my $self = shift;
for (grep /^INST_/, keys %{ $self } ) {
exists $self->{$_} && $self->{$_} =~ s/^\.\./$rel_path/;
}
$self->MM::constants;
}
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/api/mod_perl-2.0 .cvsignore
stas01/10/04 04:05:14 Added: src/api/mod_perl-2.0 .cvsignore Log: ignore file Revision ChangesPath 1.1 modperl-docs/src/api/mod_perl-2.0/.cvsignore Index: .cvsignore === Makefile blib pm_to_blib - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/devel/writing_tests writing_tests.pod
stas01/10/04 20:51:47 Modified:src/devel/writing_tests writing_tests.pod Log: - merging comments from clayton cottingham Revision ChangesPath 1.9 +18 -2 modperl-docs/src/devel/writing_tests/writing_tests.pod Index: writing_tests.pod === RCS file: /home/cvs/modperl-docs/src/devel/writing_tests/writing_tests.pod,v retrieving revision 1.8 retrieving revision 1.9 diff -u -r1.8 -r1.9 --- writing_tests.pod 2001/09/22 09:51:03 1.8 +++ writing_tests.pod 2001/10/05 03:51:47 1.9 @@ -147,6 +147,19 @@ For more details about the C module please refer to its manpage. +=head2 Prerequisites + +In order to use C it has to be installed first. + +Install C using the familiar procedure: + + % cd Apache-Test + % perl Makefile.PL + % make && make test && make install + +If you install mod_perl 2.x, you get C installed as +well. + =head2 One Part Perl Tests: Response only If you write only a response part of the test, C will @@ -203,6 +216,9 @@ } 1; +[F] C is mod_perl 2.x's package, if you test under 1.x, +use the C module instead [/F]. + The configuration part for this test will be autogenerated by the C framework and added to the autogenerated file I. In our case the following configuration section @@ -386,7 +402,7 @@ } 1; -The only thing it does is setting the I header and +The only thing it does is setting the I header and responding with I<"Amazing!">. Next prepare the I file: @@ -424,7 +440,7 @@ } C will do a lot of thing for us, such as building a -complete Makefile with prope I<'test'> and I<'clean'> targets, +complete Makefile with proper I<'test'> and I<'clean'> targets, automatically converting I<.PL> and I files and more. As you see we specify a prerequisites hash with I in it, - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/devel/writing_tests writing_tests.pod
stas01/10/06 07:03:21 Modified:src/devel/writing_tests writing_tests.pod Log: - improving the structure of the document, moving sections around - improving the 'How to Setup Testing Environment' section - fixing lots of error in the rest of the doc - adding a 'References' section Revision ChangesPath 1.10 +497 -363 modperl-docs/src/devel/writing_tests/writing_tests.pod Index: writing_tests.pod === RCS file: /home/cvs/modperl-docs/src/devel/writing_tests/writing_tests.pod,v retrieving revision 1.9 retrieving revision 1.10 diff -u -r1.9 -r1.10 --- writing_tests.pod 2001/10/05 03:51:47 1.9 +++ writing_tests.pod 2001/10/06 14:03:21 1.10 @@ -1,10 +1,117 @@ -=head1 Writing tests with Apache::Test framework +=head1 Developing and Running Tests with C Framework -=head1 Running Tests +=head1 Introduction -Running test is usual just like for any perl module, first we have to -create the I and build everything. So we run: +This chapter is talking about the C framework, and in +particular explains: +=over + +=item * how to run existing tests + +=item * setup a testing environment + +=item * develop new tests + +=back + +But first let's introduce the C framework. + +The C framework is designed for easy writing of tests +that has to be run under Apache webserver (not necessarily +mod_perl). Originally designed for the mod_perl Apache module, it was +extended to be used for any Apache module. + +You can write tests in Perl and C, and the framework will provide an +extensive functionality which makes the tests writing a simple and +therefore enjoyable process. + +If you have ever written or looked at the tests most Perl modules come +with, C uses the same concept. The script C is +running all the files ending with I<.t> it finds in the I +directory. When executed a typical test prints the following: + + 1..3 # going to run 3 tests + ok 1 # the first test has passed + ok 2 # the second test has passed + not ok 3 # the third test has failed + +Every C or C is followed by the number which tells which +sub-test has succeeded or failed. + +C uses a C module which intercepts the +C stream, parses it and at the end of the tests print the +results of the tests running: how many tests and sub-tests were run, +how many succeeded, skipped or failed. + +Some tests may be skipped by printing: + + 1..0 # all tests in this file are going to be skipped. + +Usually a test may be skipped when some feature is optional and/or +prerequisites are not installed on the system, but this is not +critical for the usefulness of the test. Once you test that you cannot +proceed with the tests and it's not a must pass test, you just skip +it. + +It's important to know, that there is a special verbose mode, enabled +with I<-v> option, in which everything printed by the test goes to +C. So for example if your test does this: + + print "testing : feature foo\n"; + print "expected: $expected\n"; + print "received: $received\n"; + ok $expected eq $received; + +in the normal mode, you won't see any of these prints. But if you run +the test with I, you will see something like this: + + testing : feature foo + expected: 2 + received: 2 + ok 2 + +When you develop the test you should always put the debug statements +there, and once the test works for you do not comment out or delete +these debug statements. This is because if some user reports a failure +in some test, you can ask him to run the failing test in the verbose +mode and send you back the report. It'll be much easier to understand +what the problem is if you get these debug printings from the user. + +In the section L<"Using Apache::TestUtil"> we discuss a few helper +functions which make the tests writing easier. + +For more details about the C module please refer to its +manpage. Also see the C manpage about Perl's test suite. + +=head1 Prerequisites + +In order to use C it has to be installed first. + +Install C using the familiar procedure: + + % cd Apache-Test + % perl Makefile.PL + % make && make test && make install + +If you install mod_perl 2.x, you get C installed as +well. + +=head1 How to Run Tests + +It's much easier to copy-cat things, than creating from scratch. It's +much easier to develop tests, when you have some existing system that +you can test, see how it works and build your own testing environment +in a similar fashion. Therefore let's first look at how the existing +test enviroments work. + +You can look at the modperl-2.0's or httpd-test'
cvs commit: modperl-docs/src/devel/writing_tests writing_tests.pod
stas01/10/07 06:05:07
Modified:src/devel/writing_tests writing_tests.pod
Log:
- merging corrections from Gary Benson
Revision ChangesPath
1.11 +8 -10 modperl-docs/src/devel/writing_tests/writing_tests.pod
Index: writing_tests.pod
===
RCS file: /home/cvs/modperl-docs/src/devel/writing_tests/writing_tests.pod,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- writing_tests.pod 2001/10/06 14:03:21 1.10
+++ writing_tests.pod 2001/10/07 13:05:07 1.11
@@ -22,7 +22,7 @@
mod_perl). Originally designed for the mod_perl Apache module, it was
extended to be used for any Apache module.
-You can write tests in Perl and C, and the framework will provide an
+The tests themselves are written in Perl, and the framework will provide an
extensive functionality which makes the tests writing a simple and
therefore enjoyable process.
@@ -39,7 +39,7 @@
Every C or C is followed by the number which tells which
sub-test has succeeded or failed.
-C uses a C module which intercepts the
+C uses the C module which intercepts the
C stream, parses it and at the end of the tests print the
results of the tests running: how many tests and sub-tests were run,
how many succeeded, skipped or failed.
@@ -54,8 +54,8 @@
proceed with the tests and it's not a must pass test, you just skip
it.
-It's important to know, that there is a special verbose mode, enabled
-with I<-v> option, in which everything printed by the test goes to
+It's important to know that there is a special verbose mode, enabled
+with the I<-v> option, in which everything printed by the test goes to
C. So for example if your test does this:
print "testing : feature foo\n";
@@ -177,7 +177,7 @@
You can run all the tests in a single directory by just passing this
directory as an argument. You can pass more than one test or directory
name at the same time. Thefore assuming that the directory
-I includes only two files: I and --the
+I includes only two files: I and I--the
following two commands are equivalent:
% t/TEST protocol/echo protocol/eliza
@@ -465,9 +465,9 @@
WriteMakefile(
...
- dist => {
- PREOP => 'pod2text lib/Apache/Amazing.pm > README',
- },
+ dist => {
+PREOP => 'pod2text lib/Apache/Amazing.pm >
$(DISTVNAME)/README',
+ },
...
);
@@ -524,8 +524,6 @@
In the previous section we have written a basic test, which doesn't do
much. In the following sections we will explain how to write more
elaborate tests.
-
-The tests can be written in Perl and C.
When you write the test for Apache, unless you want to test some
static resource, like fetching a file, usually you have to write a
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/devel/writing_tests writing_tests.pod
stas01/10/07 06:52:20 Modified:src/devel/writing_tests writing_tests.pod Log: - adding "Developing Test Response Handlers in C" section by Gary Benson Revision ChangesPath 1.12 +98 -2 modperl-docs/src/devel/writing_tests/writing_tests.pod Index: writing_tests.pod === RCS file: /home/cvs/modperl-docs/src/devel/writing_tests/writing_tests.pod,v retrieving revision 1.11 retrieving revision 1.12 diff -u -r1.11 -r1.12 --- writing_tests.pod 2001/10/07 13:05:07 1.11 +++ writing_tests.pod 2001/10/07 13:52:20 1.12 @@ -719,10 +719,104 @@ part should be named I. See the regular expression that does that in the previous section. -=head2 Developing Tests in C +=head2 Developing Test Response Handlers in C -META: to be written +If you need to exercise some C API and you don't have a Perl glue for +it, you can still use C for the testing. It allows you +to write response handlers in C and makes it easy to integrate these +with other Perl tests and use Perl for request part which will +exercise the C module. + +The C modules look just like standard Apache C modules, with a couple +of differences to: + +=over + +=item a + +help them fit into the test suite + +=item b + +allow them to compile nicely with Apache 1.x or 2.x. + +=back + +The I ASF project is a good example to look at. The C +modules are located under: I. +Look at I for a nice simple example. +C simply echos data that is Ced to it. + +The differences between vairous tests may be summarized as follows: + +=over + +=item * + +If the first line is: + + #define HTTPD_TEST_REQUIRE_APACHE 1 + +or + + #define HTTPD_TEST_REQUIRE_APACHE 2 + +then the test will be skipped unless the version matches. If a module +is compatible with the version of Apache used then it will be +automatically compiled by I with C<-DAPACHE1> or C<-DAPACHE2> +so you can conditionally compile it to suit different httpd versions. + +=item * + +If there is a section bounded by: + + #if CONFIG_FOR_HTTPD_TEST + ... + #endif +in the I<.c> file then that section will be inserted verbatim into +I by I. + +=back + +There is a certain amount of magic which hopefully allows most modules +to be compiled for Apache 1.3 or Apache 2.0 without any conditional +stuff. Replace XXX with the module name, for example echo_post or +random_chunk: + +=over + +=item * + +You should: + + #include "apache_httpd_test.h" + +which should be preceded by an: + + #define APACHE_HTTPD_TEST_HANDLER XXX_handler + +I pulls in a lot of required includes and defines +some constants and types that are not defined for Apache 1.3. + +=item * + +The handler function should be: + + static int XXX_handler(request_rec *r); + +=item * + +At the end of the file should be an: + + APACHE_HTTPD_TEST_MODULE(XXX) + +where XXX is the same as that in C. This +will generate the hooks and stuff. + +=back + + =head1 Developing Tests: Gory Details @@ -991,6 +1085,8 @@ =head1 Authors Stas Bekman Estas (at) stason.orgE + +Gary Benson Egbenson (at) redhat.comE =cut - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/api/mod_perl-2.0/Apache ServerUtil.pod RequestRec.pod
stas01/10/09 22:06:36
Modified:src/api/mod_perl-2.0/Apache RequestRec.pod
Added: src/api/mod_perl-2.0/Apache ServerUtil.pod
Log:
- documenting $r->server() and Apache->server() methods
Revision ChangesPath
1.2 +15 -4 modperl-docs/src/api/mod_perl-2.0/Apache/RequestRec.pod
Index: RequestRec.pod
===
RCS file: /home/cvs/modperl-docs/src/api/mod_perl-2.0/Apache/RequestRec.pod,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- RequestRec.pod2001/10/02 15:00:46 1.1
+++ RequestRec.pod2001/10/10 05:06:36 1.2
@@ -4,10 +4,14 @@
=head1 SYNOPSIS
-sub handler{
-my $r = shift;
-# now the API can be used on $r
-}
+ use Apache::RequestRec;
+ sub handler{
+ my $r = shift;
+
+ my $s = $r->server;
+ my $dir_config = $r->dir_config;
+ ...
+ }
=head1 DESCRIPTION
@@ -19,6 +23,13 @@
function's synopsis.
=over
+
+=item * server()
+
+ $s = $r->server;
+
+Gets the C object for the server the request C<$r> is
+running under.
=item * dir_config()
1.1 modperl-docs/src/api/mod_perl-2.0/Apache/ServerUtil.pod
Index: ServerUtil.pod
===
=head1 NAME
Apache::ServerUtil -- Methods for work with Apache::Server object
=head1 SYNOPSIS
use Apache::ServerUtil;
$s = Apache->server;
my $srv_cfg = $s->dir_config;
=head1 DESCRIPTION
META: complete
=head1 API
Function arguments (if any) and return values are shown in the
function's synopsis.
=over
=item * server()
The main server's object can be retrieved with:
$s = Apache->server;
Gets the C object for the main server.
=item * dir_config()
dir_config() provides an interface for the per-server variables
specified by the C and C directives, and also
can be manipulated via the C methods.
The keys are case-insensitive.
$t = $s->dir_config();
dir_config() called in a scalar context without the C<$key> argument
returns a I reference blessed into the I class. This
object can be manipulated via the I methods. For available
methods see I.
@values = $r->dir_config( $key );
If the C<$key> argument is passed in the list context a list of all
matching values will be returned. This method is ineffective for big
tables, as it does a linear search of the table. Thefore avoid using
this way of calling dir_config() unless you know that there could be
more than one value for the wanted key and all the values are wanted.
$value = $r->dir_config( $key );
If the C<$key> argument is passed in the scalar context only a single
value will be returned. Since the table preserves the insertion order,
if there is more than one value for the same key, the oldest value
assosiated with the desired key is returned. Calling in the scalar
context is also much faster, as it'll stop searching the table as soon
as the first match happens.
$r->dir_config( $key => $val );
If the C<$key> and the C<$val> arguments are used, the set() operation
will happen: all existing values associated with the key C<$key> (and
the key itself) will be deleted and C<$value> will be placed instead.
$r->dir_config( $key => undef );
If C<$val> is I the unset() operation will happen: all existing
values associated with the key C<$key> (and the key itself) will be
deleted.
=item * push_handlers()
=item * add_handlers()
=item * get_handlers()
=back
=cut
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/user/coding - New directory
stas01/10/09 22:23:03 modperl-docs/src/user/coding - New directory - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/user/coding coding.pod
stas01/10/09 22:23:53 Added: src/user/coding coding.pod Log: - starting "Coding with and for mod_perl" chapter - documenting exit()'s behavior Revision ChangesPath 1.1 modperl-docs/src/user/coding/coding.pod Index: coding.pod === =head1 Coding with and for mod_perl =head1 Prerequisites =head1 Installing from Source =head1 Installing from Binary Packages =head1 Perl Specifics in mod_perl Environment In the following sections we discuss the specifics of Perl behavior under mod_perl. =head2 exit() In the normal Perl code exit() is used to stop the program flow and exit the Perl interpreter. However under mod_perl we only want the stop the program flow without killing the Perl interpreter. You should take no action if your code includes exit() calls and it's OK to continue using them. mod_perl worries to override the exit() function with its own version which stops the program flow, and performs all the necessary cleanups, but doesn't kill the server. This is done by overriding: C<*CORE::GLOBAL::exit>, so if you mess up with C<*CORE::GLOBAL::exit> yourself you better know what you are doing. You can still call C to kill the interpreter, again if you know what you are doing. =head1 Maintainers Maintainer is the person(s) you should contact with updates, corrections and patches. =head1 Authors =cut - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/user/coding coding.pod
stas01/10/09 22:26:27 Modified:src/user/coding coding.pod Log: - the exact overriding of exit Revision ChangesPath 1.2 +6 -2 modperl-docs/src/user/coding/coding.pod Index: coding.pod === RCS file: /home/cvs/modperl-docs/src/user/coding/coding.pod,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- coding.pod2001/10/10 05:23:53 1.1 +++ coding.pod2001/10/10 05:26:27 1.2 @@ -21,8 +21,12 @@ OK to continue using them. mod_perl worries to override the exit() function with its own version which stops the program flow, and performs all the necessary cleanups, but doesn't kill the server. This -is done by overriding: C<*CORE::GLOBAL::exit>, so if you mess up with -C<*CORE::GLOBAL::exit> yourself you better know what you are doing. +is done by overriding: + + *CORE::GLOBAL::exit = \&ModPerl::Util::exit; + +so if you mess up with C<*CORE::GLOBAL::exit> yourself you better know +what you are doing. You can still call C to kill the interpreter, again if you know what you are doing. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/devel/writing_tests writing_tests.pod
stas01/10/20 03:48:33
Modified:src/devel/writing_tests writing_tests.pod
Log:
- mostly rewriting the "how to write tests" section
- various fixes in the other sections
- starting the debug section
Revision ChangesPath
1.13 +451 -101 modperl-docs/src/devel/writing_tests/writing_tests.pod
Index: writing_tests.pod
===
RCS file: /home/cvs/modperl-docs/src/devel/writing_tests/writing_tests.pod,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- writing_tests.pod 2001/10/07 13:52:20 1.12
+++ writing_tests.pod 2001/10/20 10:48:33 1.13
@@ -1,13 +1,13 @@
-=head1 Developing and Running Tests with C Framework
+=head1 Developing and Running Tests with the C Framework
=head1 Introduction
This chapter is talking about the C framework, and in
-particular explains:
+particular explains how to:
=over
-=item * how to run existing tests
+=item * run existing tests
=item * setup a testing environment
@@ -27,7 +27,7 @@
therefore enjoyable process.
If you have ever written or looked at the tests most Perl modules come
-with, C uses the same concept. The script C is
+with, C uses the same concept. The script I is
running all the files ending with I<.t> it finds in the I
directory. When executed a typical test prints the following:
@@ -39,7 +39,7 @@
Every C or C is followed by the number which tells which
sub-test has succeeded or failed.
-C uses the C module which intercepts the
+I uses the C module which intercepts the
C stream, parses it and at the end of the tests print the
results of the tests running: how many tests and sub-tests were run,
how many succeeded, skipped or failed.
@@ -78,7 +78,7 @@
mode and send you back the report. It'll be much easier to understand
what the problem is if you get these debug printings from the user.
-In the section L<"Using Apache::TestUtil"> we discuss a few helper
+In the section L<"How to Write Tests"> we discuss a few helper
functions which make the tests writing easier.
For more details about the C module please refer to its
@@ -191,18 +191,6 @@
META: do we include it in modperl-2.0? +document the new syntax.
-
-Or use this trick:
-
- PerlModule Apache::Foo
-
- PerlOptions +GlobalRequest
- SetHandler modperl
- PerlResponseHandler "sub { delete $INC{'Apache/Foo.pm'}; require
Apache::Foo; Apache::Foo::handler(shift);}"
-
-
-
-
This will force the response handler C to be reloaded on
every request.
@@ -519,7 +507,7 @@
how amazingly it works and how amazingly it can be deployed by other
users.
-=head1 How to Write Tests
+=head1 Apache::Test Framework's Architecture
In the previous section we have written a basic test, which doesn't do
much. In the following sections we will explain how to write more
@@ -817,159 +805,482 @@
=back
-=head1 Developing Tests: Gory Details
-
-
-
-=head2 Writing Test Methodology
+=head1 How to Write Tests
-META: to be written
+All the communications between tests and C which
+executes them is done via STDOUT. I.e. whatever tests want to report
+they do by printing something to STDOUT. If a test wants to print some
+debug comment it should do it on a separate line starting with
+C<#>.
-=head2 Using C
-META: to be written
-Here we cover in details some features useful in writing tests:
+=head2 Defining How Many Sub-Tests Are to Be Run
-=head2 Apache::Test functions
+Before sub-tests of a certain test can be run it has to declare how
+many sub-tests it is going to run. In some cases the test may decide
+to skip some of its sub-tests or not to run any at all. Therefore the
+first thing the test has to print is:
-B is a wrapper around the standard I with
-helpers for testing an Apache server.
+ 1..M\n
-META: merge with Apache::Test's inlined scarce docs
+where M is a positive integer. So if the test plans to run 5 sub-tests
+it should do:
-=over
+ print "1..5\n";
-=item * ok()
+In C this is done as follows:
-Same as I, see I documentation.
-META: expand
+ use Apache::Test;
+ plan tests => 5;
-=item * skip()
-Same as I, see I documentation.
-META: expand
-=item * sok()
+=head2 Skipping a Whole Test
-META: to be written
+Sometimes when the test cannot be run, because certain prerequisites
+are missing. To tell C that the whole test is to be
+skipped do:
-=item * plan()
+ print "1..0 # skipped because of foo is missing\n";
-Whenever you start a new test, you have to declare how many sub-tests
-it includes.
cvs commit: modperl-docs/src/devel/writing_tests writing_tests.pod
stas01/10/21 23:35:48 Modified:src/devel/writing_tests writing_tests.pod Log: - document the reasons for autoconfig magic in test handlers Revision ChangesPath 1.14 +24 -0 modperl-docs/src/devel/writing_tests/writing_tests.pod Index: writing_tests.pod === RCS file: /home/cvs/modperl-docs/src/devel/writing_tests/writing_tests.pod,v retrieving revision 1.13 retrieving revision 1.14 diff -u -r1.13 -r1.14 --- writing_tests.pod 2001/10/20 10:48:33 1.13 +++ writing_tests.pod 2001/10/22 06:35:47 1.14 @@ -1279,6 +1279,28 @@ PerlSetVar Foo Bar +This autoconfiguration feature was added to: + +=over + +=item * + +simplify (less lines) test configuration. + +=item * + +ensure unique namespace for ELocation ...E's. + +=item * + +force ELocation ...E names to be consistent. + +=item * + +prevent clashes within main configuration. + +=back + If some directives are supposed to go to the base configuration, i.e. not to be automatically wrapped into CLocationE> block, you should use a special CBaseE>..C/BaseE> block: @@ -1303,6 +1325,8 @@ laziness, since most tests don't need to add directives to the base configuration and we want to keep the configuration sections in tests to a minimum and let Perl do the rest of the job for us. + + META: Virtual host? - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/devel/porting_from_1.x - New directory
stas01/10/21 23:48:02 modperl-docs/src/devel/porting_from_1.x - New directory - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/devel/porting_from_1.x porting_from_1.x.pod
stas01/10/21 23:50:14 Added: src/devel/porting_from_1.x porting_from_1.x.pod Log: - starting the doc explaining how to port modules from 1.x to 2.x Revision ChangesPath 1.1 modperl-docs/src/devel/porting_from_1.x/porting_from_1.x.pod Index: porting_from_1.x.pod === =head1 Porting Modules from mod_perl 1.x to 2.x =head1 Introduction If you have released an C module on CPAN you may wonder what steps you should take to make your code working under 2.x while still preserving 1.x compatibility. This document attempts to answer some of the questions related to this issue. =head1 Should the Module Name Be Changed? While you can change the name of the module, it's the best to try to preserve the name and use some workarounds, if your module cannot be ported to run under 1.x and 2.x at the same time. Most of the existing 1.x modules on CPAN should work with 2.x without any change. The ones that will not work are the .xs modules. Let's say that you have a module C whose release version complient with mod_perl 1.x is 1.57. You keep this version on CPAN and release a new version 2.01 which is complient with 2.x and preserves the name of the module. It's possible that a user may need to have both versions of the module on the same machine. Since the two have the same name they obviously cannot live under the same tree. One attempt to solve that problem is to use C I's option. If the module is configured as: % perl Makefile.PL MP_INST_APACHE2=1 it'll be installed relative to the I directory. The second step is to change the documentation of your 2.x complient module to say: use Apache2 (); in the code before the module is required or in I or PerlModule Apache2 in I. This will C<@INC> to look in the I directory first. The introduction of I directory is similar to how Perl installs its modules in a version specific directory. For example: lib/5.7.1 lib/5.7.2 =head1 Requiring a specific mod_perl version. To require a module to run only under 2.x, simply add: use mod_perl 2.0; to your module. You can also use the variable C<$mod_perl::VERSION>. =head1 Adjusting Modules to Work with 1.x and 2.x. It's possible to adjust your module to work with both 2.x and 1.x. This is quite easy if your aren't using XS. Interfaces that are deprecated in 2.x can be enabled by adding: use Apache::compat(); in the code or I. The variable C<$mod_perl::VERSION> should be used in conditionals to use the appropriate code for 1.x or 2.x. XS modules will need I/C<#ifdef> logic to work with both versions. But the applications that use them should not need to know the difference. META: example? probably the best to use some existing module that co-exists with the two versions. =head1 Thread Safety =head1 'make test' Suite C testing framework that comes together with mod_perl 2.x works with 1.x and 2.x mod_perl versions. Therefore you should consider porting your test suite to use C. L explains how to do that. =head1 Maintainers Maintainer is the person(s) you should contact with updates, corrections and patches. Stas Bekman Estas (at) stason.orgE =head1 Authors Stas Bekman Estas (at) stason.orgE Doug MacEachern Edougm (at) covalent.netE =cut - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/api/mod_perl-2.0/APR Table.pod
stas01/10/22 08:47:17
Modified:src/api/mod_perl-2.0/APR Table.pod
Log:
- tie interface documenation
Submitted by: gozer
Revision ChangesPath
1.2 +19 -3 modperl-docs/src/api/mod_perl-2.0/APR/Table.pod
Index: Table.pod
===
RCS file: /home/cvs/modperl-docs/src/api/mod_perl-2.0/APR/Table.pod,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- Table.pod 2001/10/02 14:59:17 1.1
+++ Table.pod 2001/10/22 15:47:17 1.2
@@ -21,6 +21,16 @@
$table->merge($key => $val);
overlap($table_a, $table_b, $flags);
$new_table = overlay($table_base, $table_overlay, $pool);
+
+ #Tied Interface
+ $value = $table->{$key};
+ $table->{$key} = $value;
+ $table->{$key} = $value;
+ exists $table->{$key};
+
+ foreach my $key (keys %{$table}) {
+ print "$key = $table->{$key}\n";
+ }
=head1 DESCRIPTION
@@ -225,11 +235,17 @@
=head2 TIE Interface
-APR::Table sports TIE interface, so you can work with the C<$table>
-object as a hash.
+C also implements a tied interface, so you can work with the
+C<$table> object as a hash reference.
-META: complete
+The following tied-hash function are supported: FETCH, STORE, DELETE,
+CLEAR, EXISTS, FIRSTKEY, NEXTKEY and DESTROY.
+remark: C can hold more than one key-value pair sharing
+the same key, so when using a table through the tied interface, the
+first entry found with the right key will be used, completely
+disregarding possible other entries with the same key. The only
+exception to this is if you iterate over the list with I.
=cut
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/devel/writing_tests writing_tests.pod
stas01/10/22 20:15:56 Modified:src/devel/writing_tests writing_tests.pod Log: - add a new section: "Skipping Numerous Tests" Revision ChangesPath 1.15 +46 -0 modperl-docs/src/devel/writing_tests/writing_tests.pod Index: writing_tests.pod === RCS file: /home/cvs/modperl-docs/src/devel/writing_tests/writing_tests.pod,v retrieving revision 1.14 retrieving revision 1.15 diff -u -r1.14 -r1.15 --- writing_tests.pod 2001/10/22 06:35:47 1.14 +++ writing_tests.pod 2001/10/23 03:15:56 1.15 @@ -933,7 +933,53 @@ =back +=head2 Skipping Numerous Tests +Just like you can tell C to run only specific tests, you +can tell it to run all but a few tests. + +If all files in a directory I should be skipped, create: + + t/foo/all.t: + + print "1..0\n"; + +Alternatively you can specify which tests should be skipped from a +single file I. This file includes a list of tests to be +skipped. You can include comments starting with C<#> and you can use +the C<*> wildcharacter for multiply files matching. + +For example if in mod_perl 2.0 test suite we create the following file: + + t/SKIP: + --- + # skip all files in protocol + protocol + + # skip basic cgi test + modules/cgi.t + + # skip all filter/input_* files + filter/input*.t + +In our example the first pattern specifies the directory name +I, since we want to skip all tests in it. But since the +skipping is done based on matching the skip patterns from t/SKIP +against a list of potential tests to be run, some other tests may be +skipped as well if they match the pattern. Therefore it's safer to use +a pattern like this: + + protocol/*.t + +The second pattern skips a single test I. Note that you +shouldn't specify the leading I. The I<.t> extension is optional, +so you can tell: + + # skip basic cgi test + modules/cgi + +The last pattern tells C to skip all the tests starting +with I. =head2 Reporting a Success or a Failure of Sub-tests - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/api/mod_perl-2.0/APR Table.pod
stas01/10/25 04:32:42
Modified:src/api/mod_perl-2.0/APR Table.pod
Log:
- do() method documentation
Submitted by: gozer
Revision ChangesPath
1.3 +22 -2 modperl-docs/src/api/mod_perl-2.0/APR/Table.pod
Index: Table.pod
===
RCS file: /home/cvs/modperl-docs/src/api/mod_perl-2.0/APR/Table.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- Table.pod 2001/10/22 15:47:17 1.2
+++ Table.pod 2001/10/25 11:32:42 1.3
@@ -22,6 +22,8 @@
overlap($table_a, $table_b, $flags);
$new_table = overlay($table_base, $table_overlay, $pool);
+ $table->do(sub {print "key $_[0], value $_[1]\n"}, @valid_keys);
+
#Tied Interface
$value = $table->{$key};
$table->{$key} = $value;
@@ -143,9 +145,24 @@
param C<$val>: The value to add.
=item * do()
+
+ $table->do(sub {[...]}, [EMAIL PROTECTED]);
+
+Iterate over all the elements of the table, invoking provided
+subroutine for each element. The subroutine gets passed as argument,
+a key-value pair.
+
+The subroutine can abort the iteration by returning 0 and should
+always return 1 otherwise.
- META: ???
+param C: A subroutine reference or name to be called on each item
+in the table
+param C<@filter>: Only keys matching one of the entries in the filter
+will be processed
+
+
+
=item * get()
$val = $table->get($key);
@@ -245,7 +262,10 @@
the same key, so when using a table through the tied interface, the
first entry found with the right key will be used, completely
disregarding possible other entries with the same key. The only
-exception to this is if you iterate over the list with I.
+exception to this is if you iterate over the list with I, then
+you can access all key-value pairs that share the same key.
+
+
=cut
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/api - New directory
stas01/10/02 07:56:38 modperl-docs/src/api - New directory - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/devel/writing_tests writing_tests.pod
stas01/11/11 20:39:02
Modified:src/devel/writing_tests writing_tests.pod
Log:
- document skip_unless
- document run a range of sub-tests
- fix -run option usage
- add Apache::Reload example
Revision ChangesPath
1.17 +110 -30 modperl-docs/src/devel/writing_tests/writing_tests.pod
Index: writing_tests.pod
===
RCS file: /home/cvs/modperl-docs/src/devel/writing_tests/writing_tests.pod,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -r1.16 -r1.17
--- writing_tests.pod 2001/11/12 02:44:40 1.16
+++ writing_tests.pod 2001/11/12 04:39:02 1.17
@@ -158,47 +158,52 @@
% t/TEST -start
-and then run all the tests via:
+and then run tests without restarting the server using I<-run> option:
- % t/TEST
+ % t/TEST -run
-or only specific tests, by explicitly specifying them. For example to
-run the test file I we execute:
+Once the server is started you can modify I<.t> files and rerun the
+tests without restarting the server. However if you modify response
+handlers, you must restart the server for changes to take an
+effect. If C is used and configured to automatically
+reload the handlers when they change you don't have to restart the
+server. For example to automatically reload all C
+modules when they change on the disk, add to I:
- % t/TEST protocol/echo
+ PerlModule Apache::Reload
+ PerlInitHandler Apache::Reload
+ PerlSetVar ReloadAll Off
+ PerlSetVar ReloadModules "TestDirective::*"
+
+and restart the server.
+
+If none of the tests are specified at the command line all tests found
+in the I directory (files ending with I<.t> are recongnized as
+tests) will be run. To run specific tests, they should be explicitly
+specified. For example to run the test file I we
+execute:
+ % t/TEST -run protocol/echo
+
notice that you don't have to add the I prefix and I<.t> extension
for the test filenames if you specify them explicitly.
-Also when you run specific tests, it's because something is not
-working, therefore usually you want to run them in the verbose mode,
-that we have mentioned before.
+When you run specific tests you may want to run them in the verbose
+mode, and depending on how the test was written, you may get more
+debug information under this mode. This mode is turned on with I<-v>
+option:
- % t/TEST -v protocol/echo
+ % t/TEST -run -v protocol/echo
You can run all the tests in a single directory by just passing this
directory as an argument. You can pass more than one test or directory
name at the same time. Thefore assuming that the directory
I includes only two files: I and I--the
following two commands are equivalent:
-
- % t/TEST protocol/echo protocol/eliza
- % t/TEST protocol
-
-There is one bit you should be aware of. If you run the tests without
-restarting the server any changes to the response handlers that you
-apply won't take effect, untill the server is restarted. Therefore you
-may want to use C module, which will reload files
-automatically if they change between requests.
-META: do we include it in modperl-2.0? +document the new syntax.
+ % t/TEST -run protocol/echo protocol/eliza
+ % t/TEST -run protocol
-This will force the response handler C to be reloaded on
-every request.
-
-Since the request test files don't reside in memory you can change
-them and the changes will take effect without restarting the server.
-
The command:
% t/TEST -start
@@ -646,7 +651,7 @@
);
See the L manpage for more info on the t_cmp()
-function.
+function (e.g. it works with regexs as well).
And the corresponding response part:
@@ -888,6 +893,19 @@
=over
+=item * skip_unless()
+
+Instead of using a scalar as a last argument to plan() to tell whether
+to skip the test or not, it's better to use skip_unless() which also
+prints the reason for skipping the test if the condition is not
+satisfied. For example:
+
+ plan tests => 5, skip_unless(sub { $a == $b }, "$a != $b");
+
+skip_unless() executes the code reference in the first argument and if
+it returns a false value C<$reason> gets printed as a reason for test
+skipping.
+
=item * have_module()
have_module() tests for existance of Perl modules or C modules
@@ -1070,7 +1088,52 @@
skip $should_skip, $test_me;
so if C<$should_skip> is true, the test will be reported as
-skipped. The second argument is the one that's sent to ok().
+skipped. The second argument is the one that's sent to ok(), so if
+C<$should_skip> is true, a normal ok() sub-test is run. The following
+example represent four poss
cvs commit: modperl-docs/src/devel/writing_tests writing_tests.pod
stas01/11/11 20:47:33
Modified:src/devel/writing_tests writing_tests.pod
Log:
use # in debug prints
Revision ChangesPath
1.18 +11 -11modperl-docs/src/devel/writing_tests/writing_tests.pod
Index: writing_tests.pod
===
RCS file: /home/cvs/modperl-docs/src/devel/writing_tests/writing_tests.pod,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -r1.17 -r1.18
--- writing_tests.pod 2001/11/12 04:39:02 1.17
+++ writing_tests.pod 2001/11/12 04:47:33 1.18
@@ -60,17 +60,17 @@
with the I<-v> option, in which everything printed by the test goes to
C. So for example if your test does this:
- print "testing : feature foo\n";
- print "expected: $expected\n";
- print "received: $received\n";
+ print "# testing : feature foo\n";
+ print "# expected: $expected\n";
+ print "# received: $received\n";
ok $expected eq $received;
in the normal mode, you won't see any of these prints. But if you run
the test with I, you will see something like this:
- testing : feature foo
- expected: 2
- received: 2
+ # testing : feature foo
+ # expected: 2
+ # received: 2
ok 2
When you develop the test you should always put the debug statements
@@ -639,7 +639,7 @@
my $config = Apache::Test::config();
my $hostport = Apache::TestRequest::hostport($config) || '';
- print "connecting to $hostport\n";
+ print "# connecting to $hostport\n";
my $received = $config->http_raw_get("/TestApache::cool", undef);
my $expected = "COOL";
@@ -692,10 +692,10 @@
we are testing, what was expected and what was received:
apache/cool1..1
- connecting to localhost:8529
- testing : testing TestApache::cool
- expected: COOL
- received: COOL
+ # connecting to localhost:8529
+ # testing : testing TestApache::cool
+ # expected: COOL
+ # received: COOL
ok 1
ok
All tests successful.
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/api/ModPerl-Registry - New directory
stas01/11/12 20:35:41 modperl-docs/src/api/ModPerl-Registry - New directory - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/api/ModPerl-Registry/ModPerl - New directory
stas01/11/12 20:35:51 modperl-docs/src/api/ModPerl-Registry/ModPerl - New directory - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/api/ModPerl-Registry/ModPerl RegistryLoader.pod
stas01/11/12 20:36:21
Added: src/api/ModPerl-Registry/ModPerl RegistryLoader.pod
Log:
- document RegistryLoader's API
Revision ChangesPath
1.1
modperl-docs/src/api/ModPerl-Registry/ModPerl/RegistryLoader.pod
Index: RegistryLoader.pod
===
=head1 NAME
ModPerl::RegistryLoader - Compile ModPerl::RegistryCooker scripts at server
startup
=head1 SYNOPSIS
# in startup.pl
use ModPerl::RegistryLoader ();
# explicit uri => filename mapping
my $rlbb = ModPerl::RegistryLoader->new(
package => 'ModPerl::RegistryBB',
debug => 1, # default 0
);
$rlbb->handler($uri, $filename);
# uri => filename mapping using a helper function
sub trans {
my $uri = shift;
$uri =~ s|^/registry/|cgi-bin/|;
return Apache::server_root_relative($uri);
}
my $rl = ModPerl::RegistryLoader->new(
package => 'ModPerl::Registry',
trans => \&trans,
);
$rl->handler($uri);
=head1 DESCRIPTION
This modules allows compilation of scripts, running under packages
derived from C, at server startup. The
script's handler routine is compiled by the parent server, of which
children get a copy and thus saves some memory by initially sharing
the compiled copy with the parent and saving the overhead of script's
compilation on the first request in every httpd instance.
=head1 METHODS
=over
=item new()
When creating a new C object, one has to
specify which of the C derived modules to
use. For example if a script is going to run under
C the object is initialized as:
my $rlbb = ModPerl::RegistryLoader->new(
package => 'ModPerl::RegistryBB',
);
To turn the debugging on, set the I attribute to a true value:
my $rlbb = ModPerl::RegistryLoader->new(
package => 'ModPerl::RegistryBB',
debug => 1,
);
Instead of specifying explicitly a filename for each uri passed to
handler(), a special attribute I can be set to a subroutine to
perform automatic remapping.
my $rlbb = ModPerl::RegistryLoader->new(
package => 'ModPerl::RegistryBB',
trans => \&trans,
);
See the handler() item for an example of using the I attribute.
=item handler()
$rl->handler($uri, [$filename]);
The handler() method takes argument of C and optionally of
C.
URI to filename translation normally doesn't happen until HTTP request
time, so we're forced to roll our own translation. If the filename is
supplied it's used in translation.
If the filename is omitted and a C subroutine was not set in
new(), the loader will try using the C relative to the
C configuration directive. For example:
httpd.conf:
---
ServerRoot /usr/local/apache
Alias /registry/ /usr/local/apache/cgi-bin/
startup.pl:
---
use ModPerl::RegistryLoader ();
my $rl = ModPerl::RegistryLoader->new(
package => 'ModPerl::Registry',
);
# preload /usr/local/apache/cgi-bin/test.pl
$rl->handler(/registry/test.pl);
To make the loader smarter about the URI-Efilename translation,
you may provide the C method with a C function to
translate the uri to filename.
The following example will pre-load all files ending with I<.pl> in
the I directory relative to C.
httpd.conf:
---
ServerRoot /usr/local/apache
Alias /registry/ /usr/local/apache/cgi-bin/
startup.pl:
---
{
# test the scripts pre-loading by using trans sub
use ModPerl::RegistryLoader ();
use DirHandle ();
use strict;
my $dir = Apache::server_root_relative("cgi-bin");
sub trans {
my $uri = shift;
$uri =~ s|^/registry/|cgi-bin/|;
return Apache::server_root_relative($uri);
}
my $rl = ModPerl::RegistryLoader->new(
package => "ModPerl::Registry",
trans => \&trans,
);
my $dh = DirHandle->new($dir) or die $!;
for my $file ($dh->read) {
next unless $file =~ /\.pl$/;
$rl->handler("/registry/$file");
}
}
=back
=head1 AUTHORS
Doug MacEachern
Stas Bekman
=head1 SEE ALSO
ModPerl::RegistryCooker(3), Apache(3), mod_perl(3)
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/api/ModPerl-Registry/ModPerl PerlRun.pod Registry.pod RegistryBB.pod RegistryCooker.pod RegistryNG.pod
stas01/11/12 20:50:58 Added: src/api/ModPerl-Registry/ModPerl PerlRun.pod Registry.pod RegistryBB.pod RegistryCooker.pod RegistryNG.pod Log: add placeholders for API docs on ModPerl-Registry Revision ChangesPath 1.1 modperl-docs/src/api/ModPerl-Registry/ModPerl/PerlRun.pod Index: PerlRun.pod === =head1 NAME ModPerl::PerlRun - Run unaltered CGI scripts under mod_perl =head1 SYNOPSIS =head1 DESCRIPTION =head1 AUTHORS Doug MacEachern Stas Bekman =head1 SEE ALSO ModPerl::RegistryCooker(3), Apache(3), mod_perl(3) 1.1 modperl-docs/src/api/ModPerl-Registry/ModPerl/Registry.pod Index: Registry.pod === =head1 NAME ModPerl::Registry - Run unaltered CGI scripts persistently under mod_perl =head1 SYNOPSIS =head1 DESCRIPTION =head1 AUTHORS Doug MacEachern Stas Bekman =head1 SEE ALSO ModPerl::RegistryCooker(3), Apache(3), mod_perl(3) 1.1 modperl-docs/src/api/ModPerl-Registry/ModPerl/RegistryBB.pod Index: RegistryBB.pod === =head1 NAME ModPerl::RegistryBB - Run unaltered CGI scripts persistently under mod_perl =head1 SYNOPSIS =head1 DESCRIPTION =head1 AUTHORS Doug MacEachern Stas Bekman =head1 SEE ALSO ModPerl::RegistryCooker(3), Apache(3), mod_perl(3) 1.1 modperl-docs/src/api/ModPerl-Registry/ModPerl/RegistryCooker.pod Index: RegistryCooker.pod === =head1 NAME ModPerl::RegistryCooker - Cook mod_perl Registry Modules =head1 SYNOPSIS =head1 DESCRIPTION =head1 AUTHORS Doug MacEachern Stas Bekman =head1 SEE ALSO ModPerl::Registry(3), Apache(3), mod_perl(3) 1.1 modperl-docs/src/api/ModPerl-Registry/ModPerl/RegistryNG.pod Index: RegistryNG.pod === =head1 NAME ModPerl::RegistryNG - Run unaltered CGI scripts persistently under mod_perl =head1 SYNOPSIS =head1 DESCRIPTION This modules is just a back compatibility alias. Use C instead. =head1 AUTHORS Doug MacEachern Stas Bekman =head1 SEE ALSO ModPerl::RegistryCooker(3), Apache(3), mod_perl(3) - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/devel/modperl_style modperl_style.pod
stas01/11/13 19:41:35 Modified:src/devel/modperl_style modperl_style.pod Log: - Add the vim settings for the right tab/indent (by Tim Henigan) Revision ChangesPath 1.5 +28 -16modperl-docs/src/devel/modperl_style/modperl_style.pod Index: modperl_style.pod === RCS file: /home/cvs/modperl-docs/src/devel/modperl_style/modperl_style.pod,v retrieving revision 1.4 retrieving revision 1.5 diff -u -r1.4 -r1.5 --- modperl_style.pod 2001/11/12 02:44:40 1.4 +++ modperl_style.pod 2001/11/14 03:41:35 1.5 @@ -33,32 +33,37 @@ =over 4 -=item Indentation +=item Indentation and Tabs Do use 4 characters indentation. -emacs: cperl-mode: .xemacs/custom.el - - (custom-set-variables - '(cperl-indent-level 4) - '(cperl-continued-statement-offset 4) - ) - -vi: ??? +Do NOT use tabs. -=item Tabs +Here is how to setup your editor to do the right thing: -Do NOT use tabs. +=over -emacs: cperl-mode: .xemacs/custom.el +=item * x?emacs: cperl-mode + .xemacs/custom.el: + -- (custom-set-variables + '(cperl-indent-level 4) + '(cperl-continued-statement-offset 4) '(cperl-tab-always-indent t) '(indent-tabs-mode nil) ) -vi: ??? +=item * vim + .vimrc: + --- + set expandtab " replaces any tab keypress with the appropriate number of spaces + set tabstop=4 " sets tabs to 4 spaces + +=back + + =item Block Braces Do use a style similar to K&R style, not the same. The following @@ -312,12 +317,19 @@ Maintainer is the person(s) you should contact with updates, corrections and patches. -Stas Bekman E[EMAIL PROTECTED] +Stas Bekman Estas *at* stason.orgE =head1 Authors + +=over -Stas Bekman E[EMAIL PROTECTED] -Doug MacEachern +=item * Stas Bekman Estas *at* stason.orgE + +=item * Doug MacEachernEdougm *at* covalent.netE + +=item * Tim Henigan Et.henigan *at* verizon.netE + +=back =cut - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/api/mod_perl-2.0/Apache RequestRec.pod ServerUtil.pod
stas01/11/14 00:50:00
Modified:src/api/mod_perl-2.0/Apache RequestRec.pod ServerUtil.pod
Log:
- document Apache::server_root_relative
- fix $s->dir_config
Revision ChangesPath
1.3 +4 -4 modperl-docs/src/api/mod_perl-2.0/Apache/RequestRec.pod
Index: RequestRec.pod
===
RCS file: /home/cvs/modperl-docs/src/api/mod_perl-2.0/Apache/RequestRec.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- RequestRec.pod2001/10/10 05:06:36 1.2
+++ RequestRec.pod2001/11/14 08:50:00 1.3
@@ -46,7 +46,7 @@
object can be manipulated via the I methods. For available
methods see I.
- @values = $r->dir_config( $key );
+ @values = $r->dir_config($key);
If the C<$key> argument is passed in the list context a list of all
matching values will be returned. This method is ineffective for big
@@ -54,7 +54,7 @@
this way of calling dir_config() unless you know that there could be
more than one value for the wanted key and all the values are wanted.
- $value = $r->dir_config( $key );
+ $value = $r->dir_config($key);
If the C<$key> argument is passed in the scalar context only a single
value will be returned. Since the table preserves the insertion order,
@@ -63,13 +63,13 @@
context is also much faster, as it'll stop searching the table as soon
as the first match happens.
- $r->dir_config( $key => $val );
+ $r->dir_config($key => $val);
If the C<$key> and the C<$val> arguments are used, the set() operation
will happen: all existing values associated with the key C<$key> (and
the key itself) will be deleted and C<$value> will be placed instead.
- $r->dir_config( $key => undef );
+ $r->dir_config($key => undef);
If C<$val> is I the unset() operation will happen: all existing
values associated with the key C<$key> (and the key itself) will be
1.2 +31 -4 modperl-docs/src/api/mod_perl-2.0/Apache/ServerUtil.pod
Index: ServerUtil.pod
===
RCS file: /home/cvs/modperl-docs/src/api/mod_perl-2.0/Apache/ServerUtil.pod,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- ServerUtil.pod2001/10/10 05:06:36 1.1
+++ ServerUtil.pod2001/11/14 08:50:00 1.2
@@ -9,6 +9,12 @@
$s = Apache->server;
my $srv_cfg = $s->dir_config;
+ # get 'conf/' dir path using $r
+ my $conf_dir = Apache::server_root_relative('conf', $r->pool);
+
+ # get 'log/' dir path using default server startup pool
+ my $log_dir = Apache::server_root_relative('log');
+
=head1 DESCRIPTION
META: complete
@@ -43,7 +49,7 @@
object can be manipulated via the I methods. For available
methods see I.
- @values = $r->dir_config( $key );
+ @values = $s->dir_config($key);
If the C<$key> argument is passed in the list context a list of all
matching values will be returned. This method is ineffective for big
@@ -51,7 +57,7 @@
this way of calling dir_config() unless you know that there could be
more than one value for the wanted key and all the values are wanted.
- $value = $r->dir_config( $key );
+ $value = $s->dir_config($key);
If the C<$key> argument is passed in the scalar context only a single
value will be returned. Since the table preserves the insertion order,
@@ -60,13 +66,13 @@
context is also much faster, as it'll stop searching the table as soon
as the first match happens.
- $r->dir_config( $key => $val );
+ $s->dir_config($key => $val);
If the C<$key> and the C<$val> arguments are used, the set() operation
will happen: all existing values associated with the key C<$key> (and
the key itself) will be deleted and C<$value> will be placed instead.
- $r->dir_config( $key => undef );
+ $s->dir_config($key => undef);
If C<$val> is I the unset() operation will happen: all existing
values associated with the key C<$key> (and the key itself) will be
@@ -77,6 +83,27 @@
=item * add_handlers()
=item * get_handlers()
+
+=item * server_root_relative()
+
+Returns the canonical form of the filename made absolute to
+C:
+
+ Apache::server_root_relative([$fname, [$pool]]);
+
+If C<$fname> is specified, it'll be appended to the value of
+C and return it. e.g.:
+
+ my $log_dir = Apache::server_root_relative('log', $r->pool);
+
+If C<$pool> is not specified, the default server startup pool is used
+(this style adds an ove
cvs commit: modperl-docs/src/devel/core_explained core_explained.pod
stas01/11/15 08:31:56
Modified:src/devel/core_explained core_explained.pod
Log:
- starting to work on the core guide
Revision ChangesPath
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.pod2001/11/12 02:44:40 1.4
+++ core_explained.pod2001/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, I and I 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 public API.
+
+=head3 xs/maps
+
+The I 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,Mo
cvs commit: modperl-docs/src/api/mod_perl-2.0/Apache ServerUtil.pod
stas01/11/19 18:35:07
Modified:src/api/mod_perl-2.0/Apache ServerUtil.pod
Log:
- adjust the doc for server_root_relative
- document the server_root constant
- split the API doc into constants, functions and methods sections.
Revision ChangesPath
1.3 +36 -20modperl-docs/src/api/mod_perl-2.0/Apache/ServerUtil.pod
Index: ServerUtil.pod
===
RCS file: /home/cvs/modperl-docs/src/api/mod_perl-2.0/Apache/ServerUtil.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ServerUtil.pod2001/11/14 08:50:00 1.2
+++ ServerUtil.pod2001/11/20 02:35:07 1.3
@@ -24,8 +24,44 @@
Function arguments (if any) and return values are shown in the
function's synopsis.
+=head2 CONSTANTS
+
+=over
+
+=item * server_root
+
+returns the value set by the C directive.
+
+=back
+
+=head2 FUNCTIONS
+
=over
+=item * server_root_relative()
+
+Returns the canonical form of the filename made absolute to
+C:
+
+ Apache::server_root_relative($pool, $fname);
+
+C<$fname> is appended to the value of C and return
+it. e.g.:
+
+ my $log_dir = Apache::server_root_relative($r->pool, 'logs');
+
+If C<$fname> is not specified, the value of C is returned
+with a trailing C. (it's the same as using C<''> as C<$fname>'s
+value).
+
+Also see the L> constant.
+
+=back
+
+=head2 METHODS
+
+=over
+
=item * server()
The main server's object can be retrieved with:
@@ -84,26 +120,6 @@
=item * get_handlers()
-=item * server_root_relative()
-
-Returns the canonical form of the filename made absolute to
-C:
-
- Apache::server_root_relative([$fname, [$pool]]);
-
-If C<$fname> is specified, it'll be appended to the value of
-C and return it. e.g.:
-
- my $log_dir = Apache::server_root_relative('log', $r->pool);
-
-If C<$pool> is not specified, the default server startup pool is used
-(this style adds an overhead of fetching the startup data). e.g.:
-
- my $conf_dir = Apache::server_root_relative('conf');
-
-If C<$fname> is not specified, the value of C is returned
-with a trailing C. (it's the same as using C<''> as C<$fname>'s
-value).
=back
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/devel/writing_tests writing_tests.pod
stas01/11/19 20:12:48
Modified:src/devel/writing_tests writing_tests.pod
Log:
- start using t_debug() function in tests
Revision ChangesPath
1.19 +10 -7 modperl-docs/src/devel/writing_tests/writing_tests.pod
Index: writing_tests.pod
===
RCS file: /home/cvs/modperl-docs/src/devel/writing_tests/writing_tests.pod,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -r1.18 -r1.19
--- writing_tests.pod 2001/11/12 04:47:33 1.18
+++ writing_tests.pod 2001/11/20 04:12:48 1.19
@@ -639,7 +639,7 @@
my $config = Apache::Test::config();
my $hostport = Apache::TestRequest::hostport($config) || '';
- print "# connecting to $hostport\n";
+ t_debug("connecting to $hostport");
my $received = $config->http_raw_get("/TestApache::cool", undef);
my $expected = "COOL";
@@ -817,8 +817,9 @@
All the communications between tests and C which
executes them is done via STDOUT. I.e. whatever tests want to report
they do by printing something to STDOUT. If a test wants to print some
-debug comment it should do it on a separate line starting with
-C<#>.
+debug comment it should do it starting on a separate line, and each
+debug line should start with C<#>. The t_debug() function from the
+C package should be used for that purpose.
@@ -1022,9 +1023,10 @@
this test snippet:
use Apache::Test;
+ use Apache::TestUtil;
plan tests => 3;
ok "success";
- print "# expecting to fail next test\n"
+ t_debug("expecting to fail next test");
ok "";
ok 0;
@@ -1221,13 +1223,14 @@
debug_comments.t
use Apache::Test;
+ use Apache::TestUtil;
plan tests => 1;
- print "# testing feature foo\n";
+ t_debug("testing feature foo");
$expected = "a good value";
$received = "a bad value";
- print "# expected: $expected\n";
- print "# received: $received\n";
+ t_debug("expected: $expected");
+ t_debug("received: $received");
ok defined $received && $received eq $expected;
If in this example C<$received> gets assigned I string,
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/user/install install.pod
stas01/11/20 20:39:15 Modified:src/user/install install.pod Log: - rebuild trick Revision ChangesPath 1.5 +9 -0 modperl-docs/src/user/install/install.pod Index: install.pod === RCS file: /home/cvs/modperl-docs/src/user/install/install.pod,v retrieving revision 1.4 retrieving revision 1.5 diff -u -r1.4 -r1.5 --- install.pod 2001/11/12 02:44:41 1.4 +++ install.pod 2001/11/21 04:39:15 1.5 @@ -8,6 +8,15 @@ =head1 Installing from Source +=head3 Re-using Build Options + +Since mod_perl remembers what build options were used to build it, you +can use this knowledge to rebuild it using the same options. Simply +chdir to the mod_perl source directory and run: + + % cd modperl-2.0 + % perl -MApache::Build -erebuild + =head1 Installing from Binary Packages =head1 Maintainers - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/devel/core_explained core_explained.pod
stas01/11/20 20:39:52
Modified:src/devel/core_explained core_explained.pod
Log:
- partial covering of the maps files
Revision ChangesPath
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.pod2001/11/15 16:31:56 1.5
+++ core_explained.pod2001/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, I and I 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 public API.
-=head3 xs/maps
+=head2 xs/maps
The I 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 directory. This Perl representation is then used
+during C 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 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 should
+be run manually and the updated files ending up in the
+I directory should be committed to the cvs
+repository.
+
+The I make target is actually to run
+I, which can be run directly without needing to
+create I first.
+
+There are three different types of map files in the I
+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
+
+the module name where the functions should be put. e.g. C will place the functions into
+I.
+
+=item * C
+
+the package name functions belong to, defaults to C. The
+value of I 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 the C
+package will be used, if it starts with I then the C
+package is used.
+
+=item * C
+
+prefix string to be stripped from the function name. If not specified
+it defaults to C, converted to C name convention, e.g.
+C makes the prefix: I. If the converted
+prefix does not match, defaults to I or I.
+
+=item * C
+
+META: complete
+
+=item * C
+
+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
cvs commit: modperl-docs/src/user/install install.pod
stas01/11/21 19:46:09 Modified:src/user/install install.pod Log: '-e rebuild' reads better than '-erebuild' Submitted by: dougm Revision ChangesPath 1.6 +1 -1 modperl-docs/src/user/install/install.pod Index: install.pod === RCS file: /home/cvs/modperl-docs/src/user/install/install.pod,v retrieving revision 1.5 retrieving revision 1.6 diff -u -r1.5 -r1.6 --- install.pod 2001/11/21 04:39:15 1.5 +++ install.pod 2001/11/22 03:46:09 1.6 @@ -15,7 +15,7 @@ chdir to the mod_perl source directory and run: % cd modperl-2.0 - % perl -MApache::Build -erebuild + % perl -MApache::Build -e rebuild =head1 Installing from Binary Packages - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/devel/writing_tests writing_tests.pod
stas01/11/21 22:17:47 Modified:src/devel/writing_tests writing_tests.pod Log: - documenting .in conf files creation Revision ChangesPath 1.20 +89 -0 modperl-docs/src/devel/writing_tests/writing_tests.pod Index: writing_tests.pod === RCS file: /home/cvs/modperl-docs/src/devel/writing_tests/writing_tests.pod,v retrieving revision 1.19 retrieving revision 1.20 diff -u -r1.19 -r1.20 --- writing_tests.pod 2001/11/20 04:12:48 1.19 +++ writing_tests.pod 2001/11/22 06:17:47 1.20 @@ -1463,6 +1463,95 @@ META: to be completed +=head2 Extending Startup Configuration for httpd and Perl + +Sometimes you need to add extra I configuration and perl +startup specific to your project that uses C. This can +be accomplished by creating the desired files with an extension I<.in> +in the I directory and running: + + panic% t/TEST -config + +which for each file with the extension I<.in> will create a new file, +without this extension, convert any template placeholders into real +values and link it from the main I. The latter happens +only if the file have the following extensions: + +=over + +=item * .conf.in + +will add to I: + + Include foo.conf + +=item * .pl.in + +will add to I: + + PerlRequire foo.pl + +=item * other + +other files with I<.in> extension will be processed as well, but not +linked from I. + +=back + +As mentioned before the converted files are created, any special token +in them are getting replaced with the appropriate values. For example +the token C<@ServerRoot@> will be replaced with the value defined by +the C directive, so you can write a file that does the +following: + + my-extra.conf.in + + PerlSwitches [EMAIL PROTECTED]@/../lib + +and assuming that the I is I<~/modperl-2.0/t/>, when +I will be created, it'll look like: + + my-extra.conf.in + + PerlSwitches -Mlib=~/modperl-2.0/t/../lib + +The following tokens are valid: + +META: complete + + 'cgi_module_name' => 'mod_cgi', + 'conf_dir' => '/home/stas/httpd/prefork/conf', + 't_conf_file' => '/home/stas/apache.org/modperl-2.0/t/conf/httpd.conf', + 't_dir' => '/home/stas/apache.org/modperl-2.0/t', + 'cgi_module' => 'mod_cgi.c', + 'target' => 'httpd', + 'thread_module' => 'worker.c', + 'bindir' => '/home/stas/httpd/prefork/bin', + 'user' => 'stas', + 'top_dir' => '/home/stas/apache.org/modperl-2.0', + 'httpd_conf' => '/home/stas/httpd/prefork/conf/httpd.conf', + 'httpd' => '/home/stas/httpd/prefork/bin/httpd', + 'scheme' => 'http', + 'ssl_module_name' => 'mod_ssl', + 'port' => 8529, + 'sbindir' => '/home/stas/httpd/prefork/bin', + 't_conf' => '/home/stas/apache.org/modperl-2.0/t/conf', + 'servername' => 'localhost.localdomain', + 'inherit_documentroot' => '/home/stas/httpd/prefork/htdocs', + 'proxy' => 'off', + 'serveradmin' => '[EMAIL PROTECTED]', + 'remote_addr' => '127.0.0.1', + 'perlpod' => '/home/stas/perl/ithread/lib/5.7.2/pod', + 'ssl_module' => 'mod_ssl.c', + 't_logs' => '/home/stas/apache.org/modperl-2.0/t/logs', + 'maxclients' => 1, + 'group' => 'stas', + 'thread_module_name' => 'worker', + 'documentroot' => '/home/stas/apache.org/modperl-2.0/t/htdocs', + 'serverroot' => '/home/stas/apache.org/modperl-2.0/t', + 'perl' => '/home/stas/perl/ithread/bin/perl', + 'src_dir' => '/home/stas/apache.org/modperl-2.0/src/modules/perl' + =head2 Threaded versus Non-threaded Perl Test's Compatibility Since the tests are supposed to run properly under non-threaded and - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/devel/core_explained core_explained.pod
stas01/11/22 07:43:58 Modified:src/devel/core_explained core_explained.pod Log: xs_generate is running from Makefile.PL only if MP_GENERATE_XS=1 Revision ChangesPath 1.7 +4 -3 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.6 retrieving revision 1.7 diff -u -r1.6 -r1.7 --- core_explained.pod2001/11/21 04:39:52 1.6 +++ core_explained.pod2001/11/22 15:43:58 1.7 @@ -228,8 +228,8 @@ converted into I. If you don't want to do a visual check on how XS code will be -generated, just rebuild the project starting with C. Otherwise run: +generated, just rebuild the project starting with C. Otherwise run: % make xs_generate @@ -239,7 +239,8 @@ =head2 XS generation process As mentioned before XS code is generated in the I directory -either during C via xs_generate() or explicitly via: +either during C via xs_generate() if +C is used or explicitly via: % make xs_generate - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/user/compat - New directory
stas01/11/25 19:28:00 modperl-docs/src/user/compat - New directory - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/user/compat compat.pod
stas01/11/25 19:28:46 Added: src/user/compat compat.pod Log: - start documenting 1.x vs 2.x compatibility issues Revision ChangesPath 1.1 modperl-docs/src/user/compat/compat.pod Index: compat.pod === =head1 NAME mod_perl 1.x versus mod_perl 2.x compatibility issues =head1 Code Porting from 1.x to 2.x mod_perl 2.x is trying hard to be back compatible with mod_perl 1.x. However some things (mostly APIs) have been changed. In order to gain a complete compatibilty with 1.x while running under 2.x, you should simply load the compatibility module: use Apache::compat; at the server startup. And unless there are forgotten things or bugs, your code should work without any changes under 2.x series. However, unless you want to keep the 1.x compatibility, you should try to remove the compatibility layer and adjust your code to work under 2.x without it. You want to do it mainly for the performance improvement. This document explains what APIs have changed and what new APIs should be used instead. =head1 Apache::Registry and Apache::PerlRun =head1 Apache::File =head1 Maintainers Maintainer is the person(s) you should contact with updates, corrections and patches. Stas Bekman Estas (at) stason.orgE =head1 Authors =over =item * Stas Bekman Estas (at) stason.orgE =back =cut - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/devel/writing_tests writing_tests.pod
stas01/11/27 18:22:52 Modified:src/devel/writing_tests writing_tests.pod Log: - add the valid configuration tokens location Revision ChangesPath 1.21 +3 -36 modperl-docs/src/devel/writing_tests/writing_tests.pod Index: writing_tests.pod === RCS file: /home/cvs/modperl-docs/src/devel/writing_tests/writing_tests.pod,v retrieving revision 1.20 retrieving revision 1.21 diff -u -r1.20 -r1.21 --- writing_tests.pod 2001/11/22 06:17:47 1.20 +++ writing_tests.pod 2001/11/28 02:22:52 1.21 @@ -1515,42 +1515,9 @@ PerlSwitches -Mlib=~/modperl-2.0/t/../lib -The following tokens are valid: - -META: complete - - 'cgi_module_name' => 'mod_cgi', - 'conf_dir' => '/home/stas/httpd/prefork/conf', - 't_conf_file' => '/home/stas/apache.org/modperl-2.0/t/conf/httpd.conf', - 't_dir' => '/home/stas/apache.org/modperl-2.0/t', - 'cgi_module' => 'mod_cgi.c', - 'target' => 'httpd', - 'thread_module' => 'worker.c', - 'bindir' => '/home/stas/httpd/prefork/bin', - 'user' => 'stas', - 'top_dir' => '/home/stas/apache.org/modperl-2.0', - 'httpd_conf' => '/home/stas/httpd/prefork/conf/httpd.conf', - 'httpd' => '/home/stas/httpd/prefork/bin/httpd', - 'scheme' => 'http', - 'ssl_module_name' => 'mod_ssl', - 'port' => 8529, - 'sbindir' => '/home/stas/httpd/prefork/bin', - 't_conf' => '/home/stas/apache.org/modperl-2.0/t/conf', - 'servername' => 'localhost.localdomain', - 'inherit_documentroot' => '/home/stas/httpd/prefork/htdocs', - 'proxy' => 'off', - 'serveradmin' => '[EMAIL PROTECTED]', - 'remote_addr' => '127.0.0.1', - 'perlpod' => '/home/stas/perl/ithread/lib/5.7.2/pod', - 'ssl_module' => 'mod_ssl.c', - 't_logs' => '/home/stas/apache.org/modperl-2.0/t/logs', - 'maxclients' => 1, - 'group' => 'stas', - 'thread_module_name' => 'worker', - 'documentroot' => '/home/stas/apache.org/modperl-2.0/t/htdocs', - 'serverroot' => '/home/stas/apache.org/modperl-2.0/t', - 'perl' => '/home/stas/perl/ithread/bin/perl', - 'src_dir' => '/home/stas/apache.org/modperl-2.0/src/modules/perl' +The valid tokens are defined in C<%Apache::TestConfig::Usage> and also +can be in the output of C's I +section. The tokens are case insensitive. =head2 Threaded versus Non-threaded Perl Test's Compatibility - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/devel/writing_tests writing_tests.pod
stas01/11/27 18:37:31 Modified:src/devel/writing_tests writing_tests.pod Log: a typo Revision ChangesPath 1.22 +2 -2 modperl-docs/src/devel/writing_tests/writing_tests.pod Index: writing_tests.pod === RCS file: /home/cvs/modperl-docs/src/devel/writing_tests/writing_tests.pod,v retrieving revision 1.21 retrieving revision 1.22 diff -u -r1.21 -r1.22 --- writing_tests.pod 2001/11/28 02:22:52 1.21 +++ writing_tests.pod 2001/11/28 02:37:31 1.22 @@ -1516,8 +1516,8 @@ PerlSwitches -Mlib=~/modperl-2.0/t/../lib The valid tokens are defined in C<%Apache::TestConfig::Usage> and also -can be in the output of C's I -section. The tokens are case insensitive. +can be seen in the output of C's I section. The tokens are case insensitive. =head2 Threaded versus Non-threaded Perl Test's Compatibility - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/devel/core_explained core_explained.pod
stas01/11/29 08:26:32
Modified:src/devel/core_explained core_explained.pod
Log:
- document the BOOT= directive in the map file
Revision ChangesPath
1.8 +36 -3 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.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- core_explained.pod2001/11/22 15:43:58 1.7
+++ core_explained.pod2001/11/29 16:26:32 1.8
@@ -156,7 +156,40 @@
=item * C
-META: complete
+The C directive tells the XS generator, whether to add the boot
+function to the autogenerated XS file or not. If the value of C
+is not true or it's simply not declared, the boot function won't be
+added.
+
+If the value is true, a boot function will be added to the XS file.
+Note, that this function is not declared in the map file.
+
+The boot function name must be constructed from three parts:
+
+ 'mpxs_' . MODULE . '_BOOT'
+
+where C is the one declared with C in the map file.
+
+For example if we want to have an XS boot function for a class
+C, we create this function in I:
+
+ static void mpxs_APR__IO_BOOT(pTHX)
+ {
+ /* boot code here */
+ }
+
+and now we add the C declaration to the
+I file:
+
+ MODULE=APR::IO PACKAGE=APR::IO BOOT=1
+
+When I is run (after running I),
+it autogenerates I and amongst other things will
+include:
+
+ BOOT:
+ mpxs_APR__IO_BOOT(aTHXo);
+
=item * C
@@ -164,8 +197,8 @@
=back
-Every function definition is declared on a separate line, using the
-following format:
+Every function definition is declared on a separate line (use C<\> if
+the line is too long), using the following format:
C function name | Dispatch function name | Argspec | Perl alias
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/world/templates choosing.pod
stas01/11/11 18:44:41 Modified:src/devel/core_explained core_explained.pod src/devel/modperl_style modperl_style.pod src/devel/porting_from_1.x porting_from_1.x.pod src/devel/writing_tests writing_tests.pod src/user/coding coding.pod src/user/install install.pod src/user/intro start_fast.pod src/world/templates choosing.pod Log: use NAME as a header to aid converting Revision ChangesPath 1.4 +4 -2 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.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- core_explained.pod2001/09/15 18:49:02 1.3 +++ core_explained.pod2001/11/12 02:44:40 1.4 @@ -1,5 +1,7 @@ -=head1 mod_perl 2.0 Source Code Explained +=head1 NAME +mod_perl 2.0 Source Code Explained + =head1 Code Layout Apache-Test/ - test kit for mod_perl and Apache::* modules @@ -16,7 +18,7 @@ xs/ -=head1 +=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 1.4 +3 -1 modperl-docs/src/devel/modperl_style/modperl_style.pod Index: modperl_style.pod === RCS file: /home/cvs/modperl-docs/src/devel/modperl_style/modperl_style.pod,v retrieving revision 1.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- modperl_style.pod 2001/10/02 15:27:02 1.3 +++ modperl_style.pod 2001/11/12 02:44:40 1.4 @@ -1,4 +1,6 @@ -=head1 mod_perl Code Development Style Guide +=head1 NAME + +mod_perl Code Development Style Guide =head1 Coding Style Guide 1.2 +3 -1 modperl-docs/src/devel/porting_from_1.x/porting_from_1.x.pod Index: porting_from_1.x.pod === RCS file: /home/cvs/modperl-docs/src/devel/porting_from_1.x/porting_from_1.x.pod,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- porting_from_1.x.pod 2001/10/22 06:50:14 1.1 +++ porting_from_1.x.pod 2001/11/12 02:44:40 1.2 @@ -1,4 +1,6 @@ -=head1 Porting Modules from mod_perl 1.x to 2.x +=head1 NAME + +Porting Modules from mod_perl 1.x to 2.x =head1 Introduction 1.16 +4 -2 modperl-docs/src/devel/writing_tests/writing_tests.pod Index: writing_tests.pod === RCS file: /home/cvs/modperl-docs/src/devel/writing_tests/writing_tests.pod,v retrieving revision 1.15 retrieving revision 1.16 diff -u -r1.15 -r1.16 --- writing_tests.pod 2001/10/23 03:15:56 1.15 +++ writing_tests.pod 2001/11/12 02:44:40 1.16 @@ -1,5 +1,7 @@ -=head1 Developing and Running Tests with the C Framework +=head1 NAME +Developing and Running Tests with the C Framework + =head1 Introduction This chapter is talking about the C framework, and in @@ -1105,7 +1107,7 @@ know that some sub-test is failing but for some reason we want to flag it as a todo sub-test and not as a broken test. C recognizes I sub-tests if the standard output line contains the -substring I< # TODO> after i or I and is +substring I< # TODO> after I or I and is counted as a todo sub-test. The text afterwards is the explanation of the thing that has to be done before this sub-test will succeed. For example: 1.3 +3 -1 modperl-docs/src/user/coding/coding.pod Index: coding.pod === RCS file: /home/cvs/modperl-docs/src/user/coding/coding.pod,v retrieving revision 1.2 retrieving revision 1.3 diff -u -r1.2 -r1.3 --- coding.pod2001/10/10 05:26:27 1.2 +++ coding.pod2001/11/12 02:44:40 1.3 @@ -1,4 +1,6 @@ -=head1 Coding with and for mod_perl +=head1 NAME + +Coding with and for mod_perl =head1 Prerequisites 1.4 +5 -1 modperl-docs/src/user/install/install.pod Index: install.pod === RCS file: /home/cvs/modperl-docs/src/user/install/install.pod,v retrieving revision 1.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- install.pod 2001/09/15 18:49:02 1.3 +++ install.pod 2001/11/12 02:44:41 1.4 @@ -1,6 +1,10 @@ -=head1 Installing mod_perl +=head1 NAME +Installing mod_perl + =head1 Prerequisites + +Lots of prerequisites =head1 Installing from Source 1.4 +3 -1
cvs commit: modperl-docs/src/devel/writing_tests writing_tests.pod
stas01/12/05 00:10:37 Modified:src/devel/writing_tests writing_tests.pod Log: - document the stressing run option Revision ChangesPath 1.23 +81 -4 modperl-docs/src/devel/writing_tests/writing_tests.pod Index: writing_tests.pod === RCS file: /home/cvs/modperl-docs/src/devel/writing_tests/writing_tests.pod,v retrieving revision 1.22 retrieving revision 1.23 diff -u -r1.22 -r1.23 --- writing_tests.pod 2001/11/28 02:37:31 1.22 +++ writing_tests.pod 2001/12/05 08:10:37 1.23 @@ -111,6 +111,8 @@ testing environments which both use C for their test suites. +=head2 Basic Testing + Running tests is just like for any CPAN Perl module; first we create the I and build everything with I: @@ -156,13 +158,17 @@ want to wait for the server to start every time. You can start it once: - % t/TEST -start + % t/TEST -start-httpd and then run tests without restarting the server using I<-run> option: % t/TEST -run + +When you are done with tests, stop the server with: + + % t/TEST -stop-httpd -Once the server is started you can modify I<.t> files and rerun the +When the server is started you can modify I<.t> files and rerun the tests without restarting the server. However if you modify response handlers, you must restart the server for changes to take an effect. If C is used and configured to automatically @@ -206,7 +212,7 @@ The command: - % t/TEST -start + % t/TEST -start-httpd always stops the server first if any is running. In case you have a server runnning on the same port, (for example if you develop the a @@ -215,10 +221,81 @@ pick a free port, but you can explicitly tell on which port to run, using the I<-port> configuration option: - % t/TEST -start -port 8799 + % t/TEST -start-httpd -port 8799 or by setting an evironment variable C to the desired value before starting the server. + +=head2 Stress Testing + +Normally when I is run without specifying the tests to run, +the tests will be sorted alphabetically. If tests are explicitly +passed as arguments to I they will be run in a specified +order. + +There are a few options useful for stress testing. + +=over + +=item -times + +You can run the tests N times by using the I<-times> option. For +example to run all the tests 3 times specify: + + % t/TEST -times=3 + +=item -order + +It's possible that certain tests aren't cleaning up after themselves +and modify the state of the server, which may influence other +tests. But since normally all the tests are run in the same order, the +potential problem may not be discovered until the code is used in +production, where the real world testing hits the problem. Therefore +in order to try to detect as many problems as possible during the +testing process, it's may be useful to run tests in different orders. + +This if of course mosly useful in conjunction with I<-times=N> option. + +Assuming that we have tests a, b and c: + +=over + +=item * -order=rotate + +rotate the tests: a, b, c, a, b, c + +=item * -order=repeat + +repeat the tests: a, a, b, b, c, c + +=item * -order=random + +run in the random order, e.g.: a, c, c, b, a, b + +In this mode the used srand() seed is printed to STDOUT, so it then +can be used to rerun the tests in exactly the same order. + +=item * -order=SEED + +used to initialize the pseudo-random algorithm, which allows to +reproduce the same sequence of tests. For example if we run: + + % t/TEST -order=random -times=5 + +and the seed 234559 is used, we can repeat the same order of tests, by +running: + + % t/TEST -order=234559 -times=5 + +Alternatively, the environment variable C can be set +to the value of seed. + +=back + +=back + + + META: a lot more stuff to go here from the pods/modperl_dev.pod and Apache-Test/README - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/user/compat compat.pod
stas01/12/13 20:56:17 Modified:src/user/compat compat.pod Log: Apache->gensym now lives in compat Revision ChangesPath 1.2 +15 -0 modperl-docs/src/user/compat/compat.pod Index: compat.pod === RCS file: /home/cvs/modperl-docs/src/user/compat/compat.pod,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- compat.pod2001/11/26 03:28:46 1.1 +++ compat.pod2001/12/14 04:56:17 1.2 @@ -22,10 +22,25 @@ This document explains what APIs have changed and what new APIs should be used instead. +=head1 Apache methods + +=head2 gensym + +Since Perl 5.6.1 filehandlers are autovivified and there is no need +for gensym() function, since now it can be done with: + + open my $fh, "foo" or die $!; + +The C function modperl_perl_gensym() is available for XS/C extension +writers, though. + =head1 Apache::Registry and Apache::PerlRun =head1 Apache::File +=head1 Apache::StatINC + +C has been replaced by C. =head1 Maintainers - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/user/config - New directory
stas01/12/17 18:52:59 modperl-docs/src/user/config - New directory - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/user/config config.pod
stas01/12/17 18:59:44
Added: src/user/config config.pod
Log:
- starting config doc.
- documenting how to retrieve server startup options.
Revision ChangesPath
1.1 modperl-docs/src/user/config/config.pod
Index: config.pod
===
=head1 NAME
Server Configuration
=head1 Retrieving Server Startup Options
The httpd server startup options can retrieved using
C. For example this checks whether the
server has been started in a single mode:
if (Apache::exists_config_define("ONE_PROCESS")) {
print "Running in a single mode";
}
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
corrections and patches.
Stas Bekman Estas (at) stason.orgE
=head1 Authors
=over
=item * Stas Bekman Estas (at) stason.orgE
=back
=cut
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/user/compat compat.pod
stas01/12/21 06:58:43 Modified:src/user/compat compat.pod Log: - mention a need to build modperl with MP_COMPAT_1X=1 to gain compat level of 1x Revision ChangesPath 1.3 +2 -1 modperl-docs/src/user/compat/compat.pod Index: compat.pod === RCS file: /home/cvs/modperl-docs/src/user/compat/compat.pod,v retrieving revision 1.2 retrieving revision 1.3 diff -u -r1.2 -r1.3 --- compat.pod2001/12/14 04:56:17 1.2 +++ compat.pod2001/12/21 14:58:43 1.3 @@ -7,7 +7,8 @@ mod_perl 2.x is trying hard to be back compatible with mod_perl 1.x. However some things (mostly APIs) have been changed. In order to gain a complete compatibilty with 1.x while running under 2.x, you -should simply load the compatibility module: +should build mod_perl with C and simply load the +compatibility module: use Apache::compat; - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/user/compat compat.pod
stas01/12/21 07:24:35 Modified:src/user/compat compat.pod Log: - document the Configuration Directives that have changed in 2.x Revision ChangesPath 1.4 +69 -5 modperl-docs/src/user/compat/compat.pod Index: compat.pod === RCS file: /home/cvs/modperl-docs/src/user/compat/compat.pod,v retrieving revision 1.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- compat.pod2001/12/21 14:58:43 1.3 +++ compat.pod2001/12/21 15:24:35 1.4 @@ -7,8 +7,8 @@ mod_perl 2.x is trying hard to be back compatible with mod_perl 1.x. However some things (mostly APIs) have been changed. In order to gain a complete compatibilty with 1.x while running under 2.x, you -should build mod_perl with C and simply load the -compatibility module: +should build mod_perl with C and load the +compatibility module as early as possible: use Apache::compat; @@ -23,8 +23,62 @@ This document explains what APIs have changed and what new APIs should be used instead. -=head1 Apache methods +=head1 Configuration Directives +To continue using mod_perl configuration files from 1.x, build +mod_perl with C. To migrate the configuration files to +the 2.x syntax, you may need to do certain adjustments if you use any +of the configuration directives listed in the following sections. + +Remember that if you use any of the new directives you configuration +won't work anymore with mod_perl 1.x. + +=head2 PerlHandler + +Replaced with C. + +=head2 PerlSendHeader + +Replaced with C directive. + + PerlSendHeader On => Options +ParseHeaders + PerlSendHeader Off => Options -ParseHeaders + +=head2 PerlSetupEnv + +Replaced with C directive. + + PerlSendHeader On => Options +SetupEnv + PerlSendHeader Off => Options -SetupEnv + +=head2 PerlTaintCheck + +Now can be turned on with: + + PerlSwitches -T + +The default is I. You cannot turn it I once it's turned +I. + +=head2 PerlWarn + +Now can be turned on with: + + PerlSwitches -w + + + + + +=head1 Apache API + +To continue using Apache API from 1.x, load the compatibility module +as early as possible: + + use Apache::compat; + +at the server startup. + =head2 gensym Since Perl 5.6.1 filehandlers are autovivified and there is no need @@ -34,14 +88,24 @@ The C function modperl_perl_gensym() is available for XS/C extension writers, though. + +=head2 Apache::File + + -=head1 Apache::Registry and Apache::PerlRun +=head1 Apache::Registry and Apache::PerlRun and Other mod_cgi Emulators -=head1 Apache::File +C and C now live in the +C namespace to avoid collisions with the versions from 1.x. +META: complete + + =head1 Apache::StatINC C has been replaced by C. + + =head1 Maintainers - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/devel/core_explained core_explained.pod
stas01/12/21 08:54:20
Modified:src/devel/core_explained core_explained.pod
Log:
- add a writeup on MP_INLINE vs C Macros vs Normal Functions
Revision ChangesPath
1.10 +138 -0modperl-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.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- core_explained.pod2001/12/04 06:37:14 1.9
+++ core_explained.pod2001/12/21 16:54:20 1.10
@@ -238,6 +238,7 @@
name is just a prefix (I, I) the C function name is
appended to it.
+See the explanation about function naming and arguments passing.
=item * Argspec
@@ -296,6 +297,143 @@
modperl_xs_sv_convert.h
modperl_xs_typedefs.h
+=head1 mpxs_ vs MPXS_
+
+If you look at the source code there are functions starting with
+I and those with I.
+
+If you want to mess directly with the stack (i.e. without specifying
+the prototype of the function), there are two ways to do that. Either
+the function has to have a prototype C<...> (which stands for
+I, I and I arguments) or prefixed with I,
+which are hooked directly into newXS().
+
+META: complete
+
+
+=head1 MP_INLINE vs C Macros vs Normal Functions
+
+To make the code maintainable and reusable functions and macros are
+used in when programming in C (and other languages :).
+
+When function is marked as I it's merely a hint to the
+compiler to replace the call to a function with the code inside this
+function (i.e. inlined). Not every function can be inlined. Some
+typical reasons why inlining is sometimes not done include:
+
+=over
+
+=item *
+
+the function calls itself, that is, is recursive
+
+=item *
+
+the function contains loops such as C or C
+
+=item *
+
+the function size is too large
+
+=back
+
+Most of the advantage of inline functions comes from avoiding the
+overhead of calling an actual function. Such overhead includes saving
+registers, setting up stack frames, etc. But with large functions the
+overhead becomes less important.
+
+Use the C keyword in the declaration of the functions that
+are to be inlined. The functions should be inlined when:
+
+=over
+
+=item *
+
+Only ever called once (the I that are called from I<.xs>
+files), no matter what the size of code is.
+
+=item *
+
+Short bodies of code called in a I code (like
+I, which is called many times inside of a loop),
+where it is cleaner to see the code in function form rather than macro
+with lots of C<\>'s. Remember that an inline function takes much more
+space than a normal functions if called from many places in the code.
+
+=back
+
+Of course C macros are a bit faster then inlined functions, since
+there is not even I to be made, the code is literally
+copied into the place it's called from. However using macros comes at
+a price:
+
+=over
+
+=item *
+
+Also unlike macros, in functions argument types are checked, and
+necessary conversions are performed correctly. With macros it's
+possible that weird things will happen if the caller has passed
+arguments of the wrong type when calling a macro.
+
+=item *
+
+One should be careful to pass only absolute values as I<"arguments">
+to macros. Consider a macro that returns an absolute value of the
+passed argument:
+
+ #define ABS(v) ( (v) >= 0 ? (v) : -(v) )
+
+In our example if you happen to pass a function it will be called
+twice:
+
+ abs_val = ABS(f());
+
+Since it'll be extended as:
+
+ abs_val = f() >= 0 ? f() : -f();
+
+You cannot do simple operation like increment--in our example it will
+be called twice:
+
+ abs_val = ABS(i++);
+
+Because it becomes:
+
+ abs_val = i++ >= 0 ? i++ : -i++;
+
+=item *
+
+It's dangerous to use the if() condition without enclosing the code in
+C<{}>, since the macro may be called from inside another if-else
+condition, which may cause the else part called if the if() part from
+the macro fails.
+
+But we always use C<{}> for the code inside the if-else condition, so
+it's not a problem here.
+
+=item *
+
+A multi-line macro can cause problems if someone uses the macro in a
+context that demands a single statement.
+
+ while (foo) MYMACRO(bar);
+
+But again, we always enclose any code in conditional with C<{}>, so
+it's not a problem for us.
+
+=item *
+
+Inline functions present a problem for debuggers and profilers,
+because the function is expanded at the point of call and loses its
+identity. This makes the debugging process a nightmare.
+
+A
cvs commit: modperl-docs/src/devel/writing_tests writing_tests.pod
stas01/12/23 21:47:46
Modified:src/devel/writing_tests writing_tests.pod
Log:
- update the docs for skip_unless
Revision ChangesPath
1.24 +28 -8 modperl-docs/src/devel/writing_tests/writing_tests.pod
Index: writing_tests.pod
===
RCS file: /home/cvs/modperl-docs/src/devel/writing_tests/writing_tests.pod,v
retrieving revision 1.23
retrieving revision 1.24
diff -u -r1.23 -r1.24
--- writing_tests.pod 2001/12/05 08:10:37 1.23
+++ writing_tests.pod 2001/12/24 05:47:46 1.24
@@ -973,16 +973,36 @@
=item * skip_unless()
-Instead of using a scalar as a last argument to plan() to tell whether
-to skip the test or not, it's better to use skip_unless() which also
-prints the reason for skipping the test if the condition is not
-satisfied. For example:
+Alternatively to specifying a last argument for plan(), the
+skip_unless() function can be called before plan(), to decide whether
+to skip the whole test or not. plan() won't be reached if skip_unless
+decides to skip the test.
- plan tests => 5, skip_unless(sub { $a == $b }, "$a != $b");
+skip_unless()'s argument is a list of things to test. The list can
+include scalars, which are passed to have_module(), and hash
+references. The hash references have a condition code reference as a
+key and a reason for failure as a value. The condition code is run and
+if it fails the provided reason is used to tell user why the test was
+skipped.
-skip_unless() executes the code reference in the first argument and if
-it returns a false value C<$reason> gets printed as a reason for test
-skipping.
+For example:
+
+ skip_unless({sub {$a==$b} => "$a != $b!"
+ sub {$a==1} => "$a != 1!"},
+ 'LWP',
+ 'cgi_d',
+ {sub {0} => "forced to be skipped"},
+ );
+ plan tests => 5;
+
+In this example, the first argument is a hash reference which includes
+two pairs of condition test functions and the corresponding reasons,
+the second and the third arguments are scalars passed to have_module()
+and the last argument is another hash reference with a single
+condition. This is just to demonstrate that you can supply conditions
+in various syntaxes without particular order. If any of the
+requirements from this list fail, plan() won't be called since
+skip_unless() will call exit().
=item * have_module()
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/devel/writing_tests writing_tests.pod
stas01/12/24 11:30:25
Modified:src/devel/writing_tests writing_tests.pod
Log:
document how to:
- start multiple servers
- use multiple user agents
- hit the same interpreter
Revision ChangesPath
1.25 +133 -0modperl-docs/src/devel/writing_tests/writing_tests.pod
Index: writing_tests.pod
===
RCS file: /home/cvs/modperl-docs/src/devel/writing_tests/writing_tests.pod,v
retrieving revision 1.24
retrieving revision 1.25
diff -u -r1.24 -r1.25
--- writing_tests.pod 2001/12/24 05:47:46 1.24
+++ writing_tests.pod 2001/12/24 19:30:25 1.25
@@ -888,6 +888,139 @@
=back
+=head2 Request Generation Methods
+
+META: here goes the explanation of shortcuts: GET_BODY, POST_BODY,
+etc.
+
+=head2 Starting Multiple Servers
+
+By default the C framework sets up only a single server
+to test against.
+
+In some cases you need to have more than one server. If this is the
+situation, you have to override the I configuration
+directive, whose default is 1. Usually this is done in C by
+subclassing the parent test run class and overriding the
+new_test_config() method. For example if the parent class is
+C, you can change your C to be:
+
+ use strict;
+ use warnings FATAL => 'all';
+
+ use lib "../lib"; # test against the source lib for easier dev
+ use lib map {("../blib/$_", "../../blib/$_")} qw(lib arch);
+
+ use Apache::TestRunPerl ();
+
+ package MyTest;
+
+ our @ISA = qw(Apache::TestRunPerl);
+
+ # subclass new_test_config to add some config vars which will be
+ # replaced in generated httpd.conf
+ sub new_test_config {
+ my $self = shift;
+
+ $self->{conf_opts}->{maxclients} = 2;
+
+ return $self->SUPER::new_test_config;
+ }
+
+ MyTest->new->run(@ARGV);
+
+=head2 Multiple User Agents
+
+By default the C framework uses a single user agent
+which talks to the server (this is the C user agent, if you have
+C installed). You almost never use this agent directly in the
+tests, but via various wrappers. However if you need a second user
+agent you can clone these. For example:
+
+ my $ua2 = Apache::TestRequest::user_agent()->clone;
+
+
+=head2 Hitting the Same Interpreter (Server Thread/Process Instance)
+
+When a single instance of the server thread/process is running, all
+the tests go through the same server. However if the C
+framework was configured to to run a few instances, two subsequent
+sub-tests may not hit the same server instance. In certain tests
+(e.g. testing the closure effect or the C blocks) it's
+important to make sure that a sequence of sub-tests are run against
+the same server instance. The C framework supports this
+internally.
+
+Here is an example from C closure tests. Using the
+counter closure problem under C:
+
+ cgi-bin/closure.pl
+ --
+ #!perl -w
+ print "Content-type: text/plain\r\n\r\n";
+
+ # this is a closure (when compiled inside handler()):
+ my $counter = 0;
+ counter();
+
+ sub counter {
+ #warn "$$";
+ print ++$counter;
+ }
+
+If this script get invoked twice in a row and we make sure that it
+gets executed by the same server instance, the first time it'll return
+1 and the second time 2. So here is the gist of the request part that
+makes sure that its two subsequent requests hit the same server
+instance:
+
+ closure.t
+ -
+ ...
+ my $url = "/same_interp/cgi-bin/closure.pl";
+ my $same_interp = Apache::TestRequest::same_interp_tie($url);
+
+ # should be no closure effect, always returns 1
+ my $first = req($same_interp, $url);
+ my $second = req($same_interp, $url);
+ ok t_cmp(
+ 1,
+ $first && $second && ($second - $first),
+ "the closure problem is there",
+ );
+ sub req {
+ my($same_interp, $url) = @_;
+ my $res = Apache::TestRequest::same_interp_do($same_interp,
+\&GET, $url);
+ return $res ? $res->content : undef;
+ }
+
+In this test we generate two requests to I and
+expect the returned value to increment for each new request, because
+of the closure problem generated by C. Since we
+don't know whether some other test has called this script already, we
+simply check whether the substraction of the two subsequent requests'
+outputs gives a value of 1.
+
+The test starts by requesting the server to tie a single instance to
+all requests made with a certain identifier. This is done using the
+same_interp_tie() function which returns a unique server instance's
+indentifier
cvs commit: modperl-docs/admin doc_template.pod
stas01/12/24 21:23:22 Modified:admindoc_template.pod Log: - correct the doc template Revision ChangesPath 1.2 +11 -3 modperl-docs/admin/doc_template.pod Index: doc_template.pod === RCS file: /home/cvs/modperl-docs/admin/doc_template.pod,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- doc_template.pod 2001/09/17 15:31:24 1.1 +++ doc_template.pod 2001/12/25 05:23:22 1.2 @@ -1,5 +1,7 @@ -=head1 PAGE TITLE +=head1 NAME +TITLE goes here + =head1 ... =head2 ... @@ -9,11 +11,17 @@ Maintainer is the person(s) you should contact with updates, corrections and patches. -Foo Bar E[EMAIL PROTECTED] +Foo Bar Efoo (at) bar.example.comE =head1 Authors + +=over + +=item * Foo Bar Efoo (at) bar.example.comE + +=item * Foo Tar Efoo (at) tar.example.comE -Foo Bar E[EMAIL PROTECTED] +=back =cut - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/admin style.pod
stas01/12/24 21:23:41 Modified:adminstyle.pod Log: - suggest using example.com/localhost in examples Revision ChangesPath 1.2 +14 -3 modperl-docs/admin/style.pod Index: style.pod === RCS file: /home/cvs/modperl-docs/admin/style.pod,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- style.pod 2001/09/15 18:48:43 1.1 +++ style.pod 2001/12/25 05:23:41 1.2 @@ -24,10 +24,17 @@ =item * -Keep the text width < 74 cols. +When using domain names in examples use only I and its +derivatives (e.g. I) or I (or +I). I is an official example +domain. =item * +Keep the text width <= 74 cols. + +=item * + Please avoid leaving ^M (CR on the DOS platforms). Either use the editor to remove these new line chars, or use Perl: @@ -271,10 +278,14 @@ Maintainer is the person(s) you should contact with updates, corrections and patches. -Stas Bekman E[EMAIL PROTECTED] +Stas Bekman Estas (at) stason.orgE =head1 Authors -Stas Bekman E[EMAIL PROTECTED] +=over + +=item * Stas Bekman Estas (at) stason.orgE + +=back =cut - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/api/mod_perl-2.0/APR PerlIO.pod
stas01/12/24 23:37:33
Added: src/api/mod_perl-2.0/APR PerlIO.pod
Log:
- start APR::PerlIO docs
Revision ChangesPath
1.1 modperl-docs/src/api/mod_perl-2.0/APR/PerlIO.pod
Index: PerlIO.pod
===
=head1 NAME
C -- An APR Perl IO layer
=head1 SYNOPSIS
use APR::PerlIO ();
sub handler {
my $r = shift;
open my $fh, ">:APR", $filename, $r or die $!;
# work with $fh as normal $fh
close $fh;
return Apache::OK;
}
=head1 DESCRIPTION
C implements a Perl IO layer using APR's file
manipulation as its internals. Why do you want to use this? Normally
you shouldn't, probably it won't be faster than Perl's default
layer. It's only useful when you need to manipulate a filehandle
opened at the APR side, while using Perl.
Normally you won't call open() with APR layer attribute, but some
mod_perl functions will return a filehandle which is internally hooked
to APR. But you can use APR Perl IO directly if you want.
=head1 SYNOPSIS
Perl Interface:
=over
=item open()
To use APR Perl IO to open a file the four arguments open() should be
used. For example:
open my $fh, ">:APR", $filename, $r or die $!;
where:
the second argument is the mode to open the file, constructed from two
sections separated by the C<:> character: the first section is the
mode to open the file under (E, E, etc) and the second section
must be a string I.
the fourth argument can be a C or
C object.
the rest of the arguments are the same as described by the I
manpage.
=back
The C interface provides functions to convert between Perl IO and
APR Perl IO filehandles.
=head1 SEE ALSO
L, L, L.
=cut
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/api/mod_perl-2.0 Makefile.PL
stas01/12/25 04:44:49
Modified:.Makefile.PL
src/docs/2.0/api/mod_perl-2.0 Makefile.PL
Log:
- api docs location's path change adjustments s|docs/src/api|docs/api|
Revision ChangesPath
1.56 +1 -1 modperl-2.0/Makefile.PL
Index: Makefile.PL
===
RCS file: /home/cvs/modperl-2.0/Makefile.PL,v
retrieving revision 1.55
retrieving revision 1.56
diff -u -r1.55 -r1.56
--- Makefile.PL 2001/12/10 06:29:27 1.55
+++ Makefile.PL 2001/12/25 12:44:49 1.56
@@ -32,7 +32,7 @@
#NMAKE : fatal error U1077: 'cd' : return code '0x2'
#Stop.
my @remote_makefile_dirs = Apache::Build::is_win32() ? () :
- qw(docs/src/api/mod_perl-2.0);
+ qw(docs/api/mod_perl-2.0);
my @scripts = qw(t/TEST t/SMOKE);
configure();
1.2 +3 -3 modperl-docs/src/docs/2.0/api/mod_perl-2.0/Makefile.PL
Index: Makefile.PL
===
RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/mod_perl-2.0/Makefile.PL,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- Makefile.PL 2001/10/04 10:53:20 1.1
+++ Makefile.PL 2001/12/25 12:44:49 1.2
@@ -6,7 +6,7 @@
use ExtUtils::MakeMaker;
-my $rel_path = File::Spec->catfile(('..') x 4);
+my $rel_path = File::Spec->catfile(('..') x 3);
WriteMakefile(
NAME => 'API',
@@ -22,8 +22,8 @@
package MY;
-# when called from top mod_perl dir, it gets ../blib for all pathes,
-# so we want to point it back to the top blib.
+# when called from top mod_perl dir, it gets ../blib for all paths, so
+# we want to point it back to the top blib dir.
sub MY::constants {
my $self = shift;
for (grep /^INST_/, keys %{ $self } ) {
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/devel/writing_tests writing_tests.pod
stas01/12/26 20:57:44 Modified:src/docs/2.0/devel/writing_tests writing_tests.pod Log: - document Apache::TestSmoke functionality Revision ChangesPath 1.26 +184 -9 modperl-docs/src/docs/2.0/devel/writing_tests/writing_tests.pod Index: writing_tests.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/devel/writing_tests/writing_tests.pod,v retrieving revision 1.25 retrieving revision 1.26 diff -u -r1.25 -r1.26 --- writing_tests.pod 2001/12/24 19:30:25 1.25 +++ writing_tests.pod 2001/12/27 04:57:44 1.26 @@ -226,15 +226,42 @@ or by setting an evironment variable C to the desired value before starting the server. -=head2 Stress Testing - Normally when I is run without specifying the tests to run, the tests will be sorted alphabetically. If tests are explicitly passed as arguments to I they will be run in a specified order. + +=head2 Stress Testing + +=head3 The Problem -There are a few options useful for stress testing. +When we try to test a stateless machine (i.e. all tests are +independent), running all tests once ensures that all tested things +properly work. However when a state machine is tested (i.e. where a +run of one test may influence another test) it's not enough to run all +the tests once to know that the tested features actually work. It's +quite possible that if the same tests are run in a different order +and/or repeated a few times, some tests may fail. This usually +happens when some tests don't restore the system under test to its +pristine state at the end of the run, which may influence other tests +which rely on the fact that they start on pristine state, when in fact +it's not true anymore. In fact it's possible that a single test may +fail when run twice or three times in a sequence. + +=head3 The Solution + +To reduce the possibility of such dependency errors, it's important to +run random testing repeated many times with many different +pseudo-random engine initialization seeds. Of course if no failures +get spotted that doesn't mean that there are no tests +inter-dependencies, unless all possible combinations were run +(exhaustive approach). Therefore it's possible that some problems may +still be seen in production, but this testing greatly minimizes such a +possibility. +The C framework provides a few options useful for stress +testing. + =over =item -times @@ -272,8 +299,9 @@ run in the random order, e.g.: a, c, c, b, a, b -In this mode the used srand() seed is printed to STDOUT, so it then -can be used to rerun the tests in exactly the same order. +In this mode the seed picked by srand() is printed to C, so it +then can be used to rerun the tests in exactly the same order +(remember to log the output). =item * -order=SEED @@ -288,15 +316,159 @@ % t/TEST -order=234559 -times=5 Alternatively, the environment variable C can be set -to the value of seed. +to the value of a seed when I<-order=random> is used. e.g. under +bash(1): + + % APACHE_TEST_SEED=234559 t/TEST -order=random -times=5 + +or with any shell program if you have the C utility: + + $ env APACHE_TEST_SEED=234559 t/TEST -order=random -times=5 + +=back + +=back + +=head2 Resolving Sequence Problems + +When this kind of testing is used and a failure is detected there are +two problems: + +=over + +=item 1 + +First is to be able to reproduce the problem so if we think we fixed +it, we could verify the fix. This one is easy, just remember the +sequence of tests run till the failed test and rerun the same sequence +once again after the problem has been fixed. + +=item 2 + +Second is to be able to understand the cause of the problem. If during +the random test the failure has happened after running 400 tests, how +can we possibly know which previously running tests has caused to the +failure of the test 401. Chances are that most of the tests were clean +and don't have inter-dependency problem. Therefore it'd be very +helpful if we could reduce the long sequence to a minimum. Preferably +1 or 2 tests. That's when we can try to understand the cause of the +detected problem. + +=back + +=head2 Apache::TestSmoke Solution + +C attempts to solve both problems. When it's run, +at the end of each iteration it reports the minimal sequence of tests +causing a failure. This doesn't always succeed, but works in many +cases. + +You should create a small script to drive C, +usually I. If you don't have it already, create it: + + t/SMOKE.PL + -- + #!perl + + use strict; + use warnings FATAL => 'all'; + + use FindBin; + use li
cvs commit: modperl-docs/src/docs/2.0/devel/writing_tests writing_tests.pod
stas01/12/26 21:08:42 Modified:src/docs/2.0/devel/writing_tests writing_tests.pod Log: - document special configuration files Revision ChangesPath 1.27 +30 -5 modperl-docs/src/docs/2.0/devel/writing_tests/writing_tests.pod Index: writing_tests.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/devel/writing_tests/writing_tests.pod,v retrieving revision 1.26 retrieving revision 1.27 diff -u -r1.26 -r1.27 --- writing_tests.pod 2001/12/27 04:57:44 1.26 +++ writing_tests.pod 2001/12/27 05:08:42 1.27 @@ -1768,11 +1768,6 @@ plan(), ok() and other functions() will work correctly more than one test is running under the same interpreter. - - - - - =head2 Auto Configuration If the test is comprised only from the request part, you have to @@ -1920,6 +1915,36 @@ The valid tokens are defined in C<%Apache::TestConfig::Usage> and also can be seen in the output of C's I section. The tokens are case insensitive. + +=head2 Special Configuration Files + +Some of the files in the I directory have a special meaning, +since the C framework uses them for the minimal +configuration setup. But they can be overriden: + +=over + +=item * + +if the file I exists, it will be used instead of +the default template (in I). + +=item * + +if the file I exists, it will be used to +generate I with C<@variable@> substitutions. + +=item * + +if the file I exists, it will be included by +I. + +=item * + +if the file I exists, it will be included by +I as a mod_perl file (PerlRequire) + +=back =head2 Threaded versus Non-threaded Perl Test's Compatibility - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/devel/writing_tests writing_tests.pod
stas01/12/26 23:04:35 Modified:src/docs/2.0/devel/writing_tests writing_tests.pod Log: - port README to extensively document Request Generation and Response Options, + runtime confguration options Revision ChangesPath 1.28 +213 -14 modperl-docs/src/docs/2.0/devel/writing_tests/writing_tests.pod Index: writing_tests.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/devel/writing_tests/writing_tests.pod,v retrieving revision 1.27 retrieving revision 1.28 diff -u -r1.27 -r1.28 --- writing_tests.pod 2001/12/27 05:08:42 1.27 +++ writing_tests.pod 2001/12/27 07:04:35 1.28 @@ -57,8 +57,8 @@ it. It's important to know that there is a special verbose mode, enabled -with the I<-v> option, in which everything printed by the test goes to -C. So for example if your test does this: +with the I<-verbose> option, in which everything printed by the test +goes to C. So for example if your test does this: print "# testing : feature foo\n"; print "# expected: $expected\n"; @@ -66,7 +66,7 @@ ok $expected eq $received; in the normal mode, you won't see any of these prints. But if you run -the test with I, you will see something like this: +the test with I, you will see something like this: # testing : feature foo # expected: 2 @@ -133,11 +133,11 @@ In case something goes wrong you should run the tests in the verbose mode: - % t/TEST -v + % t/TEST -verbose In this case the test may print useful information, like what values it expects and what values it receives, given that the test is written -to report these. In the silent mode (without C<-v>) these printouts +to report these. In the silent mode (without C<-verbose>) these printouts are suppressed by the test suite. When debugging problems it helps to keep the I file open in @@ -196,10 +196,10 @@ When you run specific tests you may want to run them in the verbose mode, and depending on how the test was written, you may get more -debug information under this mode. This mode is turned on with I<-v> +debug information under this mode. This mode is turned on with I<-verbose> option: - % t/TEST -run -v protocol/echo + % t/TEST -run -verbose protocol/echo You can run all the tests in a single directory by just passing this directory as an argument. You can pass more than one test or directory @@ -465,10 +465,185 @@ Finally, any other options passed will be forwarded to C as is. -=head2 Advanced Testing +=head2 RunTime Configuration Overriding +After the server is configured during C or with C, it's possible to explicitly override certain configuration +parameters. The override-able parameters are listed when executing: + % t/TEST -help +Probably the most useful parameters are: + +=over + +=item * -preamble + +configuration directives to add at the beginning of I. +For example to turn the tracing on: + + % t/TEST -preamble "PerlTrace all" + +=item * -postamble + +configuration directives to add at the end of I. For +example to load a certain Perl module: + + % t/TEST -postamble "PerlModule MyDebugMode" + +=item * -user + +run as user I: + + % t/TEST -user nobody + +=item * -port + +run on a different port: + + % t/TEST -port 8799 + +=item * -servername + +run on a different server: + + % t/TEST -servername test.example.com + +=item * -httpd + +configure an httpd other than the default (that apxs figures out): + + % t/TEST -httpd ~/httpd-2.0/httpd + +=item * -apxs + +switch to another apxs: + + % t/TEST -apxs ~/httpd-2.0-prefork/bin/apxs + +=back + +For a complete list of override-able configuration parameters see the +output of C. + +=head2 Request Generation and Response Options + +We have mentioned already the most useful run-time options. Here are +some other options that you may find useful during testing. + +=over + +=item * -ping + +Ping the server to see whether it runs + + % t/TEST -ping + +Ping the server and wait until the server starts, report waiting time. + + % t/TEST -ping=block + +This can be useful in conjunction with I<-run> option during debugging: + + % t/TEST -ping=block -run + +normally, I<-run> will immediately quit if it detects that the server +is not running, but with I<-ping=block> in effect, it'll wait +indefinitely for the server to start up. + +=item * -head + +Issue a C request. For example to request I: + + % t/TEST -head /server-info + +=item * -get + +Request the body of a certain URL via C. + + % t/TEST -get /server-info + +If
cvs commit: modperl-docs/admin style.pod
stas01/12/26 23:32:42 Modified:adminstyle.pod Log: - minor adjustments Revision ChangesPath 1.3 +12 -12modperl-docs/admin/style.pod Index: style.pod === RCS file: /home/cvs/modperl-docs/admin/style.pod,v retrieving revision 1.2 retrieving revision 1.3 diff -u -r1.2 -r1.3 --- style.pod 2001/12/25 05:23:41 1.2 +++ style.pod 2001/12/27 07:32:42 1.3 @@ -196,7 +196,7 @@ So what we have to do (and I haven't made it yet) is to use a convention for the code to be automatically extracted, e.g.: - file:/example.pl + file:example.pl #!/usr/bin/perl -w @@ -205,17 +205,17 @@ print "Hi"; -So as I've said before we must not forget to add indentation to empty -lines with no code in them, so that the parser picks up the whole -code, removes the header with the filename and separator, puts back -the code itself, saves it to the filename written at the top, and -places it into the same directory name the text is located in. (Well -it can be a separate tree for the code). If there are real empty -lines, only part of the script will be saved, which will make the -release broken. Another approach is to add some tail (ending token), -but it's a mess I think. I develop the text using I in -xemacs which shows all spaces not followed by any text - this helps a -lot!!! +So as I've said before we must not forget to add 2 space characters +indentation to empty lines with no code in them, so that the parser +picks up the whole code, removes the header with the filename and +separator, puts back the code itself, saves it to the filename written +at the top, and places it into the same directory name the text is +located in. (Well it can be a separate tree for the code). If there +are real empty lines, only part of the script will be saved, which +will make the release broken. Another approach is to add some tail +(ending token), but it's a mess I think. I develop the text using +I in xemacs which shows all space characters not +followed by any text - this helps a lot! =back - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/devel/writing_tests writing_tests.pod
stas01/12/26 23:33:03 Modified:src/docs/2.0/devel/writing_tests writing_tests.pod Log: - cleanups and re-shuffles Revision ChangesPath 1.29 +123 -123 modperl-docs/src/docs/2.0/devel/writing_tests/writing_tests.pod Index: writing_tests.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/devel/writing_tests/writing_tests.pod,v retrieving revision 1.28 retrieving revision 1.29 diff -u -r1.28 -r1.29 --- writing_tests.pod 2001/12/27 07:04:35 1.28 +++ writing_tests.pod 2001/12/27 07:33:03 1.29 @@ -99,7 +99,7 @@ If you install mod_perl 2.x, you get C installed as well. -=head1 How to Run Tests +=head1 Running Tests It's much easier to copy-cat things, than creating from scratch. It's much easier to develop tests, when you have some existing system that @@ -329,7 +329,7 @@ =back -=head2 Resolving Sequence Problems +=head3 Resolving Sequence Problems When this kind of testing is used and a failure is detected there are two problems: @@ -356,7 +356,7 @@ =back -=head2 Apache::TestSmoke Solution +=head3 Apache::TestSmoke Solution C attempts to solve both problems. When it's run, at the end of each iteration it reports the minimal sequence of tests @@ -366,8 +366,8 @@ You should create a small script to drive C, usually I. If you don't have it already, create it: - t/SMOKE.PL - -- + file:t/SMOKE.PL + --- #!perl use strict; @@ -640,21 +640,17 @@ during the interactive run, set the C environment variable. +=head1 Setting Up Testing Environment - - - -META: a lot more stuff to go here from the pods/modperl_dev.pod and -Apache-Test/README - -=head1 How to Setup Testing Environment - We will assume that you setup your testing environment even before you -have started developing the module, which is a very smart thing to do. +have started coding the project, which is a very smart thing to do. Of course it'll take you more time upfront, but it'll will save you a -lot of time as you develop and debug your code. The L says -that tests should be written before starting the code development. +lot of time during the project developing and debugging stages. The +L says that tests +should be written before starting the code development. + +=head2 Basic Testing Environment So the first thing is to create a package and all the helper files, so later on we can distribute it on CPAN. We are going to develop an @@ -872,7 +868,7 @@ "basic test", ); -Now create the README file. +Now create the I file. % touch README @@ -890,13 +886,13 @@ ... ); -in this case C will be created from the documenation POD +in this case I will be created from the documenation POD sections in I, but the file has to exists for I to succeed. -and finally we adjust or create the C file, so we can +and finally we adjust or create the I file, so we can prepare a complete distribution. Therefore we list all the files that -should enter the distribution including the C file itself: +should enter the distribution including the I file itself: file:MANIFEST - @@ -938,6 +934,95 @@ how amazingly it works and how amazingly it can be deployed by other users. + +=head2 Extending Configuration Setup + +Sometimes you need to add extra I configuration and perl +startup specific to your project that uses C. This can +be accomplished by creating the desired files with an extension I<.in> +in the I directory and running: + + panic% t/TEST -config + +which for each file with the extension I<.in> will create a new file, +without this extension, convert any template placeholders into real +values and link it from the main I. The latter happens +only if the file have the following extensions: + +=over + +=item * .conf.in + +will add to I: + + Include foo.conf + +=item * .pl.in + +will add to I: + + PerlRequire foo.pl + +=item * other + +other files with I<.in> extension will be processed as well, but not +linked from I. + +=back + +As mentioned before the converted files are created, any special token +in them are getting replaced with the appropriate values. For example +the token C<@ServerRoot@> will be replaced with the value defined by +the C directive, so you can write a file that does the +following: + + file:my-extra.conf.in + - + PerlSwitches [EMAIL PROTECTED]@/../lib + +and assuming that the I is I<~/modperl-2.0/t/>, when +I will be created, it'll look like: + + file:my-extra.conf.i
cvs commit: modperl-docs/src/docs/2.0/devel/perf_sizeof - New directory
stas01/12/27 00:16:56 modperl-docs/src/docs/2.0/devel/perf_sizeof - New directory - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/devel/perf_sizeof perf_sizeof.pod
stas01/12/27 00:17:41
Added: src/docs/2.0/devel/perf_sizeof perf_sizeof.pod
Log:
- moved from pod/modperl_sizeof.pod
Revision ChangesPath
1.1
modperl-docs/src/docs/2.0/devel/perf_sizeof/perf_sizeof.pod
Index: perf_sizeof.pod
===
=head1 NAME
Measure C of Perl's C Structures
=head1 DESCRIPTION
This document describes the I various structures, as
determined by I. These measurements are mainly for
research purposes into making Perl things smaller, or rather, how to
use less Perl things.
=head1 Perl Structures
Structures diagrams are courtesy gdb (print pretty) and a bit of hand
crafting.
=over 4
=item CV - 229 minimum, 254 minimum w/ symbol table entry
cv = {
sv_any = {// XPVCV *
xpv_pv = 0x0, // char *
xpv_cur = 0, // STRLEN
xpv_len = 0, // STRLEN
xof_off = 0 , // IV
xnv_nv = 0, // NV
xmg_magic = 0x0, // MAGIC *
xmg_stash = 0x0, // HV *
xcv_stash = 0x0, // HV *
xcv_start = 0x0, // OP *
xcv_root = 0x0, // OP *
xcv_xsub = 0x0, // void (*)(register PerlInterpreter *, CV *)
xcv_xsubany = { // ANY
any_ptr = 0x0,
any_i32 = 0,
any_iv = 0,
any_long = 0,
any_dptr = 0,
any_dxptr = 0
},
xcv_gv = { // GV *
sv_any = { // void *
xpv_pv = 0x0, // char *
xpv_cur = 0, // STRLEN
xpv_len = 0, // STRLEN
xiv_iv = 0, // IV
xnv_nv = 0, // NV
xmg_magic = { // MAGIC *
mg_moremagic = 0x0, // MAGIC *
mg_virtual = 0x0, // MGVTBL *
mg_private = 0, // U16
mg_type = 0,// char
mg_flags = 0, // U8
mg_obj = 0x0, // SV *
mg_ptr = 0x0, // char *
mg_len = 0, // I32
},
xmg_stash = 0x0, // HV *
xgv_gp = { // GP *
gp_sv = { // SV *
sv_any = 0x0, // void *
sv_refcnt = 0, // U32
sv_flags = 0 // U32
},
gp_refcnt = 0, // U32
gp_io = 0x0, // struct io *
gp_form = 0x0, // CV *
gp_av = 0x0, // AV *
gp_hv = 0x0, // HV *
gp_egv = 0x0, // GV *
gp_cv = 0x0, // CV *
gp_cvgen = 0, // U32
gp_flags = 0, // U32
gp_line = 0, // line_t
gp_file = 0x0, // char *
},
xgv_name = 0x0, // char *
xgv_namelen = 0, // STRLEN
xgv_stash = 0x0, // void *
xgv_flags = 0, // U8
},
sv_refcnt = 0, // U32
sv_flags = 0, // U32
},
xcv_file = 0x0, // char *
xcv_depth = 0, // long
xcv_padlist = 0x0, // AV *
xcv_outside = 0x0, // CV *
xcv_flags = 0, // cv_flags_t
}
sv_refcnt = 0, // U32
sv_flags = 0, // U32
};
In addition to the minimum bytes:
=over 4
=item name of the subroutine: GvNAMELEN(CvGV(cv))+1
=item symbol table entry: HvENTRY (25 + GvNAMELEN(CvGV(cv))+1)
=item minimum sizeof(AV) * 3: xcv_padlist if !CvXSUB(cv)
=item CvROOT(cv) optree
=back
=item HV - 60 minmum
hv = {
sv_any = { // SV *
xhv_array = 0x0, // char *
xhv_fill = 0, // STRLEN
xhv_max = 0, // STRLEN
xhv_keys = 0, // IV
xnv_nv = 0, // NV
xmg_magic = 0x0, // MAGIC *
xmg_stash = 0x0, // HV *
xhv_riter = 0,// I32
xhv_eiter = 0x0, // HE *
xhv_pmroot = 0x0, // PMOP *
xhv_name = 0x0// char *
},
sv_refcnt = 0, // U32
sv_flags = 0, // U32
};
Each entry adds sizeof(HvENTRY), minimum of 7 (initial xhv_max).
Note that keys of the same value share sizeof(HEK), across all hashes.
=item HvENTRY - 25 + HeKLEN+1
sizeof(HE *) + sizeof(HE) + sizeof(HEK)
=item HE - 12
he = {
hent_next = 0x0, // HE *
hent_hek = 0x0, // HEK *
hent_val = 0x0 // SV *
};
=item HEK - 9 + hek_len
hek = {
hek_hash = 0, // U32
hek_len = 0, // I32
hek_key = 0, // char
};
=item AV - 53
av = {
sv_any = { // SV *
xav_array = 0x0, //
cvs commit: modperl-docs/src/docs/2.0/devel/perf_sizeof perf_sizeof.pod
stas01/12/27 00:22:25
Modified:src/docs/2.0/devel/perf_sizeof perf_sizeof.pod
Log:
- adjust indentation
Revision ChangesPath
1.2 +122 -121
modperl-docs/src/docs/2.0/devel/perf_sizeof/perf_sizeof.pod
Index: perf_sizeof.pod
===
RCS file:
/home/cvs/modperl-docs/src/docs/2.0/devel/perf_sizeof/perf_sizeof.pod,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- perf_sizeof.pod 2001/12/27 08:17:41 1.1
+++ perf_sizeof.pod 2001/12/27 08:22:25 1.2
@@ -17,80 +17,80 @@
=item CV - 229 minimum, 254 minimum w/ symbol table entry
- cv = {
-sv_any = {// XPVCV *
-xpv_pv = 0x0, // char *
-xpv_cur = 0, // STRLEN
-xpv_len = 0, // STRLEN
-xof_off = 0 , // IV
-xnv_nv = 0, // NV
-xmg_magic = 0x0, // MAGIC *
-xmg_stash = 0x0, // HV *
-xcv_stash = 0x0, // HV *
-xcv_start = 0x0, // OP *
-xcv_root = 0x0, // OP *
-xcv_xsub = 0x0, // void (*)(register PerlInterpreter *, CV *)
-xcv_xsubany = { // ANY
-any_ptr = 0x0,
-any_i32 = 0,
-any_iv = 0,
-any_long = 0,
-any_dptr = 0,
-any_dxptr = 0
-},
-xcv_gv = { // GV *
-sv_any = { // void *
-xpv_pv = 0x0, // char *
-xpv_cur = 0, // STRLEN
-xpv_len = 0, // STRLEN
-xiv_iv = 0, // IV
-xnv_nv = 0, // NV
-xmg_magic = { // MAGIC *
-mg_moremagic = 0x0, // MAGIC *
-mg_virtual = 0x0, // MGVTBL *
-mg_private = 0, // U16
-mg_type = 0,// char
-mg_flags = 0, // U8
-mg_obj = 0x0, // SV *
-mg_ptr = 0x0, // char *
-mg_len = 0, // I32
-},
-xmg_stash = 0x0, // HV *
-xgv_gp = { // GP *
-gp_sv = { // SV *
-sv_any = 0x0, // void *
-sv_refcnt = 0, // U32
-sv_flags = 0 // U32
-},
-gp_refcnt = 0, // U32
-gp_io = 0x0, // struct io *
-gp_form = 0x0, // CV *
-gp_av = 0x0, // AV *
-gp_hv = 0x0, // HV *
-gp_egv = 0x0, // GV *
-gp_cv = 0x0, // CV *
-gp_cvgen = 0, // U32
-gp_flags = 0, // U32
-gp_line = 0, // line_t
-gp_file = 0x0, // char *
-},
-xgv_name = 0x0, // char *
-xgv_namelen = 0, // STRLEN
-xgv_stash = 0x0, // void *
-xgv_flags = 0, // U8
-},
-sv_refcnt = 0, // U32
-sv_flags = 0, // U32
-},
-xcv_file = 0x0, // char *
-xcv_depth = 0, // long
-xcv_padlist = 0x0, // AV *
-xcv_outside = 0x0, // CV *
-xcv_flags = 0, // cv_flags_t
-}
-sv_refcnt = 0, // U32
-sv_flags = 0, // U32
- };
+ cv = {
+ sv_any = {// XPVCV *
+ xpv_pv = 0x0, // char *
+ xpv_cur = 0, // STRLEN
+ xpv_len = 0, // STRLEN
+ xof_off = 0 , // IV
+ xnv_nv = 0, // NV
+ xmg_magic = 0x0, // MAGIC *
+ xmg_stash = 0x0, // HV *
+ xcv_stash = 0x0, // HV *
+ xcv_start = 0x0, // OP *
+ xcv_root = 0x0, // OP *
+ xcv_xsub = 0x0, // void (*)(register PerlInterpreter *, CV *)
+ xcv_xsubany = { // ANY
+ any_ptr = 0x0,
+ any_i32 = 0,
+ any_iv = 0,
+ any_long = 0,
+ any_dptr = 0,
+ any_dxptr = 0
+ },
+ xcv_gv = { // GV *
+ sv_any = { // void *
+ xpv_pv = 0x0, // char *
+ xpv_cur = 0, // STRLEN
+ xpv_len = 0, // STRLEN
+ xiv_iv = 0, // IV
+ xnv_nv = 0, // NV
+ xmg_magic = { // MAGIC *
+ mg_moremagic = 0x0, // MAGIC *
+ mg_virtual = 0x0, // MGVTBL *
+ mg_private = 0, // U16
+ mg_type = 0,// char
+ mg_flags = 0, // U8
+ mg_obj = 0x0, // SV *
+ mg_ptr = 0x0, // char *
+ mg_len = 0, // I32
cvs commit: modperl-docs/src/docs/2.0/devel/help - New directory
stas01/12/27 01:21:47 modperl-docs/src/docs/2.0/devel/help - New directory - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/devel/help help.pod
stas01/12/27 01:22:19 Added: src/docs/2.0/devel/help help.pod Log: - starting the developers help doc Revision ChangesPath 1.1 modperl-docs/src/docs/2.0/devel/help/help.pod Index: help.pod === =head1 NAME Getting Help with mod_perl 2.0 Core Development =head1 Introduction This document covers the resources available to the mod_perl 2.0 core developer. Please notice that you probably want to read the L if you have problems using mod_perl. The following mailing lists and resources can be of a major interest to the mod_perl 2.0 developers. =head1 mod_perl =head2 mod_perl 2.0 Core Development Discussion List This list is used by the mod_perl 2.0 core developers to discuss design issues, solve problems and send patches and exchange ideas. =over =item * mailing list subscription: mailto:[EMAIL PROTECTED] =item * archive: http://marc.theaimsgroup.com/?l=apache-modperl-dev&r=1&w=2#apache-modperl-dev =back When reporting problems, be sure to include the output of: % perl build/config.pl which generates the output from: =over 4 =item perl -V =item httpd -V =item Makefile.PL options =back You can also use I. If you get segmentation faults please send the stack backtrace to the modperl developers list. META: link to the place explaining how to get it =head2 mod_perl 2.0 Core Development CVS Commits List This list's traffic is comprised of solely cvs commits, so this is the place to be if you want to see mod_perl 2.0 evolve before your eyes. =over =item * mailing list subscription: mailto:[EMAIL PROTECTED] =item * archive: http://marc.theaimsgroup.com/?l=apache-modperl-cvs&r=1&w=2#apache-modperl-cvs =back =head2 Apache-Test The C project, originally developed as a part of mod_perl 2.0, is now a part of the Apache C project. You get this repository automatically when checking out the mod_perl-2.0 cvs repository. To retrieve the whole httpd-test project, run: cvs co httpd-test =over =item discussion/problems report: mailing list subscription: mailto:[EMAIL PROTECTED] archive: META: ??? =item cvs commits mailing list subscription: mailto:[EMAIL PROTECTED] archive: META: ??? =back =head1 Apache =head2 httpd 2.0 =over =item discussion/problems report: mailing list subscription: mailto:[EMAIL PROTECTED] archive: http://marc.theaimsgroup.com/?l=apache-new-httpd&r=1&w= =item cvs commits mailing list subscription: mailto:[EMAIL PROTECTED] archive: http://marc.theaimsgroup.com/?l=apache-cvs&r=1&w=2 =back =head2 Apache Portable Runtime (APR) The Apache Portable Run-time libraries have been designed to provide a common interface to low level routines across any platform. mod_perl comes with a partial Perl APR API. =over =item discussion/problems report: mailing list subscription: mailto:[EMAIL PROTECTED] archive: http://marc.theaimsgroup.com/?l=apr-dev&r=1&w=2 =item cvs commits mailing list subscription: mailto:[EMAIL PROTECTED] archive: http://marc.theaimsgroup.com/?l=apr-cvs&r=1&w=2 =back =head2 Perl 5 Currently mod_perl 2.0 requires perl 5.6.1 and higher. If you think you have found a bug in perl 5 report it to the perl5-porters mailing list. Otherwise please choose the appropriate list from the extensive perl related lists: http://lists.perl.org/. =over =item discussion/problems reports: mailing list subscription: mailto:[EMAIL PROTECTED] archive: http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/ and http://archive.develooper.com/perl5-porters@perl.org/ news gateway: news://news.perl.com/perl.porters-gw/ =item perforce Perl uses C for its source revision control, see I manpage coming with Perl for more information. the perforce repository: http://public.activestate.com/gsar/APC/ or ftp://ftp.linux.activestate.com/pub/staff/gsar/APC/ the Perl Repository Browser: http://public.activestate.com/cgi-bin/perlbrowse the Perl cross-reference: http://pxr.perl.org/source/ mailing list subscription: [EMAIL PROTECTED] archive: http://archive.develooper.com/perl5-changes@perl.org/ =back =head1 More Help There is a L in the user documentation set which covers mod_perl user's issues. =head1 Maintainers Maintainer is the person(s) you should contact with updates, corrections and patches. Stas Bekman Estas (at) stason.orgE =head1 Authors =over =item * Stas Bekman Estas (at) stason.orgE =item * =back =cut --
cvs commit: modperl-docs/src/docs/2.0/devel/writing_tests writing_tests.pod
stas01/12/27 03:11:13 Modified:src/docs/2.0/devel/writing_tests writing_tests.pod Log: - completing the porting of 'make test' docs from modperl_dev.pod Revision ChangesPath 1.30 +170 -89 modperl-docs/src/docs/2.0/devel/writing_tests/writing_tests.pod Index: writing_tests.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/devel/writing_tests/writing_tests.pod,v retrieving revision 1.29 retrieving revision 1.30 diff -u -r1.29 -r1.30 --- writing_tests.pod 2001/12/27 07:33:03 1.29 +++ writing_tests.pod 2001/12/27 11:11:13 1.30 @@ -56,10 +56,13 @@ proceed with the tests and it's not a must pass test, you just skip it. -It's important to know that there is a special verbose mode, enabled -with the I<-verbose> option, in which everything printed by the test -goes to C. So for example if your test does this: +=head2 Verbose Testing +By default print() statements in the test script are filtered out by +C. if you want the test to print what it does (if you +decide to debug some test) use C<-verbose> option. So for example if +your test does this: + print "# testing : feature foo\n"; print "# expected: $expected\n"; print "# received: $received\n"; @@ -80,8 +83,8 @@ mode and send you back the report. It'll be much easier to understand what the problem is if you get these debug printings from the user. -In the section L<"How to Write Tests"> we discuss a few helper -functions which make the tests writing easier. +In the section L<"Writing Tests"> several helper functions which make +the tests writing easier are discussed. For more details about the C module please refer to its manpage. Also see the C manpage about Perl's test suite. @@ -111,10 +114,19 @@ testing environments which both use C for their test suites. +=head2 Testing Options + +Run: + + % t/TEST -help + +to get the list of options you can use during testing. They are +covered in the rest of this document. + =head2 Basic Testing -Running tests is just like for any CPAN Perl module; first we create -the I and build everything with I: +Running tests is just like for any CPAN Perl module; first we generate +the I file and build everything with I: % perl Makefile.PL [options] % make @@ -125,44 +137,64 @@ % make test but it adds quite an overhead, since it has to check that everything -is up to date (the usual C source change control). Therefore -faster to run the tests directly via: +is up to date (the usual C source change control). Therefore you +have to run it only once after C and for re-running the tests +it's faster to run the tests directly via: % t/TEST -In case something goes wrong you should run the tests in the verbose -mode: +When C or C are run, all tests found in the I +directory (files ending with I<.t> are recognized as tests) will be +run. - % t/TEST -verbose +=head2 Individual Testing -In this case the test may print useful information, like what values -it expects and what values it receives, given that the test is written -to report these. In the silent mode (without C<-verbose>) these printouts -are suppressed by the test suite. +To run a single test, simple specify it at the command line. For +example to run the test file I, execute: -When debugging problems it helps to keep the I file open in -another console, and see the debug output in the real time via -tail(1): + % t/TEST protocol/echo - % tail -f t/logs/error_log +Notice that you don't have to add the I prefix and I<.t> extension +for the test filenames if you specify them explicitly, but you can +have these as well. Therefore the following are all valid commands: -Of course this file gets created only when the server starts, so you -cannot run tail(1) on it before the server starts. + % t/TEST protocol/echo.t + % t/TEST t/protocol/echo + % t/TEST t/protocol/echo.t + +The server will be stopped if it was already running and a new one +will be started before running the I test. At the +end of the test the server will be shut down. + +When you run specific tests you may want to run them in the verbose +mode, and depending on how the test was written, you may get more +debug information under this mode. This mode is turned on with +I<-verbose> option: + + % t/TEST -verbose protocol/echo + +You can run groups of tests at once. This command: + + % ./t/TEST modules protocol/echo + +will run all the tests in I directory, followed by +I test. -[F] Later on we will talk about I<-clean> option, for now just -remember th
cvs commit: modperl-docs/src/docs/2.0/devel/testing - New directory
stas01/12/27 03:13:50 modperl-docs/src/docs/2.0/devel/testing - New directory - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/devel/testing testing.pod
stas01/12/27 03:15:04 Added: src/docs/2.0/devel/testing testing.pod Removed: src/docs/2.0/devel/writing_tests writing_tests.pod Log: moving writing_tests to testing, since now the doc is covering more than just writing tests. Revision ChangesPath 1.1 modperl-docs/src/docs/2.0/devel/testing/testing.pod Index: testing.pod === =head1 NAME Running and Developing Tests with the C Framework =head1 Introduction This chapter is talking about the C framework, and in particular explains how to: =over =item 1 run existing tests =item 2 setup a testing environment for a new project =item 3 develop new tests =back But first let's introduce the C framework. The C framework is designed for easy writing of tests that has to be run under Apache webserver (not necessarily mod_perl). Originally designed for the mod_perl Apache module, it was extended to be used for any Apache module. The tests themselves are written in Perl, and the framework will provide an extensive functionality which makes the tests writing a simple and therefore enjoyable process. If you have ever written or looked at the tests most Perl modules come with, C uses the same concept. The script I is running all the files ending with I<.t> it finds in the I directory. When executed a typical test prints the following: 1..3 # going to run 3 tests ok 1 # the first test has passed ok 2 # the second test has passed not ok 3 # the third test has failed Every C or C is followed by the number which tells which sub-test has succeeded or failed. I uses the C module which intercepts the C stream, parses it and at the end of the tests print the results of the tests running: how many tests and sub-tests were run, how many succeeded, skipped or failed. Some tests may be skipped by printing: 1..0 # all tests in this file are going to be skipped. Usually a test may be skipped when some feature is optional and/or prerequisites are not installed on the system, but this is not critical for the usefulness of the test. Once you test that you cannot proceed with the tests and it's not a must pass test, you just skip it. =head2 Verbose Testing By default print() statements in the test script are filtered out by C. if you want the test to print what it does (if you decide to debug some test) use C<-verbose> option. So for example if your test does this: print "# testing : feature foo\n"; print "# expected: $expected\n"; print "# received: $received\n"; ok $expected eq $received; in the normal mode, you won't see any of these prints. But if you run the test with I, you will see something like this: # testing : feature foo # expected: 2 # received: 2 ok 2 When you develop the test you should always put the debug statements there, and once the test works for you do not comment out or delete these debug statements. This is because if some user reports a failure in some test, you can ask him to run the failing test in the verbose mode and send you back the report. It'll be much easier to understand what the problem is if you get these debug printings from the user. In the section L<"Writing Tests"> several helper functions which make the tests writing easier are discussed. For more details about the C module please refer to its manpage. Also see the C manpage about Perl's test suite. =head1 Prerequisites In order to use C it has to be installed first. Install C using the familiar procedure: % cd Apache-Test % perl Makefile.PL % make && make test && make install If you install mod_perl 2.x, you get C installed as well. =head1 Running Tests It's much easier to copy-cat things, than creating from scratch. It's much easier to develop tests, when you have some existing system that you can test, see how it works and build your own testing environment in a similar fashion. Therefore let's first look at how the existing test enviroments work. You can look at the modperl-2.0's or httpd-test's (I) testing environments which both use C for their test suites. =head2 Testing Options Run: % t/TEST -help to get the list of options you can use during testing. They are covered in the rest of this document. =head2 Basic Testing Running tests is just like for any CPAN Perl module; first we generate the I file and build everything with I: % perl Makefile.PL [options] % make Now we can do the testing. You can run the tests in two ways. The first one is usual: % make test but it adds
cvs commit: modperl-docs/src/docs/2.0/devel/help help.pod
stas01/12/27 03:30:45 Modified:src/docs/2.0/devel/help help.pod Log: more useful URLs and help info Revision ChangesPath 1.2 +27 -0 modperl-docs/src/docs/2.0/devel/help/help.pod Index: help.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/devel/help/help.pod,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- help.pod 2001/12/27 09:22:19 1.1 +++ help.pod 2001/12/27 11:30:45 1.2 @@ -14,6 +14,17 @@ =head1 mod_perl +=head2 Submitting Patches + +If you submit patches the I manpage can be very +useful. You can find it I or similar +or read it online at +http://sunsite.ualberta.ca/Documentation/Misc/perl-5.6.1/Porting/patching.html. + +Note that we prefer the patches inlined into an email. This makes +easier to comment on them. If your email client mangles the spacing +and wraps lines, then send them as MIME attachments. + =head2 mod_perl 2.0 Core Development Discussion List This list is used by the mod_perl 2.0 core developers to discuss @@ -119,6 +130,22 @@ archive: http://marc.theaimsgroup.com/?l=apache-cvs&r=1&w=2 =back + +=over + +=item * + +Apache source code cross-reference (LXR): +http://lxr.webperf.org/ + +=item * + +Apache source code through Doxygen documentation system: + +http://docx.webperf.org/ + + +=item * =head2 Apache Portable Runtime (APR) - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/user/compat compat.pod
stas01/12/27 03:35:22 Modified:src/docs/2.0/user/compat compat.pod Log: how to run the 1.x registry (ported from modperl_dev.pod) Revision ChangesPath 1.5 +19 -0 modperl-docs/src/docs/2.0/user/compat/compat.pod Index: compat.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/compat/compat.pod,v retrieving revision 1.4 retrieving revision 1.5 diff -u -r1.4 -r1.5 --- compat.pod2001/12/21 15:24:35 1.4 +++ compat.pod2001/12/27 11:35:22 1.5 @@ -98,6 +98,25 @@ C and C now live in the C namespace to avoid collisions with the versions from 1.x. +To run the 1.x C you have to load C: + + file:startup.pl: + + use Apache::compat (); + use lib ...; #or something to find 1.xx Apache::Registry + +then in I: + + Alias /perl /path/to/perl/scripts + + Options +ExecCGI + SetHandler modperl + PerlResponseHandler Apache::Registry + + +Notice that C has to be loaded before C if the +latter module is used. + META: complete - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/devel/debug_c - New directory
stas01/12/27 03:40:37 modperl-docs/src/docs/2.0/devel/debug_c - New directory - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/devel/debug_perl - New directory
stas01/12/27 03:40:37 modperl-docs/src/docs/2.0/devel/debug_perl - New directory - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/devel/debug_perl debug_perl.pod
stas01/12/27 03:41:58
Added: src/docs/2.0/devel/debug_c debug_c.pod
src/docs/2.0/devel/debug_perl debug_perl.pod
Log:
- porting c debug parts from the guide
- porting gdb debug notes from modperl_dev.pod
- starting an empty perl debug doc
Revision ChangesPath
1.1 modperl-docs/src/docs/2.0/devel/debug_c/debug_c.pod
Index: debug_c.pod
===
=head1 NAME
Debugging mod_perl C Internals
=head1 Debug notes
META: needs more organization
=head2 Setting gdb breakpoints with mod_perl built as DSO
If mod_perl is built as a DSO module, you cannot set the breakpoint in
the mod_perl source files when the I program gets loaded into
the debugger. The reason is simple: At this moment I has no
idea about mod_perl module yet. After the configuration file is
processed and the mod_perl DSO module is loaded then the breakpoints
in the source of mod_perl itself can be set.
The trick is to break at I, let it load
I, then you can set breakpoints anywhere in the modperl
code:
% gdb httpd
(gdb) b apr_dso_load
(gdb) run -DONE_PROCESS
[New Thread 1024 (LWP 1600)]
[Switching to Thread 1024 (LWP 1600)]
Breakpoint 1, apr_dso_load (res_handle=0xbfffb48c, path=0x811adcc
"/home/stas/apache.org/modperl-perlmodule/src/modules/perl/libmodperl.so",
pool=0x80e1a3c) at dso.c:138
141 void *os_handle = dlopen(path, RTLD_NOW | RTLD_GLOBAL);
(gdb) finish
...
Value returned is $1 = 0
(gdb) b modperl_hook_init
(gdb) continue
This example shows how to set a breakpoint at I.
To automate things you can put those in the I<.gdb-jump-to-init> file:
b apr_dso_load
run -DONE_PROCESS -d /home/stas/apache.org/modperl-perlmodule/t \
-f /home/stas/apache.org/modperl-perlmodule/t/conf/httpd.conf
finish
b modperl_hook_init
continue
and then start the debugger with:
% gdb /home/stas/httpd-2.0/bin/httpd -command \
/home/stas/apache.org/modperl-perlmodule/t/.gdb-jump-to-init
=head2 Starting the Server Fast under gdb
When the server is started under gdb, it first loads the symbol tables
of the dynamic libraries that it sees going to be used. Some versions
of gdb may take ages to complete this task, which makes the debugging
very irritating if you have to restart the server all the time and it
doesn't happen immediately.
The trick is to set the C flag to 0:
set auto-solib-add 0
in I<~/.gdbinit> file.
With this setting in effect, you can load only the needed dynamic
libraries with I command. Remember that in order to set
a breakpoint and step through the code inside a certain dynamic
library you have to load it first. For example consider this gdb
commands file:
.gdb-commands
file ~/httpd/prefork/bin/httpd
handle SIGPIPE pass
handle SIGPIPE nostop
set auto-solib-add 0
b ap_run_pre_config
run -DONE_PROCESS -d `pwd`/t -f `pwd`/t/conf/httpd.conf \
-DAPACHE2 -DPERL_USEITHREADS
sharedlibrary modperl
b modperl_hook_init
# start: modperl_hook_init
continue
# restart: ap_run_pre_config
continue
# restart: modperl_hook_init
continue
b apr_poll
continue
# load APR/PerlIO/PerlIO.so
sharedlibrary PerlIO
b PerlIOAPR_open
which can be used as:
% gdb -command=.gdb-commands
This script stops in I, so you can step through
the mod_perl startup. We had to use the I so we can
load the I library as explained earlier. Since httpd
restarts on the start, we have to I until we hit
I second time, where we can set the breakpoint at
I, the very point where httpd polls for new request and run
again I so it'll stop at I.
When gdb stops at the function I it's a time to start the
client:
% t/TEST -run
But before that if we want to debug the server response we need to set
breakpoints in the libraries we want to debug. For example if we want
to debug the function C which resides in
I we first load it and then we can set a
breakpoint in it. Notice that gdb may not be able to load a library if
it wasn't referenced by any of the code. In this case we have to
require this library at the server startup. In our example we load:
PerlModule APR::PerlIO
in I. To check which libraries' symbol tables can be
loaded in gdb, run (when the server has been started):
gdb> info sharedlibrary
which will also show which libraries were loaded already.
Also notice that you don't have to type the full path of the library
when trying to load them, even a partial name will suffice. In our
commands file example we have used C instead of
saying C.
If you want to set breakpoints and step through the code in the Perl
a
cvs commit: modperl-docs/src/docs/2.0/user/install install.pod
stas01/12/27 03:51:54 Modified:src/docs/2.0/user/config config.pod src/docs/2.0/user/install install.pod Log: config and install sections moved from pod/modperl_dev.pod into corresponding documents Revision ChangesPath 1.2 +214 -1modperl-docs/src/docs/2.0/user/config/config.pod Index: config.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/config/config.pod,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- config.pod2001/12/18 02:59:44 1.1 +++ config.pod2001/12/27 11:51:54 1.2 @@ -1,7 +1,220 @@ =head1 NAME -Server Configuration +mod_perl Server Configuration + +=head1 mod_perl configuration directives + +=head2 Installing handlers + +=over 4 + +=item PerlChildInitHandler + +=item PerlOpenLogsHandler + +=item PerlPostConfigHandler + +=item PerlPreConnectionHandler + +=item PerlProcessConnectionHandler + +=item PerlHeaderParserHandler + +=item PerlAccessHandler + +=item PerlAuthenHandler + +=item PerlAuthzHandler + +=item PerlTypeHandler + +=item PerlFixupHandler + +=item PerlOutputFilterHandler + +=item PerlResponseHandler + +=item PerlLogHandler + +=item PerlPostReadRequestHandler + +=item PerlInitHandler + +=item PerlTransHandler + +=back + +=head2 General directives + +=over 4 + +=item PerlSwitches switches + +pass switches to the Perl command line. For example, to enable +warnings: + + PerlSwitches -w + +=item PerlTrace [level] + +set the trace level. This directive is enabled when mod_perl is compiled with +the MP_TRACE option. C is either: + + all + +which sets maximum logging and debugging levels; + +a combination of one or more option letters (or option numerical +equivalents) from the following list: + + d ( 1) directive processing + f ( 2) filters + g ( 4) Perl runtime interaction + h ( 8) handlers + i ( 16) interpreter pool management + m ( 32) memory allocations + s ( 64) perl sections + t (128) benchmark-ish timings + +When C is not specified, the tracing level will be set to the +value of the MOD_PERL_TRACE environment variable. + +=back + +=head2 Threaded mode directives + +These directives are enabled only in a threaded mod_perl+Apache combo. + +=over 4 + +=item PerlInterpStart + +Number of Perl interpreters to start + +=item PerlInterpMax + +Max number of running Perl interpreters + +=item PerlInterpMaxSpare + +Max number of spare Perl interpreters + +=item PerlInterpMinSpare + +Min number of spare Perl interpreters + +=item PerlInterpMaxRequests + +Max number of requests per Perl interpreters + +=item PerlInterpScope + +Scope for which selected interpreter should be held, one of: +I, I, I, I. + +The default is I. + +=back + +=head2 PerlOptions Directive + +Enable/Disable Options. Options include: + +=over 4 + +=item Parent + +Create a new parent Perl interpreter for the given VirtualHost and +give it its own interpreter pool (implies Clone). + +=item Clone + +Share the parent Perl interpreter, but give the VirtualHost its own +interpreter pool. + +Use: + + PerlSwitches +inherit + +to inherit base Perl interpreter's C. + +=item Enable + +On by default, used to disable mod_perl for a given VirtualHost. + +=item Perl*Handler + +Disable Perl*Handlers, all compiled in handlers are enabled by default. + +=item AutoLoad + +Resolve Perl*Handlers at startup time, includes loading the module +from disk if not already loaded. + +=item GlobalRequest + +Setup the global request_rec for use with Apache->request + +=item ParseHeaders + +Scan output for HTTP headers, same functionality as 1.x's +PerlSendHeaders, but more robust. + +=item MergeHandlers + +Turn on merging of Perl*Handler arrays, example: + + PerlFixupHandler One::fixup + + + PerlFixupHandler Another::fixup + + +By default, a request for /foo only runs B (1.x behavior) +I (inside Location /foo) will run both +B and B. + +=back + +Examples: + + # disable mod_perl for this host + + PerlOptions -Enable + + + # create 2 Parent Perls, + # each pointing to a different developer library tree + + ServerName dev1 + PerlOptions +Parent + PerlSwitches -Mblib=/home/dev1/lib/perl + + + + ServerName dev2 + PerlOptions +Parent + PerlSwitches -Mblib=/home/dev2/lib/perl + + + # give VirtualHost its own interpreter pool + + PerlOptions +Clone + PerlInterpStart 2 + PerlInterpMax 2 + + + # disable handlers + + PerlOptions -Authen -
cvs commit: modperl-docs/src/docs/2.0/user/overview - New directory
stas01/12/27 04:01:19 modperl-docs/src/docs/2.0/user/overview - New directory - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/user/design - New directory
stas01/12/27 04:01:19 modperl-docs/src/docs/2.0/user/design - New directory - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/devel/debug_perl debug_perl.pod
stas01/12/27 04:07:53 Modified:src/docs/2.0/devel/porting_from_1.x porting_from_1.x.pod src/docs/2.0/devel/debug_perl debug_perl.pod Log: - tidy up Revision ChangesPath 1.3 +6 -3 modperl-docs/src/docs/2.0/devel/porting_from_1.x/porting_from_1.x.pod Index: porting_from_1.x.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/devel/porting_from_1.x/porting_from_1.x.pod,v retrieving revision 1.2 retrieving revision 1.3 diff -u -r1.2 -r1.3 --- porting_from_1.x.pod 2001/11/12 02:44:40 1.2 +++ porting_from_1.x.pod 2001/12/27 12:07:53 1.3 @@ -95,9 +95,12 @@ =head1 Authors -Stas Bekman Estas (at) stason.orgE +=over -Doug MacEachern Edougm (at) covalent.netE +=item * Stas Bekman Estas (at) stason.orgE -=cut +=item * Doug MacEachern Edougm (at) covalent.netE + +=back +=cut 1.2 +0 -12 modperl-docs/src/docs/2.0/devel/debug_perl/debug_perl.pod Index: debug_perl.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/devel/debug_perl/debug_perl.pod,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- debug_perl.pod2001/12/27 11:41:58 1.1 +++ debug_perl.pod2001/12/27 12:07:53 1.2 @@ -11,18 +11,6 @@ =head1 Authors -Stas Bekman Estas (at) stason.orgE - -=cut -=head1 Maintainers - -Maintainer is the person(s) you should contact with updates, -corrections and patches. - -Stas Bekman Estas (at) stason.orgE - -=head1 Authors - =over =item * Stas Bekman Estas (at) stason.orgE - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/devel/help help.pod
stas01/12/31 02:33:02 Modified:src/docs/2.0/devel/help help.pod Log: s|build/bugreport.pl|t/REPORT| Revision ChangesPath 1.3 +1 -1 modperl-docs/src/docs/2.0/devel/help/help.pod Index: help.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/devel/help/help.pod,v retrieving revision 1.2 retrieving revision 1.3 diff -u -r1.2 -r1.3 --- help.pod 27 Dec 2001 11:30:45 - 1.2 +++ help.pod 31 Dec 2001 10:33:02 - 1.3 @@ -58,7 +58,7 @@ =back -You can also use I. +Please use the output generated by I utility. If you get segmentation faults please send the stack backtrace to the modperl developers list. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/devel/core_explained core_explained.pod
stas01/12/31 04:13:51
Modified:src/docs/2.0/devel/core_explained core_explained.pod
Log:
- add notes on how to import new constants and enums from ap/apr
Revision ChangesPath
1.11 +28 -0
modperl-docs/src/docs/2.0/devel/core_explained/core_explained.pod
Index: core_explained.pod
===
RCS file:
/home/cvs/modperl-docs/src/docs/2.0/devel/core_explained/core_explained.pod,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- core_explained.pod21 Dec 2001 16:54:20 - 1.10
+++ core_explained.pod31 Dec 2001 12:13:51 - 1.11
@@ -435,7 +435,35 @@
In all other cases use normal functions.
+=head1 Importing Constants and Enums into Perl API
+To I httpd and APR constants and enums into Perl API, edit
+I. To add a new type of C constants
+adjust the C<%defines_wanted> variable, for C modify
+C<%enums_wanted>.
+
+For example to import all Cs starting with C add:
+
+ my %defines_wanted = (
+ ...
+ APR => {
+ ...
+ flock => [qw{APR_FLOCK_}],
+ ...
+ },
+ );
+
+When deciding which constants are to be exported, the regular
+expression will be used, so in our example all matches
+C will be imported into the Perl API.
+
+For example to import an I C for Apache, add:
+
+ my %enums_wanted = (
+ Apache => { map { $_, 1 } qw(filter_type) },
+ );
+
+Notice that I<_e> part at the end of the enum name has gone.
=head1 Maintainers
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/devel/core_explained core_explained.pod
stas01/12/31 05:19:00
Modified:src/docs/2.0/devel/core_explained core_explained.pod
Log:
- complete the example of adding simple enum/const
Revision ChangesPath
1.12 +27 -2
modperl-docs/src/docs/2.0/devel/core_explained/core_explained.pod
Index: core_explained.pod
===
RCS file:
/home/cvs/modperl-docs/src/docs/2.0/devel/core_explained/core_explained.pod,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- core_explained.pod31 Dec 2001 12:13:51 - 1.11
+++ core_explained.pod31 Dec 2001 13:19:00 - 1.12
@@ -457,13 +457,38 @@
expression will be used, so in our example all matches
C will be imported into the Perl API.
-For example to import an I C for Apache, add:
+For example to import an I C for APR, add:
my %enums_wanted = (
- Apache => { map { $_, 1 } qw(filter_type) },
+ APR => { map { $_, 1 } qw(apr_read_type) },
);
Notice that I<_e> part at the end of the enum name has gone.
+
+After adding/modifying the datastructures make sure to run C or C and verify that the
+wanted constant or enum were picked by the source scanning
+process. Simply grep I for the wanted string. For
+example after adding I enum we can check:
+
+ % more xs/tables/current/Apache/ConstantsTable.pm
+ ...
+'read_type' => [
+ 'APR_BLOCK_READ',
+ 'APR_NONBLOCK_READ'
+],
+
+Of course the newly added constant or enum's typemap should be
+declared in the appropriate I files, so the XS
+conversion of arguments will be performed correctly. For example
+I is an APR enum so it's declared in
+I:
+
+ apr_read_type | IV
+
+C is used as a typemap, lSince enum is simply an integer. In more
+complex cases the typemap can be different. (META: examples)
+
=head1 Maintainers
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/devel/core_explained core_explained.pod
stas01/12/03 22:37:14 Modified:src/devel/core_explained core_explained.pod Log: explain what's in src/modules/perl + how to add new .c/.h files there Revision ChangesPath 1.9 +15 -0 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.8 retrieving revision 1.9 diff -u -r1.8 -r1.9 --- core_explained.pod2001/11/29 16:26:32 1.8 +++ core_explained.pod2001/12/04 06:37:14 1.9 @@ -28,6 +28,20 @@ WrapXS/ - autogenerated XS code blib/- ready to install version of the package +=head1 Directory src + +=head2 Directory src/modules/perl/ + +The directory I includes the C source files needed +to build the I library. + +Notice that several files in this directory are autogenerated during +the I stage. + +When adding new source files to this directory you should add their +names to the C<@c_src_names> variable in I, so +they will be picked up by the autogenerated I. + =head1 Directory xs/ Apache/ - Apache specific XS code @@ -281,6 +295,7 @@ modperl_xs_sv_convert.h modperl_xs_typedefs.h + - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/world/templates choosing.pod
stas02/01/02 01:35:02 Modified:src/docs/2.0/api/mod_perl-2.0/Apache compat.pod src/docs/2.0/devel/testing testing.pod src/docs/2.0/world/templates choosing.pod Log: - escape [><] chars Revision ChangesPath 1.2 +2 -2 modperl-docs/src/docs/2.0/api/mod_perl-2.0/Apache/compat.pod Index: compat.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/mod_perl-2.0/Apache/compat.pod,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- compat.pod2 Oct 2001 14:59:57 - 1.1 +++ compat.pod2 Jan 2002 09:35:02 - 1.2 @@ -25,7 +25,7 @@ =over -=item * $r->header_in() +=item * $r-Eheader_in() $r->header_in( $header_name, [$value] ) @@ -37,7 +37,7 @@ $r->header_in($key, $val); -=item * $r->header_out() +=item * $r-Eheader_out() $r->header_out( $header, $value ) 1.3 +1 -1 modperl-docs/src/docs/2.0/devel/testing/testing.pod Index: testing.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/devel/testing/testing.pod,v retrieving revision 1.2 retrieving revision 1.3 diff -u -r1.2 -r1.3 --- testing.pod 1 Jan 2002 12:11:50 - 1.2 +++ testing.pod 2 Jan 2002 09:35:02 - 1.3 @@ -429,7 +429,7 @@ =item 3 It reports all the successful reductions as it goes to STDOUT and -report file of the format: smoke-report-.txt. +report file of the format: smoke-report-EdateE.txt. In addition the systems build parameters are logged into the report file, so the detected problems could be reproduced. 1.5 +154 -154 modperl-docs/src/docs/2.0/world/templates/choosing.pod Index: choosing.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/world/templates/choosing.pod,v retrieving revision 1.4 retrieving revision 1.5 diff -u -r1.4 -r1.5 --- choosing.pod 12 Nov 2001 02:44:41 - 1.4 +++ choosing.pod 2 Jan 2002 09:35:02 - 1.5 @@ -915,160 +915,160 @@ =begin pod2html - - - - - - Application Framework - - - Pipeline or Callback - - - Parsing Method - - - Language - - - - - HTML::Mason - - - Framework - - - Callback - - - Compiled - - - Perl - - - - - Template Toolkit - - - Just Templates - - - Pipeline - - - Compiled - - - Mini-Language - - - - - Apache::ASP - - - Framework - - - Callback - - - Compiled - - - Perl and XSL - - - - - HTML::Embperl - - - Framework - - - Callback - - - Compiled - - - Perl - - - - - SSI - - - Just Templates - - - Callback - - - Repeated Parse - - - Mini-Language - - - - - AxKit - - - Framework - - - Pipeline - - - Compiled or Cached Parse Tree - - - Perl and XSL and Mini-Language(s) - - - - - HTML::Template - - - Just Templates - - - Pipeline - - - Cached Parse Tree - - - Mini-Language - - - - - Text::Template - - - Just Templates - - - Pipeline - - - Compiled - - - Perl - - - + + + + + +Application Framework + + +Pipeline or Callback + + +Parsing Method + + +Language + + + + +HTML::Mason + + +Framework + + +Callback + + +Compiled + + +Perl + + + + +Template Toolkit + + +Just Templates + + +Pipeline + + +Compiled + + +Mini-Language + + + + +Apache::ASP + + +Framework + + +Callback + + +Compiled + +
cvs commit: modperl-docs/src/docs/2.0/api/mod_perl-2.0/APR PerlIO.pod Table.pod
stas02/01/02 03:14:22 Modified:src/docs/2.0/api/mod_perl-2.0/APR PerlIO.pod Table.pod Log: - cannot have formatting chars in the NAME section, problems with rendered HTMl Revision ChangesPath 1.2 +2 -2 modperl-docs/src/docs/2.0/api/mod_perl-2.0/APR/PerlIO.pod Index: PerlIO.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/mod_perl-2.0/APR/PerlIO.pod,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- PerlIO.pod25 Dec 2001 07:37:33 - 1.1 +++ PerlIO.pod2 Jan 2002 11:14:22 - 1.2 @@ -1,6 +1,6 @@ =head1 NAME -C -- An APR Perl IO layer +APR:PerlIO -- An APR Perl IO layer =head1 SYNOPSIS @@ -28,7 +28,7 @@ mod_perl functions will return a filehandle which is internally hooked to APR. But you can use APR Perl IO directly if you want. -=head1 SYNOPSIS +=head1 METHODS Perl Interface: 1.4 +1 -1 modperl-docs/src/docs/2.0/api/mod_perl-2.0/APR/Table.pod Index: Table.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/mod_perl-2.0/APR/Table.pod,v retrieving revision 1.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- Table.pod 25 Oct 2001 11:32:42 - 1.3 +++ Table.pod 2 Jan 2002 11:14:22 - 1.4 @@ -1,6 +1,6 @@ =head1 NAME -C -- A Perl API for manipulating paque string-content table +APR::Table -- A Perl API for manipulating paque string-content table =head1 SYNOPSIS - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/devel/core_explained core_explained.pod
stas02/01/02 23:21:04 Modified:src/docs/2.0/devel/core_explained core_explained.pod Log: - a typo fix Revision ChangesPath 1.13 +1 -1 modperl-docs/src/docs/2.0/devel/core_explained/core_explained.pod Index: core_explained.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/devel/core_explained/core_explained.pod,v retrieving revision 1.12 retrieving revision 1.13 diff -u -r1.12 -r1.13 --- core_explained.pod31 Dec 2001 13:19:00 - 1.12 +++ core_explained.pod3 Jan 2002 07:21:04 - 1.13 @@ -486,7 +486,7 @@ apr_read_type | IV -C is used as a typemap, lSince enum is simply an integer. In more +C is used as a typemap, Since enum is just an integer. In more complex cases the typemap can be different. (META: examples) - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/devel/modperl_style modperl_style.pod
stas02/01/03 04:56:32
Modified:src/docs/2.0/devel/modperl_style modperl_style.pod
Log:
- minor style fixes
Revision ChangesPath
1.6 +4 -4
modperl-docs/src/docs/2.0/devel/modperl_style/modperl_style.pod
Index: modperl_style.pod
===
RCS file:
/home/cvs/modperl-docs/src/docs/2.0/devel/modperl_style/modperl_style.pod,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- modperl_style.pod 14 Nov 2001 03:41:35 - 1.5
+++ modperl_style.pod 3 Jan 2002 12:56:32 - 1.6
@@ -80,7 +80,7 @@
else {
$self->foo("one", 2, "...");
}
-
+
return $self;
}
@@ -323,11 +323,11 @@
=over
-=item * Stas Bekman Estas *at* stason.orgE
+=item * Stas Bekman Estas (at) stason.orgE
-=item * Doug MacEachernEdougm *at* covalent.netE
+=item * Doug MacEachernEdougm (at) covalent.netE
-=item * Tim Henigan Et.henigan *at* verizon.netE
+=item * Tim Henigan Et.henigan (at) verizon.netE
=back
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/lib - New directory
stas02/01/05 10:50:31 modperl-docs/lib - New directory - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/lib/DocSet - New directory
stas02/01/05 10:50:36 modperl-docs/lib/DocSet - New directory - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/lib/DocSet/Doc - New directory
stas02/01/05 10:50:44 modperl-docs/lib/DocSet/Doc - New directory - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/lib/DocSet/DocSet - New directory
stas02/01/05 10:50:44 modperl-docs/lib/DocSet/DocSet - New directory - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/lib/DocSet/Source - New directory
stas02/01/05 10:50:45 modperl-docs/lib/DocSet/Source - New directory - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/lib/DocSet/Template - New directory
stas02/01/05 10:50:45 modperl-docs/lib/DocSet/Template - New directory - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/lib/DocSet/Template/Plugin - New directory
stas02/01/05 10:51:17 modperl-docs/lib/DocSet/Template/Plugin - New directory - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/lib/DocSet/Template/Plugin NavigateCache.pm
stas02/01/05 10:51:59 Added: lib DocSet.pm lib/DocSet 5005compat.pm Cache.pm Config.pm Doc.pm DocSet.pm NavigateCache.pm RunTime.pm Util.pm lib/DocSet/Doc HTML2HTML.pm POD2HTML.pm Text2HTML.pm lib/DocSet/DocSet HTML.pm PSPDF.pm lib/DocSet/Source HTML.pm POD.pm Text.pm lib/DocSet/Template/Plugin NavigateCache.pm Log: - add the DocSet package locally until it gets released on CPAN Revision ChangesPath 1.1 modperl-docs/lib/DocSet.pm Index: DocSet.pm === package DocSet; $VERSION = '0.08'; =head1 NAME DocSet - documentation projects builder in HTML, PS and PDF formats =head1 SYNOPSIS pod2hpp [options] base_full_path relative_to_base_configuration_file_location Options: -hthis help -vverbose -ipodify pseudo-pod items (s/^* /=item */) -screate the splitted html version (not implemented) -tcreate tar.gz (not implemented) -pgenerate PS file -dgenerate PDF file -fforce a complete rebuild -aprint available hypertext anchors (not implemented) -ldo hypertext links validation (not implemented) -eslides mode (for presentations) (not implemented) -mexecuted from Makefile (forces rebuild, no PS/PDF file, no tgz archive!) =head1 DESCRIPTION This package builds a docset from sources in different formats. The generated documents can be all nicely interlinked and to have the same look and feel. Currently it knows to handle input formats: * POD * HTML and knows to generate: * HTML * PS * PDF =head2 Modification control Each output mode maintains its own cache (per docset) which is used when certain source documents weren't modified since last build and the build is running in a non-force-rebuild mode. =head2 Definitions: * Chapter is a single document (file). * Link is an URL * Docset is a collection of docsets, chapters and links. =head2 Application Specific Features =over =item 1 META: not ported yet! Generate a split version HTML, creating html file for each pod section, and having everything interlinked of course. This version is used best for the search. =item 1 Complete the POD on the fly from the files in POD format. This is used to ease the generating of the presentations slides, so one can use C<*> instead of a long =over/=item/.../=item/=back strings. The rest is done as before. Take a look at the special version of the html2ps format to generate nice slides in I. =item 1 META: not ported yet! If you turn the slides mode on, it automatically turns the C<-i> (C<*> preprocessing) mode and does a page break before each =head tag. =back =head2 Look-n-Feel Customization You can customise the look and feel of the ouput by adjusting the templates in the directory I. You can change look and feel of the PS (PDF) versions by modifying I. Be careful that if your documentation that you want to put in one PS or PDF file is very big and you tell html2ps to put the TOC at the beginning you will need lots of memory because it won't write a single byte to the disk before it gets all the HTML markup converted to PS. =head1 CONFIGURATION All you have to prepare is a single config file that you then pass as an argument to C: pod2hpp [options] /abs/project/root/path /full/path/to/config/file Every directory in the source tree may have a configuration file, which designates a docset's root. See the I files for examples. Usually the file in the root (I) sets operational directories and other arguments, which you don't have to repeat in sub-docsets. Modify these files to suit your documentation project layout. Note that I script automatically locates your project's directory, so you can move your project around filesystem without changing anything. I explains the layout of the directories. C manpage explains the layout of the configuration file. =head1 PREREQUISITES All these are not required if all you want is to generate only the html version. =over 4 =item * ps2pdf Needed to generate the PDF version =item * Storable Perl module available from CPAN (http://cpan.org/) Allows source modification control, so if you modify only one file you will not have to rebuild everything to get the updated HTML/PS/PDF files. =back =head1 SUPPORT Notice that this tool relies on two tools (ps2pdf and html2ps) which I don't support. So if you have any problem first make sure that it's not
cvs commit: modperl-docs/src/about - New directory
stas02/01/05 11:05:12 modperl-docs/src/about - New directory - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
