lib/Catalyst/Manual/Installation.pod

   1 =head1 NAME
   2
   3 Catalyst::Manual::Installation - Catalyst Installation
   4
   5 =head1 DESCRIPTION
   6
   7 How to install Catalyst.
   8
   9 =head1 INSTALLATION
  10
  11 One of the frequent problems reported by new users of Catalyst is that
  12 it can be extremely time-consuming and difficult to install.
  13
  14 One of the great strengths of Perl as a programming language is its use
  15 of CPAN, the Comprehensive Perl Archive Network, an enormous global
  16 repository containing over 10,000 free modules.  For almost any basic
  17 task--and a very large number of non-basic ones--there is a module on
  18 CPAN that will help you. Catalyst has taken advantage of this, and uses
  19 a very large number of CPAN modules, rather than reinventing the wheel
  20 over and over again.  On the one hand, Catalyst gains power and
  21 flexibility through this re-use of existing code. On the other hand,
  22 Catalyst's reliance on CPAN can complicate initial installations,
  23 especially in shared-hosting environments where you, the user, do not
  24 have easy control over what versions of other modules are installed.
  25
  26 It is worth stressing that the difficulties found in installing Catalyst
  27 are caused not by anything intrinsic to Catalyst itself, but rather by
  28 the interrelated dependencies of a large number of required modules.
  29
  30 Fortunately, there are a growing number of methods that can dramatically
  31 ease this undertaking. Note that for many of these, you will probably
  32 need to install additional Catalyst-related modules (especially plugins)
  33 to do the things you want. As of version 5.70, Catalyst has split into
  34 two packages, L<Catalyst::Runtime>, which includes the core elements
  35 necessary to deploy a Catalyst application, and L<Catalyst::Devel>,
  36 which includes the Helpers and other things necessary or useful for
  37 developing Catalyst applications.  In a purely deployment environment
  38 you can omit L<Catalyst::Devel>.
  39
  40 =over 4
  41
  42 =item *
  43
  44 Matt Trout's C<cat-install> script
  45
  46 Available at L<http://www.shadowcatsystems.co.uk/static/cat-install>,
  47 C<cat-install> can be a quick and painless way to get Catalyst up and
  48 running on your system.  Just download the script from the link above
  49 and type C<perl cat-install>. This script automates the process of
  50 installing Catalyst itself and its dependencies, with bits of overriding
  51 so that the process does not require user interaction. C<cat-install>
  52 installs Catalyst and its dependencies using the L<CPAN> module, so that
  53 modules are installed the same way you would probably install them
  54 normally--it just makes it easier. This is a recommended solution for
  55 installation.
  56
  57 =item *
  58
  59 Chris Laco's CatInABox
  60
  61 CatInABox is a complete version of Catalyst that is installed locally on
  62 your system, so that you don't need to go through the effort of doing a
  63 full install. Simply download the tarball from
  64 L<http://handelframework.com/downloads/CatInABox.tar.gz> and unpack it
  65 on your machine.  Depending on your OS platform, either run C<start.bat>
  66 or C<start.sh> to set your bin/PERLLIB paths. This tarball contains
  67 everything needed to try out Catalyst including Catalyst itself,
  68 Template Toolkit, several Authentication modules, StackTrace, and a few
  69 other plugins.
  70
  71 A special Win32 version is available upon request that contains many
  72 more plugins and pre-compiled modules, including DBIx::Class, DBI,
  73 SQLite, and Session support. If you are interested in this version,
  74 please send e-mail to C<claco@chrislaco.com>.
  75
  76 =item *
  77
  78 Pre-Built VMWare Images
  79
  80 Under the VMWare community program, work is ongoing to develop a number
  81 of VMWare images where an entire Catalyst development environment has
  82 already been installed, complete with database engines and a full
  83 complement of Catalyst plugins.
  84
  85 =back
  86
  87 =head2 OTHER METHODS
  88
  89 In addition to the "all-in-one" approaches mentioned above, there are a
  90 variety of other installation techniques:
  91
  92 =over 4
  93
  94 =item *
  95
  96 CPAN
  97
  98 The traditional way to install Catalyst is directly from CPAN using the
  99 C<Task::Catalyst> bundle and C<Catalyst::Devel>:
 100
 101     $ perl -MCPAN -e 'install Task::Catalyst'
 102     $ perl -MCPAN -e 'install Catalyst::Devel'
 103
 104 Unless you have a particularly complete set of Perl modules already
 105 installed, be prepared for a large number of nested dependencies.
 106
 107 =item *
 108
 109 Gentoo Linux
 110
 111 For users of Gentoo, see
 112 C<http://gentoo-wiki.com/HOWTO_Catalyst_Framework> for automated
 113 installations.  In short, simply mount the portage overlay and type
 114 C<emerge catalystframework>.
 115
 116 =item *
 117
 118 FreeBSD
 119
 120 FreeBSD users can get up and running quickly by typing C<cd
 121 /usr/ports/www/p5-Catalyst-Devel && make install>, or C<portinstall
 122 p5-Catalyst-Devel> if C<portinstall> is installed on your system.
 123
 124 =item *
 125
 126 Windows ActivePerl
 127
 128 Windows users can take advantage of the PPM tool that comes with
 129 ActivePerl to jumpstart their Catalyst environment.  Directions are
 130 available at L<http://catalyst.infogami.com/install/windows>.
 131
 132 =item *
 133
 134 Subversion Repository
 135
 136 Catalyst uses Subversion for version control. To checkout the latest:
 137
 138     $ svn co http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Runtime/
 139
 140 =back
 141
 142 B<NOTE:> Although all of the above methods can be used to install a base
 143 Catalyst system, only the VMWare image is likely to have all of the
 144 plugins and modules you need to use Catalyst properly.  When you start
 145 the C<script/myapp_server.pl> development server, it will tell you about
 146 any modules that are missing.  To add them, type something along the
 147 lines of the following (C<Catalyst::Model::DBIC::Schema> is used here as
 148 a representative example):
 149
 150     # perl -MCPAN -e 'install Catalyst::Model::DBIC::Schema'
 151     ...
 152