[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 Trouts 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 Appendix X.

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
Commit	Line	Data
4d583dd8	1	=head1 NAME
	2
	3	Catalyst::Manual::Installation Catalyst Installation
	4
	5
	6
	7	=head1 DESCRIPTION
	8
	9	This section of the Catalyst tutorial looks at a number of items required to first get going with Catalyst development.
	10
	11
	12
	13	=head1 INSTALLATION
	14
	15	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:
	16
	17	=over 4
	18
	19	=item *
	20
	21	Matt Trouts C<cat-install>
	22
	23	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>.
	24
	25	=item *
	26
	27	Chris Laco's CatInABox
	28
	29	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>.
	30
	31	=item *
	32
	33	Pre-Built VMWare Images
	34
	35	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.
	36
	37	=back
	38
	39
	40	=head2 OTHER METHODS
	41
	42	In addition to the "all-in-one" approaches mentioned above, there are a variety of other installation techniques:
	43
	44	=over 4
	45
	46	=item *
	47
	48	CPAN
	49
	50	The traditional way to install Catalyst is directly from CPAN using C<Task::Catalyst> bundle:
	51
	52	$ perl MCPAN e 'install Task::Catalyst'
	53
	54	Unless you have a particularly complete set of Perl modules already installed, be prepared for a large number of nested dependencies.
	55
	56	=item *
	57
	58	Gentoo Linux
	59
	60	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>.
	61
	62	=items *
	63
	64	FreeBSD
65
66	FreeBSD users can get up and running quickly by typing C<cd /usr/ports/www/p5-Catalyst && make install>.
67
68	=item *
69
70	Windows ActivePerl
71
72	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>.
73
74	=back
75
76	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):
77
78	# perl -MCPAN -e shell
79
80	cpan shell -- CPAN exploration and modules installation (v1.87)
81	ReadLine support enabled
82
83	cpan> install Catalyst::Model::DBIC::Schema
84	...
85
86
87	=head2 OTHER ITEMS
88
89	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:
90
91	=over 4
92
93	=item *
94
95	A Web Server
96
97	Although Apache is obviously an extremely popular choice, lighttpd has a growing following. Catalyst applications can also be run under IIS.
98
99	=item *
100
101	A Database
102
103	Although other databases with support for Perl are certainly possible, most Catalyst applications tend to use one of the following:
104
105	=item *
106
107	SQLite
108
109	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>.
110
111	=item *
112
113	MySQL
114
115	MySQL is an extremely popular database available at L<www.mysql.com>.
116
117	=item *
118
119	PostgreSQL
120
121	PostgreSQL is a well-respected database available at L<http://www.postgresql.org/>.
122
123	=back
124
125	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 Appendix X.
126
127	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.
128
129	=back
130
131