Mailing List Archive

On Aug 24, 2004, at 3:09 PM, Randy Kobes wrote:

> Yes, F<> is understood (I've been using it for the Win32
> sections). There's a neat feature in the html conversion -
> if there's a (physical) file "foo", F<foo> will become a
> link to "foo".

Ah, yeah, that's slick. Thanks Randy.

So I made it as far as "Stress Testing", but then just filled in
Apache::TestMB information in the rest of the document. Hopefully I can
get to editing the remainder for grammar, punctuation, etc. sometime
soon.

Let me know if this looks good to you guys and I'll commit it.

Regards,

David

Index: src/docs/general/testing/testing.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/general/testing/testing.pod,v
retrieving revision 1.34
diff -u -r1.34 testing.pod
--- src/docs/general/testing/testing.pod 16 Jul 2004 21:46:11 -0000 1.34
+++ src/docs/general/testing/testing.pod 24 Aug 2004 21:54:31 -0000
@@ -6,12 +6,12 @@

The title is self-explanatory :)

-The C<Apache::Test> framework was designed for creating test suits for
-products running on Apache httpd webserver (not necessarily
+The C<Apache::Test> framework was designed for creating test suites for
+products running on the Apache httpd webserver (not necessarily
mod_perl). Originally designed for the mod_perl Apache module, it was
extended to be used for any Apache module.

-This chapter is talking about the C<Apache::Test> framework, and in
+This chapter discusses the C<Apache::Test> framework, and in
particular explains how to:

=over
@@ -27,29 +27,30 @@
For other C<Apache::Test> resources, see the
L<References|/"References">
section at the end of this document.

-=head1 Basics of Perl Modules Testing
+=head1 Basics of Perl Module Testing

The tests themselves are written in Perl. The framework provides an
-extensive functionality which makes the tests writing a simple and
+extensive functionality which makes writing tests a simple and
therefore enjoyable process.

-If you have ever written or looked at the tests most Perl modules come
-with, C<Apache::Test> uses the same concept. The script I<t/TEST> is
-running all the files ending with I<.t> it finds in the I<t/>
-directory. When executed a typical test prints the following:
+If you have ever written or looked at the tests that come with most
Perl
+modules, you'll recognize that C<Apache::Test> uses the same
+concepts. The script I<t/TEST> executes runs all the files ending with
+I<.t> that it finds in the I<t/> 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<ok> or C<not ok> is followed by the number which tells which
-sub-test has succeeded or failed.
+Every C<ok> or C<not ok> is followed by a number that identifies which
+sub-test has passed or failed.

-I<t/TEST> uses the C<Test::Harness> module which intercepts the
-C<STDOUT> 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.
+I<t/TEST> uses the C<Test::Harness> module, which intercepts the
+C<STDOUT> stream, parses it and at the end of the tests, prints the
+results of the tests: how many tests and sub-tests were run and
+how many passed, failed, or were skipped.

Some tests may be skipped by printing:

@@ -57,13 +58,13 @@

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.
-
-By default print() statements in the test script are filtered out by
-C<Test::Harness>. 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
+critical for the usefulness of the test. Once you determine that
+you cannot proceed with the tests, and it is not a requirement that
+the tests pass, you can just skip them.
+
+By default, C<print> statements in the test script are filtered out by
+C<Test::Harness>. If you want the test to print what it does (for
example,
+to debug a test) use the C<-verbose> option. So for example if
your test does this:

print "# testing : feature foo\n";
@@ -72,25 +73,50 @@
ok $expected eq $received;

in the normal mode, you won't see any of these prints. But if you run
-the test with I<t/TEST -verbose>, you will see something like this:
+the test with C<t/TEST -verbose>, 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.
+When you develop the test you should always insert the debug
statements,
+and once the test works for you, do not comment out or delete these
+debug statements. It's a good idea to leave them in 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 the report. It'll be much easier to
+understand the problem if you get these debug printings from the user.
+
+A simpler approach is to use the C<Test::More> module in your test
+scripts. This module offers many useful test functions, including
+C<diag>, a function that automatically escapes and passes strings to
+C<print> to bypass C<Test::Harnes>:
+
+ use Test::More;
+ diag "testing : feature foo\n";
+ diag "expected: $expected\n";
+ diag "received: $received\n";
+ ok $expected eq $received;
+
+In fact, for an example such as this, you can just use Test::More's
+C<is> function, which will output the necessary diagnostics in the
event
+of a test failure:
+
+ is $received, $expected;
+
+For which the output for a test failure would be something like:
+
+not ok 1
+# Failed test (-e at line 1)
+# got: '1'
+# expected: '2'

-In the section L<Writing Tests|/"Writing_Tests"> several helper
functions which make
-the tests writing easier are discussed.
+The L<Writing Tests|/"Writing_Tests"> section documents several helper
+functions that make simplify the writing of tests.

For more details about the C<Test::Harness> module please refer to its
-manpage. Also see the C<Test> manpage about Perl's test suite.
+manpage. Also see the C<Test> and C<Test::More> manpages for
+documentation of Perl's test suite.

=head1 Prerequisites

@@ -102,19 +128,18 @@
% perl Makefile.PL
% make && make test && make install

-If you install mod_perl 2.0, you get C<Apache::Test> installed as
-well.
+If you install mod_perl 2.0, C<Apache::Test> will be installed with it.

=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.
+It's much easier to copy existing examples than to create something
from
+scratch. It's also simpler to develop tests when you have some existing
+system that to test, so that you can see how it works and build your
own
+testing environment in a similar fashion. So 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<perl-framework>)
-testing environments which both use C<Apache::Test> for their test
+testing environments, both of which use C<Apache::Test> for their test
suites.

=head2 Testing Options
@@ -123,7 +148,7 @@

% t/TEST -help

-to get the list of options you can use during testing. Most options
+to get a list of options you can use during testing. Most options
are covered further in this document.

=head2 Basic Testing
@@ -135,31 +160,31 @@
% make

Now we can do the testing. You can run the tests in two ways. The
-first one is usual:
+first one is the usual:

% make test

-but it adds quite an overhead, since it has to check that everything
-is up to date (the usual C<make> source change control). Therefore you
-have to run it only once after C<make> and for re-running the tests
-it's faster to run the tests directly via:
+But this approach adds quite an overhead, since it has to check that
+everything is up to date (the usual C<make> source change control).
+Therefore, you have to run it only once after C<make>; for re-running
+the tests, it's faster to run them directly via:

% t/TEST

-When C<make test> or C<t/TEST> are run, all tests found in the I<t>
+When C<make test> or C<t/TEST> is run, all tests found in the I<t>
directory (files ending with I<.t> are recognized as tests) will be
run.

=head2 Individual Testing

-To run a single test, simple specify it at the command line. For
-example to run the test file I<t/protocol/echo.t>, execute:
+To run a single test, simply specify it at the command line. For
+example, to run the test file I<t/protocol/echo.t>, execute:

% t/TEST protocol/echo

-Notice that you don't have to add the I<t/> 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:
+Notice that the I<t/> prefix and the I<.t> extension for the test
+filenames are optional when you specify them explicitly. Therefore the
+following are all valid commands:

% t/TEST protocol/echo.t
% t/TEST t/protocol/echo
@@ -170,13 +195,13 @@
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
+mode and, depending on how the tests were written, you may get more
+debugging information under this mode. Verbose mode is turned on with
I<-verbose> option:

% t/TEST -verbose protocol/echo

-You can run groups of tests at once. This command:
+You can run groups of tests at once, too. This command:

% ./t/TEST modules protocol/echo

@@ -186,10 +211,10 @@

=head2 Repetitive Testing

-By default when you run the test without I<-run-tests> option, the
+By default, when you run tests without the I<-run-tests> option, the
server will be started before the testing and stopped at the end. If
-during a debugging process you need to re-run tests without a need to
-restart the server, you can start the server once:
+during a debugging process you need to re-run tests without the need to
+restart the server, you can start it once:

% t/TEST -start-httpd

@@ -203,39 +228,39 @@

% t/TEST -stop-httpd

-When the server is started you can modify I<.t> files and rerun the
-tests without restarting the server. However if you modify response
+When the server is running, you can modify I<.t> files and rerun the
+tests without restarting it. But if you modify response
handlers, you must restart the server for changes to take an
-effect. However the changes are done in the perl code only, it's
-possible to orrange for Apache::Test to L<handle the code reload
+effect. However, if the changes are only to perl code, it's
+possible to arrange for Apache::Test to L<handle the code reload
without restarting the
server|/Using_Apache__Test_to_Speed_up_Project_Development>.

The I<-start-httpd> option always stops the server first if any is
running.

-Normally when I<t/TEST> is run without specifying the tests to run,
+Normally, when I<t/TEST> is run without specifying the tests to run,
the tests will be sorted alphabetically. If tests are explicitly
-passed as arguments to I<t/TEST> they will be run in a specified
+passed as arguments to I<t/TEST> they will be run in the specified
order.

=head2 Parallel Testing

Sometimes you need to run more than one C<Apache::Test> framework
instances at the same time. In this case you have to use different
-ports for each instance. You can specify explicitly which port to use,
-using the I<-port> configuration option. For example to run the server
-on port 34343:
+ports for each instance. You can specify explicitly which port to use
+using the I<-port> configuration option. For example, to run the server
+on port 34343, do this:

% t/TEST -start-httpd -port=34343

-or by setting an evironment variable C<APACHE_TEST_PORT> to the
-desired value before starting the server.
+You can also affect the port by setting the C<APACHE_TEST_PORT>
+evironment variable to the desired value before starting the server.

Specifying the port explicitly may not be the most convenient option
if you happen to run many instances of the C<Apache::Test> framework.
-The I<-port=select> option comes to help. This option will
-automatically pick for the next available port. For example if you
+The I<-port=select> option helps such situations. This option will
+automatically select the next available port. For example if you
run:

% t/TEST -start-httpd -port=select
@@ -243,48 +268,46 @@
and there is already one server from a different test suite which uses
the default port 8529, the new server will try to use a higher port.

-There is one problem that remains to be resolved though. It's possible
+There is one problem that remains to be resolved, though. It's possible
that two or more servers running I<-port=select> will still decide to
use the same port, because when the server is configured it only tests
-whether the port is available but doesn't call bind()
-immediately. Thefore there is a race condition here, which needs to be
-resolved. Currently the workaround is to start the instances of the
-C<Apache::Test> framework with a slight delay between each other.
-Depending on the speed of you machine, 4-5 seconds can be a good
-choice. that's approximately the time it takes to configure and start
-the server on a quite slow machine.
+whether the port is available but doesn't call bind() immediately. This
+race condition needs to be resolved. Currently the workaround is to
+start the instances of the C<Apache::Test> framework with a slight
delay
+between them. Depending on the speed of your machine, 4-5 seconds can
be
+a good choice, as this is the approximate the time it takes to
configure
+and start the server on a quite slow machine.

=head2 Verbose Mode

-In case something goes wrong you should run the tests in the verbose
-mode:
+In case something goes wrong you should run the tests in verbose mode:

% t/TEST -verbose

-In this case the test may print useful information, like what values
+In verbose mode, 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 filtered out by C<Test::Harness>. When running in the
-I<verbose> mode usually it's a good idea to run only problematic tests
-to minimize the size of the generated output.
+to report these. In silent mode (without C<-verbose>), these printouts
+are filtered out by C<Test::Harness>. When running in I<verbose>, mode
+usually it's a good idea to run only problematic tests in order to
+minimize the size of the generated output.

-When debugging problems it helps to keep the I<error_log> file open in
-another console, and see the debug output in the real time via
+When debugging tests, it often helps to keep the I<error_log> file open
+in another console, and see the debug output in the real time via
tail(1):

% tail -f t/logs/error_log

Of course this file gets created only when the server starts, so you
cannot run tail(1) on it before the server starts. Every time C<t/TEST
--clean> is run, I<t/logs/error_log> gets deleted, therefore you have
-to run the tail(1) command again, when the server is started.
+-clean> is run, I<t/logs/error_log> gets deleted; therefore, you'll
have
+to run the tail(1) command again once the server starts.

=head2 Colored Trace Mode

If your terminal supports colored text you may want to set the
-environment variable C<APACHE_TEST_COLOR> to 1 to enable the colored
-tracing when running in the non-batch mode, which makes it easier to
-tell the reported errors and warnings, from the rest of the
+environment variable C<APACHE_TEST_COLOR> to 1 to enable any colored
+tracing when running in the non-batch mode. Colored tracing mode can
+make it easier to discriminate errors and warnings from other
notifications.

=head2 Controlling the Apache::Test's Signal to Noise Ratio
@@ -296,14 +319,14 @@

emerg alert crit error warning notice info debug

-where I<emerg> is the for the most important messages and I<debug> for
-the least important ones.
+where I<emerg> is the for the most important messages and I<debug> is
+for the least important ones.

-Currently the default level is I<info>, therefore any messages which
-fall into the I<info> category and above (I<notice>, I<warning>, etc).
-This tracing level is unrelated to the Apache's C<LogLevel> mechanism,
-which Apache-Test sets to C<debug> in F<t/conf/httpd.conf> and you can
-override it F<t/conf/extra.conf.in>.
+Currently, the default level is I<info>; therefore, any messages which
+fall into the I<info> category and above (I<notice>, I<warning>, etc)
+will be output. This tracing level is unrelated to Apache's C<LogLevel>
+mechanism, which Apache-Test sets to C<debug> in F<t/conf/httpd.conf>
+and which you can override F<t/conf/extra.conf.in>.

Let's assume you have the following code snippet:

@@ -315,11 +338,11 @@

% t/TEST -trace=warning ...

-now only the warning message
+now only the warning message

careful, perl on the premises

-will be printed. If you want to see the I<debug> messages you can
+will be printed. If you want to see I<debug> messages, you can
change the default level using I<-trace> option:

% t/TEST -trace=debug ...
@@ -330,29 +353,30 @@
to a file. Refer to the C<Apache::TestTrace> manpage for more
information.

-Finally you can use methods: C<emerg()>, C<alert()>, C<crit()>,
-C<error()>, C<warning()>, C<notice()>, C<info()> and C<debug()> in
-your client and server side code. This if useful for example if you
-have some debug tracing that you don't want to be printed during the
-normal C<make test>. However if some users have a problem you can ask
-them to run the test suite with the trace level of 'debug' and voila
-they can send you the extra debug output. Moreveor all these functions
-use C<Data::Dumper> to dump arguments which are references to perl
-structures. So for example your code may look like:
+Finally, you can use the C<emerg()>, C<alert()>, C<crit()>, C<error()>,
+C<warning()>, C<notice()>, C<info()> and C<debug()> methods in your
+client and server side code. These methods are useful when, for
example,
+you have some debug tracing that you don't want to be printed during
the
+normal C<make test> or C<.Build test>. However, if some users have a
+problem you can ask them to run the test suite with the trace level set
+to 'debug' and, voila, they can send you the extra debug output.
+Moreveor, all of these functions use C<Data::Dumper> to dump arguments
+that are references to perl structures. So for example your code may
+look like:

use Apache::TestTrace;
...
my $data = { foo => bar };
debug "my data", $data;

-and only when run with C<-trace=debug> it'll output.
+and only when run with C<-trace=debug> it'll output:

my data
$VAR1 = {
'foo' => 'bar'
};

-Normally it will not print anything.
+Normally it will print nothing.



@@ -792,7 +816,7 @@
=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
+later we can distribute it on CPAN. We are going to develop an
C<Apache::Amazing> module as an example.

% h2xs -AXn Apache::Amazing
@@ -806,8 +830,8 @@
C<h2xs> is a nifty utility that gets installed together with Perl and
helps us to create some of the files we will need later.

-However we are going to use a little bit different files layout,
-therefore we are going to move things around a bit.
+However, we are going to use a slightly different file layout;
therefore we
+are going to move things around a bit.

We want our module to live in the I<Apache-Amazing> directory, so we
do:
@@ -819,7 +843,7 @@

% cd Apache-Amazing

-We don't need the I<test.pl>. as we are going to create a whole
+We don't need the I<test.pl>, as we are going to create a whole
testing environment:

% rm test.pl
@@ -832,22 +856,22 @@
% mkdir lib/Apache
% mv Amazing.pm lib/Apache

-Now we adjust the I<lib/Apache/Amazing.pm> to look like this:
+Now we adjust I<lib/Apache/Amazing.pm> to look like this:

#file:lib/Apache/Amazing.pm
#--------------------------
package Apache::Amazing;
-
+
use strict;
use warnings;
-
+
use Apache::RequestRec ();
use Apache::RequestIO ();
-
+
$Apache::Amazing::VERSION = '0.01';
-
+
use Apache::Const -compile => 'OK';
-
+
sub handler {
my $r = shift;
$r->content_type('text/plain');
@@ -858,21 +882,51 @@
__END__
... pod documentation goes here...

-The only thing it does is setting the I<text/plain> header and
+The only thing our modules does is set the I<text/plain> header and
responding with I<"Amazing!">.

-Next adjust or create the I<Makefile.PL> file:
+Next, you have a choice to make. Perl modules typically use one of two
+build systems: C<ExtUtils::MakeMaker> or C<Module::Build>.
+
+C<ExtUtils::MakeMaker> is the traditional Perl module build system, and
+comes preinstalled with Perl. It generates a tradiational F<Makefile>
to
+handle the build process. The code to generate the F<Makefile> resides
+in F<Makefile.PL>.
+
+C<Module::Build> is a new build system, available from CPAN, and
+scheduled to be added to the core Perl distribution in version 5.10,
+with the goal of eventually replacing
+C<ExtUtils::MakeMaker>. C<Module::Build> uses pure Perl code to manage
+the build process, making it much easier to override its behavior to
+perform special build tasks. It is also more portable, since it relies
+on Perl itself, rather than the C<make> utility.
+
+So the decision you need to make is which system to use. Most modules
on
+CPAN use C<ExtUtils::MakeMaker>, and for most simple modules it is more
+than adequate. But more and more modules are moving to C<Module::Build>
+so as to take advantage of its new features. C<Module::Build> is the
+future of Perl build systems, but C<ExtUtils::MakeMaker> is likely to
be
+around for some time to come.
+
+Fortunately, C<Apache::Test> makes it easy to use either build system.
+
+=over 4
+
+=item C<ExtUtils::MakeMaker>
+
+If you decide to use C<ExtUtils::MakeMaker>, adjust or create the
+I<Makefile.PL> file to use C<Apache::TestMM>:

#file:Makefile.PL
#----------------
require 5.6.1;
-
+
use ExtUtils::MakeMaker;
-
+
use lib qw(../blib/lib lib );
-
+
use Apache::TestMM qw(test clean); #enable 'make test'
-
+
# prerequisites
my %require =
(
@@ -897,18 +951,55 @@
) : ()
),
);
-
+
sub clean_files {
return [@scripts];
}

-C<Apache::TestMM> will do a lot of thing for us, such as building a
-complete Makefile with proper I<'test'> and I<'clean'> targets,
+C<Apache::TestMM> does a lot of thing for us, such as building a
+complete F<Makefile> with proper I<'test'> and I<'clean'> targets,
automatically converting I<.PL> and I<conf/*.in> files and more.

-As you see we specify a prerequisites hash with I<Apache::Test> in it,
-so if the package gets distributed on CPAN, C<CPAN.pm> shell will know
-to fetch and install this required package.
+As you can see, we specify a prerequisites hash that includes
+I<Apache::Test>, so if the package gets distributed on CPAN, the
+C<CPAN.pm> and C<CPANPLUS> shells will know to fetch and install this
+required package.
+
+=item C<Module::Build>
+
+If you decide to use C<Module::Build>, the process is even simpler.
Just
+delete the F<Makefile.PL> file and create F<Build.PL> instead. It
should
+look somethiing like this:
+
+ use Module::Build:
+
+ my $build_pkg = eval { require Apache::TestMB }
+ ? 'Apache::TestMB' : 'Module::Build';
+
+ my $build = $build_pkg->new(
+ module_name => 'Apache::Amazing',
+ license => 'perl',
+ build_requires => { Apache::Test => '1.12' },
+ create_makefile_pl => 'passthrough',
+ );
+ $build->create_build_script;
+
+Note that the first thing this script does is check to be sure that
+C<Apache::TestMB> is installed. If it is not, and your module is
+installed with the C<CPAN.pm> or C<CPANPLUS> shells, it will be
+installed before continuing. This is because we've specified that
+C<Apache::Test> 1.12 (the first version of C<Apache::Test> to include
+C<Apache::TestMB>) is required to build the module (in this case,
+because its tests require it). We've also specified what license the
+module is distributed under, and that a passthrough F<Makefile.PL>
+should be generated. This last parameter helps those who don't have
+C<Module::Build> installed, as it allows them to use an
+C<ExtUtils::MakeMaker>-style F<Makefile.PL> script to build, test, and
+install the module (although what the passthrough script actually does
+is install C<Module::Build> from CPAN and pass build commands through
to
+our C<Build.PL> script).
+
+=back

Next we create the test suite, which will reside in the I<t>
directory:
@@ -921,19 +1012,19 @@
#file:t/TEST.PL
#--------------
#!perl
-
+
use strict;
use warnings FATAL => 'all';
-
+
use lib qw(lib);
-
+
use Apache::TestRunPerl ();
-
+
Apache::TestRunPerl->new->run(@ARGV);

-Assuming that C<Apache::Test> is already installed on your system and
-Perl can find it. If not you should tell Perl where to find it. For
-example you could add:
+This script assumes that C<Apache::Test> is already installed on your
+system and that Perl can find it. If not, you should tell Perl where to
+find it. For example you could add:

use lib qw(Apache-Test/lib);

@@ -944,21 +1035,27 @@
but C<#!perl>. When I<t/TEST> is created the correct path will be
placed there automatically.

+B<Note:> If you use C<Apache::TestMB> in a F<Build.PL> script, the
+creation of the F<t/TEST.PL> script is optional. You only need to
create
+it if you need it to do something special that the above example does
+not.
+
Next we need to prepare extra Apache configuration bits, which will
reside in I<t/conf>:

% mkdir t/conf

-We create the I<t/conf/extra.conf.in> file which will be automatically
+We create the I<t/conf/extra.conf.in> file, which will be automatically
converted into I<t/conf/extra.conf> before the server starts. If the
-file has any placeholders like C<@documentroot@>, these will be
-replaced with the real values specific for the used server. In our
-case we put the following configuration bits into this file:
+file has any placeholders like C<@documentroot@>, these will be
replaced
+with the real values specific for the Apache server used for the
+tests. In our case, we put the following configuration bits into this
+file:

#file:t/conf/extra.conf.in
#-------------------------
# this file will be Include-d by @ServerRoot@/httpd.conf
-
+
# where Apache::Amazing can be found
PerlSwitches -I@ServerRoot@/../lib
# preload the module
@@ -968,9 +1065,10 @@
PerlResponseHandler Apache::Amazing
</Location>

-As you can see we just add a simple E<lt>LocationE<gt> container and
+As you can see, we just add a simple E<lt>LocationE<gt> container and
tell Apache that the namespace I</test/amazing> should be handled by
-C<Apache::Amazing> module running as a mod_perl handler. Notice that:
+the C<Apache::Amazing> module running as a mod_perl handler. Notice
+that:

SetHandler modperl

@@ -987,19 +1085,19 @@
#-----------
use strict;
use warnings FATAL => 'all';
-
+
use Apache::Amazing;
use Apache::Test;
use Apache::TestUtil;
use Apache::TestRequest 'GET_BODY';
-
+
plan tests => 2;
-
+
ok 1; # simple load test
-
+
my $url = '/test/amazing';
my $data = GET_BODY $url;
-
+
ok t_cmp(
"Amazing!",
$data,
@@ -1024,11 +1122,21 @@
#...
);

-in this case I<README> will be created from the documenation POD
-sections in I<lib/Apache/Amazing.pm>, but the file has to exists for
-I<make dist> to succeed.
+Or for C<Module::Build> to generate the F<README> with:

-and finally we adjust or create the I<MANIFEST> file, so we can
+ #file:Build.PL
+ #-------------
+ my $build = $build_pkg->new(
+ #...
+ create_readme => 1,
+ #...
+ );
+
+In these cases, I<README> will be created from the documenation POD
+sections in I<lib/Apache/Amazing.pm>, but the file must exist for
+I<make dist> or C<./Build.PL dist> to succeed.
+
+And finally, we adjust or create the I<MANIFEST> file, so we can
prepare a complete distribution. Therefore we list all the files that
should enter the distribution including the I<MANIFEST> file itself:

@@ -1038,14 +1146,19 @@
t/TEST.PL
t/basic.t
t/conf/extra.conf.in
- Makefile.PL
+ Makefile.PL # and/or Build.PL
Changes
README
MANIFEST

+You can automate the creation or updating of the F<MANIFEST> file using
+C<make manifest> with F<Makefile.PL> or C<./Build manifest> with
+F<Build.PL>.
+
That's it. Now we can build the package. But we need to know the
location of the C<apxs> utility from the installed httpd server. We
-pass its path as an option to I<Makefile.PL>:
+pass its path as an option to I<Makefile.PL> or F<Build.PL>. To build,
+test, and install the module with F<Makefile.PL>, do this:

% perl Makefile.PL -apxs ~/httpd/prefork/bin/apxs
% make
@@ -1063,16 +1176,28 @@

% make dist

-will create the package which can be immediately uploaded to CPAN. In
-this example the generated source package with all the required files
-will be called: I<Apache-Amazing-0.01.tar.gz>.
+This build command will create the package which can be immediately
+uploaded to CPAN. In this example, the generated source package with
all
+the required files will be called: I<Apache-Amazing-0.01.tar.gz>.
+
+The same process can be accomplished with F<Buiild.PL> like so:
+
+ # perl Build.PL -apxs ~/httpd/prefork/bin/apxs
+ % ./Build
+ % ./Build test
+
+ basic...........ok
+ All tests successful.
+ Files=1, Tests=2, 1 wallclock secs ( 0.52 cusr + 0.02 csys = 0.54
CPU)
+
+ % ./Build install
+ % ./Build dist

The only thing that we haven't done and hope that you will do is to
write the POD sections for the C<Apache::Amazing> module, explaining
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<httpd.conf> configuration and perl
@@ -1176,6 +1301,10 @@

% perl Makefile.PL -httpd_conf /path/to/httpd.conf

+or with F<Build.PL>:
+
+ % perl Build.PL -httpd_conf /path/to/httpd.conf
+
or during the configuration:

% t/TEST -conf -httpd_conf /path/to/httpd.conf
@@ -1300,8 +1429,9 @@

The configuration part for this test will be autogenerated by the
C<Apache::Test> framework and added to the autogenerated file
-I<t/conf/httpd.conf> when C<make test> or C<t/TEST -configure> is
-run. In our case the following configuration section will be added:
+I<t/conf/httpd.conf> when C<make test> or C<./Build test> or C<t/TEST
+-configure> is run. In our case the following configuration section
will
+be added:

<Location /TestApache__write>
SetHandler modperl
@@ -3058,22 +3188,22 @@
choice but to restart the server before you want to test the modified
code.

-First of all, your perl modules need to reside under the I<lib>
+First of all, your Perl modules need to reside under the I<lib>
directory, the same way they reside in I<blib/lib>. In the section
-L<Basic Testing
-Environment|/Basic_Testing_Environment> we've already arranged for
that.
-If I<Amazing.pm> resides in the top-level directory, it's not possible
-to perform C<'require Apache::Amazing'>. Only after running C<make>,
-the file will be moved to I<blib/lib/Apache/Amazing.pm>, which is when
-we can load it. But you don't want to run C<make> every time you
-change the file. It's both annoying and error-prone, since at times
-you'd do some change, try to verify it and it will appear to be wrong,
-and you will try to understand why, whereas in reality you just forgot
-to run C<make> and the server was testing against the old unmodified
-version in C<blib/lib>. Of you course if you always run C<make test>
-it'll always do the right thing, but it's not the most effecient way
-to undertake when you want to test a specific test and you do it every
-few seconds.
+L<Basic Testing Environment|/Basic_Testing_Environment>, we've already
+arranged for that. If I<Amazing.pm> resides in the top-level directory,
+it's not possible to perform C<'require Apache::Amazing'>. Only after
+running C<make> or C<./Build> wil the file be moved to
+I<blib/lib/Apache/Amazing.pm>, which is when we can load it. But you
+don't want to run C<make> or C<./Build> every time you change the
+file. It's both annoying and error-prone, since at times you'd make a
+change, try to verify it, and it will appear to be wrong for no obvious
+reason. What will really have happend is that you just forgot to run
+C<make> or C<./Build> and the server was testing against the old
+unmodified version in C<blib/lib>. Of course, if you always run C<make
+test> or C<./Build test>, it'll always do the right thing, but it's not
+the most effecient approach to undertake when you want to test a
+specific test and you do it every few seconds.

The following scenario will make you a much happier Perl developer.

@@ -3090,8 +3220,8 @@
I<t/conf/modperl_inc.pl>. This technique is convenient since you don't
need to modify your code to include that directory.

-Second, we need to configure mod_perl to use C<Apache::Reload> to
-automatically reload the module when it's changed, by adding following
+Second, we need to configure mod_perl to use C<Apache::Reload>--to
+automatically reload the module when it's changed--by adding following
configuration directives to I<t/conf/extra.conf.in>:

PerlModule Apache::Reload
@@ -3099,7 +3229,7 @@
PerlSetVar ReloadAll Off
PerlSetVar ReloadModules "Apache::Amazing"

-(For more information about C<Apache::Reload>, depending on the used
+(For more information about C<Apache::Reload>, depending on the
mod_perl generation, refer to L<the mod_perl 1.0
documentation|docs::1.0::guide::porting/Using_Apache__Reload> or
L<the C<Apache::Reload> manpage for mod_perl