Commit | Line | Data |
f984f5d7 |
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 | |
85d9fce6 |
101 | $ perl -MCPAN -e 'install Task::Catalyst' |
102 | $ perl -MCPAN -e 'install Catalyst::Devel' |
f984f5d7 |
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 |
252855c3 |
121 | /usr/ports/www/p5-Catalyst-Devel && make install>, or C<portinstall |
122 | p5-Catalyst-Devel> if C<portinstall> is installed on your system. |
f984f5d7 |
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 |
252855c3 |
130 | available at L<http://catalyst.infogami.com/install/windows>. |
f984f5d7 |
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 | |