AxKit Articles Demo and Examples Tarball
========================================

This tarball contains most of the C and Perl prerequisites that are
usually needed to build and operate an AxKit-enabled Apache web server.
Some older or special purpose Unix variants may need to have additional
prerequisites installed[1] or upgraded [2].  It also includes the
examples from the first two articles in the perl.com on AxKit.  The
first article may be found at:

    http://www.perl.com/pub/a/2002/03/12/axkit.html

This tarball has been tested (though not thoroughly) on RedHat 6.2 Linux
(or GNU/Linux, if you prefer) and on FreeBSD 4.1.  The Apache/mod_perl
httpd, AxKit, and all contained prerequisites are built by running

   perl install

in the same directory as this README.  NOTE:  The build can take some
time (about 9 minute on a 1GHz Pentium III with a single ISA disk and
512MB RAM): there are over 30 separate packages to install, including
Apache, mod_perl, and several XML handling C libraries.

When complete, the directory hierarchy looks something like:

   ./
   +--- README            # This file
   +--- install           # the install script.
   +--- dists/            # All of the tarballs
   +--- build/            # (created) where all the tarballs are built
   +-+- www/              # The final product
     +-+- bin/
       +--- apachectl    # How to stop and start the httpd
       +--- httpd        # The web server
       +--- ...          # lots of other goodies :)
     +--- htdocs/        # The example pages and Apache documentation
     +--- lib/           # All prerequisites and AxKit itself
     +-+- conf/          # All config files
       +--- httpd.conf  # The main Apache config file
     +-+- logs/
       +--- error_log   # Debug, warning, and error messages

The install script will not (easily) install things anywhere else.  If
you get a test failure or two, you might try cding in to the appropriate
build/...  directory and doing the "make && make install" for that
prerequisite, since this is an example server and a few test failures
might not impair it's ability to run examples (no guarantees, though!).
In this unfortunate eventuality, re-running perl install should pick up
where it left off and install the remainder of the system.

To start and stop the web server, use

    www/bin/apachectl start

and

    www/bin/apachectl stop

(assuming you're in the main directory created by untarring this
distribution).

If you doubt that the web server actually exited (or you re-ran install
without shutting it down), you might need to kill the httpd instances
manually.

By default (unless you run the install as root--please don't!), the web
server will be configured to listen on port 8080, so a command like

    lynx http://127.0.0.1:8080/

should get you the (trivial) page served up by the example given in the first
article.  It should say something like "Hi! It's 4:20:00."

If port 8080 is in use on your system, edit www/conf/httpd.conf and
change the Port directive to a better value.

Because this is a large tarball comprised almost exclusively of code I
didn't write, I can only offer advice on fixing any build problems.  Bug
reports, questions (and patches and answers to other's questions, of
course ;) should be submitted to AxKit-users@AxKit.org.  General
Apache/mod_perl questions should be directed to the mod_perl list
at modperl@perl.apache.org .

Later articles will be accompanied by new tarballs containing bug fixes,
updated libraries, and new examples.

Thanks,

Barrie Slaymaker

[1] The iconv library--which is required to do the character encoding
conversions that AxKit does automatically--is optional on
FreeBSD and OpenBSD, for instance.

[2] we recommend perl5.6.1, though perl5.00503 will do.  It is
especially important to not use perl5.6.0, even though it ships with
several recent distributions (it is known to have stability problems in
a mod_perl environment).
