[catagits/Catalyst-Runtime.git] / lib / Catalyst / Manual / Installation.pod

head1 NAME

Catalyst::Manual::Installation - Catalyst Installation

=head1 DESCRIPTION

How to install Catalyst.

=head1 INSTALLATION

On one hand, Catalyst gains immediate power and flexibility
through its use of CPAN (the Comprehensive Perl Archive
Network, an enormous global repository containing over 10,000
free modules).  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 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:

=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.

=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
C<Task::Catalyst> bundle:

	$ perl -MCPAN -e 'install Task::Catalyst'

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/

=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, and to complete the tutorial.  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'
    ...
Commit	Line	Data
ca993681	1	head1 NAME
4d583dd8	2
64ccd8a8	3	Catalyst::Manual::Installation - Catalyst Installation
4d583dd8	4
4d583dd8	5	=head1 DESCRIPTION
4d583dd8	6
ca993681	7	How to install Catalyst.
4d583dd8	8
ca993681	9	=head1 INSTALLATION
4d583dd8	10
ca993681	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.
4d583dd8	18
ca993681	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.
4d583dd8	23
ca993681	24	Fortunately, there are a growing number of methods that can
ca993681	25	dramatically ease this undertaking:
4d583dd8	26
	27	=over 4
	28
	29	=item *
	30
da62e298	31	Matt Trout's C<cat-install> script
da62e298	32
9b0ec7a1	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.
4d583dd8	39
	40	=item *
	41
	42	Chris Laco's CatInABox
	43
9b0ec7a1	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
64ccd8a8	47	L<http://handelframework.com/downloads/CatInABox.tar.gz> and unpack it
64ccd8a8	48	on your machine. Depending on your OS platform, either run C<start.bat>
9b0ec7a1	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>.
4d583dd8	58
	59	=item *
	60
	61	Pre-Built VMWare Images
	62
64ccd8a8	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.
4d583dd8	67
	68	=back
	69
4d583dd8	70	=head2 OTHER METHODS
4d583dd8	71
64ccd8a8	72	In addition to the "all-in-one" approaches mentioned above, there are a
64ccd8a8	73	variety of other installation techniques:
4d583dd8	74
	75	=over 4
	76
	77	=item *
	78
	79	CPAN
	80
64ccd8a8	81	The traditional way to install Catalyst is directly from CPAN using
64ccd8a8	82	C<Task::Catalyst> bundle:
4d583dd8	83
64ccd8a8	84	$ perl -MCPAN -e 'install Task::Catalyst'
4d583dd8	85
64ccd8a8	86	Unless you have a particularly complete set of Perl modules already
64ccd8a8	87	installed, be prepared for a large number of nested dependencies.
4d583dd8	88
	89	=item *
	90
	91	Gentoo Linux
	92
64ccd8a8	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>.
4d583dd8	97
ca993681	98	=item *
4d583dd8	99
	100	FreeBSD
	101
64ccd8a8	102	FreeBSD users can get up and running quickly by typing C<cd
ca993681	103	/usr/ports/www/p5-Catalyst && make install>, or C<portinstall
ca993681	104	p5-Catalyst> if C<portinstall> is installed on your system.
4d583dd8	105
	106	=item *
	107
	108	Windows ActivePerl
	109
64ccd8a8	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>.
4d583dd8	113
ca993681	114	=item *
4d583dd8	115
ca993681	116	Subversion Repository
4d583dd8	117
ca993681	118	Catalyst uses Subversion for version control. To checkout the latest:
4d583dd8	119
ca993681	120	$ svn co http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst/
4d583dd8	121
	122	=back
	123
ca993681	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	...
4d583dd8	136