Installation of AxKit has been designed to be as simple as
possible (but we might not always get it right!).

If you do not have Apache and mod_perl installed, please scroll
down to "INSTALLATION OF MOD_PERL/APACHE".

CPAN SHELL WAY

The easiest way to install it is from the CPAN shell:

 $ su
 $ perl -MCPAN -e shell
 cpan> install AxKit

This will download AxKit, and install any pre-requisite
modules before installing it. You will also be asked questions
regarding optional modules that you may wish to install.

WITHOUT THE CPAN SHELL

If you do not have network access (due to firewalls), installation
is also fairly simple, it follows the common perl installation
idiom:

 $ perl Makefile.PL
 $ make
 $ make test
 $ su
 $ make install

The installer will check pre-requisite modules and automatically
install anything that is an absolute requirement before running.

INSTALLATION OF MOD_PERL/APACHE

Note that AxKit WILL NOT install Apache and mod_perl for you. That
is simply because these are extremely large and complex packages,
and you should install them yourself. However some people have
experienced problems with their installation of mod_perl (for
example segmentation faults). So here is my recipe for a stable
installation:

 Download mod_perl from http://perl.apache.org/
 Download Apache from http://www.apache.org/httpd.html
 Extract both archives in a suitable location (I use /tmp)
 Do not extract one archive in the other's directory - this
   will cause you problems.
 
 Now cd to the mod_perl directory, and enter the following:
 
 $ perl Makefile.PL \
 > EVERYTHING=1 \
 > USE_APACI=1 \
 > DYNAMIC=1 \
 > APACHE_PREFIX=/opt/apache \
 > APACHE_SRC=../apache_1.3.12/src \
 > DO_HTTPD=1 \
 > APACI_ARGS="--enable-module=so --enable-shared=info 
 > --enable-shared=proxy --enable-shared=rewrite 
 > --enable-shared=log_agent"
 $ make
 $ su
 $ make install

Note that in the above, the $ and > are part of your shell prompt,
not part of the commands to enter!

Also note that the paths for the APACHE_SRC and APACHE_PREFIX should
be fixed to the version of apache you downloaded, and the location
you wish to install Apache into, respectively.

ADVANCED INSTALLATION TIPS

The following options can be passed on the command line to AxKit's
Makefile.PL:

  DEBUG=1
  
    This option turns on lots of output from the running of Makefile.PL,
    use it in case you have problems installing AxKit and wish to
    send email to axkit-users@axkit.org with your problem.

  EXPAT_OPTS="..."
  
    Setting this option is only relevant if you do not already have
    libexpat installed. It lists options to be passed to libexpat's
    ./configure command. Such options might be "--prefix=/usr" which
    will install libexpat in /usr/lib, rather than the default
    location (which will likely be /usr/local/lib).

  LIBS="-L/path/to/expat/lib -lexpat"
  
    Allows you to set your library search path.

  INC="-I/path/to/expat/include"
  
    Allows you to set the include search path.

  NO_DIRECTIVES=1
  
    This option turns off AxKit's apache configuration directives,
    which means you will have to set these via PerlSetVar instead.
    
    This is useful because sometimes AxKit and mod_php can cause
    conflicts when using configuration directives (and results
    in segfaults). This is hopefully fixed in mod_perl 1.25.

    Note that you *must* manually remove all traces of AxKit from
    your /usr/lib/perl5/site_perl directory before re-running
    Makefile.PL with NO_DIRECTIVES=1 because unfortunately this
    causes AxKit to be installed in a completely different location,
    yet mod_perl will pick up the original copy compiled with
    directives, which is probably not what you want at all.

CONFIGURATION

In general you should read the AxKit Quick Start guide on
http://axkit.org/, but for the impatient, read on.

Once you have AxKit installed, you need to configure Apache to
associate XML files with AxKit.  In doing so, there are a few
considerations to make.  If your installation is only going to be
handling XML files (ex: no PHP or cgi requests) then it's safe to
include the following directives in your httpd.conf:

    # note the PerlModule line has to be *outside* any
    # <Files>, <Location>, <Directory> or <VirtualHost>
    # sections.
    PerlModule AxKit
    
    SetHandler axkit
    
    AxCacheDir /tmp/axkit_cache/
    AxAddStyleMap text/xsl Apache::AxKit::Language::LibXSLT

If, however, you are using other content handler modules, such
as PHP or mod_cgi to send content to the browser, you will more
than likely want to use AddHandler:

    PerlModule AxKit

    AddHandler axkit .xml
    AddHandler axkit .xsp
    
Another symptom that you want to wrap your configuration in a conditional
block is if you turn on debugging (see perldoc AxKit for AxDebugLevel),
request a test cgi program, receive the plain text version of the test 
cgi and see something similar to the following in your error logs:

      [warn] [AxKit] : handler called for /cgi-bin/test-cgi
      [warn] [AxKit] : checking if we process this resource
      [warn] [AxKit] [DECLINED] '/usr/local/www/cgi-bin/test-cgi' not 
      recognized as XML

GETTING HELP

If you are still stuck getting this to work, first of all, see the
AxKit FAQ at http://axkit.org/faq.xml - especially if your Apache
is segfaulting when using AxKit.

Then please send problem reports to axkit-users@axkit.org along with
information about what version of the following items you are running:

    AxKit
    mod_perl
    Apache
    Perl
    Operating System

However please note that installation problems regarding mod_perl,
Sablotron, or Apache should be directed to the appropriate places
for those modules, not to the axkit-users mailing list. Thank you.

Please do not send email direct to matt@sergeant.org for problems
with AxKit. Thank you.

IF EVERYTHING WORKS

Congratulations! You have a running AxKit. Now please visit
http://axkit.org/docs/quick_start.dkb for a guide to your first pages
with AxKit.

