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