Cleaned up Tut files; no substantive changes

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

=head1 NAME

Catalyst::Manual::Installation - Catalyst Installation



=head1 DESCRIPTION

This section of the Catalyst tutorial looks at a number of items
required to first get going with Catalyst development.



=head1 INSTALLATION

On one hand, Catalyst gains immediate power and flexibility through is
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.
Fortunately, there are a growing number of methods that can dramatically
ease this undertaking:

=over 4

=item * 

Matt Trout's C<cat-install>

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.  Just download the script from the link above and type C<perl
cat-install>.

=item * 

Chris Laco's CatInABox

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

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

=items * 

FreeBSD

FreeBSD users can get up and running quickly by typing C<cd
/usr/ports/www/p5-Catalyst && make install>.

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

=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 complete this tutorial.  When you start
the C<script/myapp_server.pl> development server later to run your
application, 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 shell
    
    cpan shell -- CPAN exploration and modules installation (v1.87)
    ReadLine support enabled
    
    cpan> install Catalyst::Model::DBIC::Schema
    ...


=head2 OTHER ITEMS

Although Catalyst is a very flexible platform that can be used for wide
variety of applications, the bulk of Catalyst developers use it to build
web applications that set on top of a relational database.
Consequently, you will very likely need:

=over 4

=item * 

A Web Server

Although Apache is obviously an extremely popular choice, lighttpd has a
growing following.  Catalyst applications can also be run under IIS.

=item * 

A Database

Although other databases with support for Perl are certainly possible,
most Catalyst applications tend to use one of the following:

=item * 

SQLite

SQLite is a popular choice for development and testing because it does
note require that a database daemon be running or configured.  It
operates on C<.db> files that are generally located in the directory of
your Catalyst application project.  More information is available at
L<www.sqlite.org>.

=item * 

MySQL

MySQL is an extremely popular database available at L<www.mysql.com>.

=item * 

PostgreSQL

PostgreSQL is a well-respected database available at
L<http://www.postgresql.org/>.

=back

This tutorial will primarily focus on SQLite because of its simplicity;
however, modifications in the script required to support MySQL and
PostgreSQL will be presented in the Appendix.

B<Note:> One of the advantages of the MVC design patterns is that
applications become much more database independent.  As such, you will
notice that only the C<.sql> files used to initialize the database
change between database systems... the Catalyst code all remains the
same.

=back