--- /dev/null
+=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 && make install>, or C<portinstall
+p5-Catalyst> 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/katalytes/cat_on_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'
+ ...
+
projects / catagits/Catalyst-Runtime.git / blobdiff