INSTALL

PREREQUISITES
-------------

Install the prerequisites as listed in Makefile.PL.

The perl minimum version is probably 5.6.0, but see below.

CGI
---

You need to make cgi-bin/cpantestermatrix.pl available as a CGI script.

PLACK
-----

Alternatively: one very easy way of doing that is using the included
cpan-testers-matrix.psgi file that wraps up the CGI script in a PSGI
application. Just make sure the following modules are installed:

- Plack
- CGI::Emulate::PSGI
- CGI::Compile

Then point `plackup' or your favourite PSGI-supporting webserver at
it, e.g.:

  $ plackup cpan-testers-matrix.psgi
  HTTP::Server::PSGI: Accepting connections at http://0:5000/

Note that you might need to change the #! shebang in
cgi-bin/cpantestermatrix.pl if you want to run it with a perl other
than /usr/bin/perl.

APACHE
------

With apache + mod_perl you can use the nearly "zero conf"
configuration file etc/httpd.conf:

* Just include the configuration file for use into your Apache, e.g.
  on a FreeBSD system:

    cd /usr/local/etc/apache22/Includes
    ln -s /path/to/cpan-testers-matrix/etc/httpd.conf cpan-testers-matrix.conf

  Or on a Debian system (make sure the libapache2-mod-perl2 is installed)

    cd /etc/apache2/sites-enabled
    ln -s /path/to/cpan-testers-matrix/etc/httpd.conf cpan-testers-matrix.conf

* NameVirtualHost should be turned on in the standard Apache
  configuration, if not already done, e.g. add into the standard
  httpd.conf:

    NameVirtualHost *:80

* Add an entry with the hostname "matrix-cpantesters" to your local
  DNS, or, easier, to your /etc/hosts:

    127.0.0.1     matrix-cpantesters

* Restart the Apache, and point your browser to http://matrix-cpantesters

* Make sure that a cache file may be written by the Apache user. On a
  Debian system:

    touch -t 197001010000 cgi-bin/cpantesters_amendments.st
    sudo chown www-data cgi-bin/cpantesters_amendments.st


ADDITIONAL CONFIGURATION
------------------------

To support not only searching for dist names, but also for module
names, there is additional configuration necessary.

First, create a cpantestersmatrix.yml, which is located next to
cpantestersmatrix.cgi. This yaml file should contain a hash with the
following keys:

* cpan_home: pointing to the .cpan directory of a user where the
  packages file is regularily updated (see below)

* plain_packages_file: the path for a file where a uncompressed
  02packages file is written to. The parent directory must exist.

The distribution contains some sample files.

Additionally somehow it has to be made sure that CPAN's packages file
is updated regularily. This can be done with a cron job in /etc/cron.d
like the following:

15 0,6,12,18 * * * root perl -MCPAN -e 'CPAN::Index->reload'

QUICK STEPS TO GET make test RUNNING
------------------------------------

Shell commands to enable the run of 'make test' without configuring
for a full featured server:

 t=`mktemp -d`
 mkdir -p $t/sources/modules
 lwp-download http://www.cpan.org/modules/02packages.details.txt.gz $t/sources/modules/02packages.details.txt.gz
 echo "cpan_home: $t" > cgi-bin/cpantestersmatrix.yml
 echo "plain_packages_file: $t/plain_packages_file" >> cgi-bin/cpantestersmatrix.yml
 PERL_AUTHOR_TEST=1 make test

PROBLEMS
--------

It's recommended to use perl 5.14.0 or later because of slowness when
using taint mode. See
https://rt.perl.org/rt3/Public/Bug/Display.html?id=75954 This is
really only needed when viewing large author pages (e.g. ADAMK,
ZOFFIX). Another fix is to just remove "-T" from the
cgi-bin/cpantestermatrix.pl shebang.