=head1 NAME
Catalyst::Manual::Installation - Catalyst Installation
=head1 DESCRIPTION
How to install Catalyst.
=head1 INSTALLATION
One of the frequent problems reported by new users of Catalyst is that
it can be extremely time-consuming and difficult to install.
One of the great strengths of Perl as a programming language is its use
of CPAN, the Comprehensive Perl Archive Network, an enormous global
repository containing over 10,000 free modules. For almost any basic
task--and a very large number of non-basic ones--there is a module on
CPAN that will help you. Catalyst has taken advantage of this, and uses
a very large number of CPAN modules, rather than reinventing the wheel
over and over again. On the one hand, Catalyst gains power and
flexibility through this re-use of existing code. On the other hand,
Catalyst's reliance on CPAN can complicate initial installations,
especially in shared-hosting environments where you, the user, do not
have easy control over what versions of other modules are installed.
It is worth stressing that the difficulties found in installing Catalyst
are caused not by anything intrinsic to Catalyst itself, but rather by
the interrelated dependencies of a large number of required modules.
Fortunately, there are a growing number of methods that can dramatically
ease this undertaking. Note that for many of these, you will probably
need to install additional Catalyst-related modules (especially plugins)
to do the things you want. As of version 5.70, Catalyst has split into
two packages, L<Catalyst::Runtime>, which includes the core elements
necessary to deploy a Catalyst application, and L<Catalyst::Devel>,
which includes the Helpers and other things necessary or useful for
developing Catalyst applications. In a purely deployment environment
you can omit L<Catalyst::Devel>.
=over 4
=item *
Matt Trout's C<cat-install> script
Available at L<http://www.shadowcatsystems.co.uk/static/cat-install>,
C<cat-install> can be a quick and painless way to get Catalyst up and
running on your system. Just download the script from the link above
and type C<perl cat-install>. This script automates the process of
installing Catalyst itself and its dependencies, with bits of overriding
so that the process does not require user interaction. C<cat-install>
installs Catalyst and its dependencies using the L<CPAN> module, so that
modules are installed the same way you would probably install them
normally--it just makes it easier. This is a recommended solution for
installation.
=item *
Chris Laco's CatInABox
CatInABox is a complete version of Catalyst that is installed locally on
your system, so that you don't need to go through the effort of doing a
full install. Simply download the tarball from
L<http://handelframework.com/downloads/CatInABox.tar.gz> and unpack it
on your machine. Depending on your OS platform, either run C<start.bat>
or C<start.sh> to set your bin/PERLLIB paths. This tarball contains
everything needed to try out Catalyst including Catalyst itself,
Template Toolkit, several Authentication modules, StackTrace, and a few
other plugins.
A special Win32 version is available upon request that contains many
more plugins and pre-compiled modules, including DBIx::Class, DBI,
SQLite, and Session support. If you are interested in this version,
please send e-mail to C<claco@chrislaco.com>.
=item *
Pre-Built VMWare Images
Under the VMWare community program, work is ongoing to develop a number
of VMWare images where an entire Catalyst development environment has
already been installed, complete with database engines and a full
complement of Catalyst plugins.
=back
=head2 OTHER METHODS
In addition to the "all-in-one" approaches mentioned above, there are a
variety of other installation techniques:
=over 4
=item *
CPAN
The traditional way to install Catalyst is directly from CPAN using the
C<Task::Catalyst> bundle and C<Catalyst::Devel>:
$ perl -MCPAN -e 'install Task::Catalyst'
$ perl -MCPAN -e 'install Catalyst::Devel'
Unless you have a particularly complete set of Perl modules already
installed, be prepared for a large number of nested dependencies.
=item *
Gentoo Linux
For users of Gentoo, see
C<http://gentoo-wiki.com/HOWTO_Catalyst_Framework> for automated
installations. In short, simply mount the portage overlay and type
C<emerge catalystframework>.
=item *
FreeBSD
FreeBSD users can get up and running quickly by typing C<cd
/usr/ports/www/p5-Catalyst-Devel && make install>, or C<portinstall
p5-Catalyst-Devel> if C<portinstall> is installed on your system.
=item *
Windows ActivePerl
Windows users can take advantage of the PPM tool that comes with
ActivePerl to jumpstart their Catalyst environment. Directions are
available at L<http://catalyst.infogami.com/install/windows>.
=item *
Subversion Repository
Catalyst uses Subversion for version control. To checkout the latest:
$ svn co http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Runtime/
=back
B<NOTE:> Although all of the above methods can be used to install a base
Catalyst system, only the VMWare image is likely to have all of the
plugins and modules you need to use Catalyst properly. When you start
the C<script/myapp_server.pl> development server, it will tell you about
any modules that are missing. To add them, type something along the
lines of the following (C<Catalyst::Model::DBIC::Schema> is used here as
a representative example):
# perl -MCPAN -e 'install Catalyst::Model::DBIC::Schema'
...