Installing Catalyst

What does it actually mean "to install Catalyst"?

If you want to install the Catalyst Framework in order to be able to run and/or develop a Catalyst based web application you need:

1.	perl 5.8.6 or higher	you either have one in you OS (most UNIX systems) or you have to install it (like on MS Windows)
2.	Catalyst::Runtime Catalyst::Devel	you need to install perl modules Catalyst::Runtime (sometimes called Catalyst Core) + Catalyst::Devel (you need this for development of Catalyst applications) + bunch of its dependencies (where bunch means another more than 100 perl modules)
3.	some additional perl modules	on top of the previous point you will definitely need some additional modules from Catalyst::* or CatalystX::* namespace (see recommended plugins)

Catalyst version

If somebody is talking about Catalyst version she/he means the version of Catalyst::Runtime module.

As of June 2009, Catalyst 5.8 has just been released and based on the release schedule of Catalyst 5.7, it will get frequent bugfix and performance releases.

current stable version	http://search.cpan.org/dist/Catalyst-Runtime
latest development version	SVN repository: http://dev.catalystframework.org/repos/Catalyst/Catalyst-Runtime/5.80/trunk/
	Web interface to SVN repository: http://dev.catalystframework.org/svnweb/Catalyst/log/

To find out what Catalyst version you have:

perl -MCatalyst::Runtime -e 'print Catalyst::Runtime->VERSION'

There are more ways to install Catalyst

Before we start the installation of Catalyst::* modules we need a working perl 5.8.1 or higher.

• on most UNIX platform or Mac OS X you either have perl pre-installed or you can easily get it (on older systems do not forget to check the perl version).
• on MS Windows you can choose Strawberry Perl or Active State. Strawberry is slightly preferred as it supports CPAN which makes things much much easier.

To install all required perl modules you can choose one of these approaches:

• install from CPAN - the main advantage is that CPAN is the primary release point so you can get the latest version of Catalyst and all related modules
• install via SW packages - this options means using popular *.deb/*.rpm/... packages used for SW distribution. The main advantage is better version control and ability to install/uninstall the same modules later.
• or you can decide to choose ready to use BinaryBuilds.

NOTE: Despite the fact that nearly all Catalyst::* modules are written in pure perl there are many other modules in Catalyst dependency chain that are implemented in C/XS thus are platform dependant (and for installation from CPAN you will need C/C++ compiler).

Installation from CPAN

As mentioned above the CPAN is the primary release point for Catalyst and all related modules.

If precompiled packages (discussed later) aren't available, or if they are of an older version than the version of Catalyst you want to install, you can go the source installation route.

Before installation

Make sure your OS has a C compiler in the path (cc, gcc, make etc.).

Before installing Catalyst, make sure you have configured cpan (just run cpan). You may also want to update your cpan:

cpan
    install CPAN
    reload cpan

Installation - basic Catalyst modules

Use cpan utility and simply run:

cpan Catalyst::Runtime Catalyst::Devel

and answer yes to all prompts (there will be a lot of them). To force an automatic "yes" to prompts, run

PERL_MM_USE_DEFAULT=1 cpan Catalyst::Runtime Catalyst::Devel

Installation - additional Catalyst related modules

If you just got a Catalyst Application and want to run it, it is very likely that Catalyst::Runtime will not be enough. You will probably need to install additional dependencies required by your application.

Following the instructions below will install the basic set of Catalyst modules, on top of which you can use CPAN to install the other modules you need for authentication, authorization, models and so on, typically by adding them as dependencies to your project's Makefile.PL and running:

make installdeps

Upgrading

To upgrade your catalyst framework (both Runtime and Devel) to latest release simply run:

cpan Catalyst::Runtime Catalyst::Devel

Notes: Debian/Ubuntu

To get all required dev tools (gcc, make, ...) run:

apt-get install build-essential

Notes: Fedora/RedHat

To get all required dev tools (gcc, make, ...) run:

yum groupinstall "Development Tools"

Notes: MS Windows

To install from CPAN you have to choose Strawberry Perl that fully supports CPAN and comes with all required dev tools (gcc, make, ...) pre-installed.

What strawberry perl version to choose?

It is recommended to choose version 5.8.9 or 5.10.1 or 5.12.0 (or higher).

The installation

After installing the perl you need to just run the following commands from command prompt:

set PERL_MM_USE_DEFAULT=1
perl -MCPAN -e "notest('install', 'HTTP::Server::Simple', 'WWW::Mechanize');"
cpan Catalyst::Runtime Catalyst::Devel

NOTE: HTTP::Server::Simple and WWW::Mechanize have to be installed with "notest" as some of the tests hang up.

Notes: Mac OS X

If you have OS X 10.3 or higher you should be OK with pre-installed perl version.

One of the dependencies on OS X is Mac::Carbon. That's pre-installed in the system provided perl, but will be pulled in by cpan if you use your own perl. Some of it's tests are broken on Leopard, so you may need to force install it before following the above directions.

Notes: Solaris 10

Installing from CPAN on Solaris 10, with the OS Perl, works if you update CPAN first.

Installation from packages

Debian, Ubuntu (*.deb)

Some operating systems such as Debian or Ubuntu may already have precompiled Catalyst packages. See http://packages.ubuntu.com/search?searchon=names&keywords=catalyst or:

apt-cache search catalyst

To install on Ubuntu fire up System > Administration > Synaptic Package Manager, search for "catalyst", then install:

• libcatalyst-perl - The Elegant MVC Web Application Framework

You may also want to install:

• libcatalyst-engine-apache-perl - Base class for Apache 1.x and 2.x Catalyst engines
• libcatalyst-model-cdbi-perl - CDBI Model Class for Catalyst
• libcatalyst-modules-extra-perl - Extra modules for Catalyst
• libcatalyst-modules-perl - Modules for Catalyst
• libcatalyst-plugin-formvalidator-perl - FormValidator for Catalyst
• libcatalyst-plugin-session-fastmmap-perl - FastMmap sessions for Catalyst
• libcatalyst-view-tt-perl - Template View Class for Catalyst
• libhtml-prototype-perl - Generate HTML and Javascript for the Prototype library

Fedora, RedHat, Mandriva (*.rpm)

Fedora has a number of Catalyst packages. For more details, see http://fedoraproject.org/wiki/Catalyst.

Try to search for perl-catalyst-runtime and/or perl-catalyst-devel in the following RPM repositories:

• Fedora http://rpmfind.net/
• Mandriva, RedHat http://rpm.pbone.net/

MS Windows - ActiveState perl (*.ppm)

On Windows, you can find Catalyst packages in the http://ppm.tcool.org repository. If the 5.10 repository is not ready at the time you read this, use http://ppm.tcool.org/archives510/

If you're stuck with ActivePerl, and if you want to test the Catalyst installation (make test), install nmake 9 from VC-Express++. The older version of nmake (1.5) can't handle long command lines, and one particular test expands to a lot of .t files passed to nmake.

Then you can install Catalyst::Runtime from the Command Prompt:

ppm install http://ppm.tcool.org/archives510/Catalyst-Runtime.ppd

Next, Install the following dependencies:

ppm install http://ppm.tcool.org/archives510/Catalyst-Plugin-ConfigLoader.ppd
ppm install http://ppm.tcool.org/archives510/Catalyst-Action-RenderView.ppd
ppm install http://ppm.tcool.org/archives510/Catalyst-Plugin-Static-Simple.ppd

Finally, install Catalyst::Devel:

ppm install http://ppm.tcool.org/archives510/Catalyst-Devel.ppd

If you encounter other dependencies, install them in a similar fashion from http://ppm.tcool.org/archives510/.

Alternative installation

For a quick but somewhat deprecated installation, download and execute mst's Shadowcat installer:

perl cat-install

This is a Perl script that interacts with CPAN to install Catalyst and its dependencies, with very little input from you. It requires perl 5.8.1+, a make utility and a compiler, a configured CPAN.pm and Module::Build installed.

Installation without root

With an account that you are unable to get full access to you can use Local::Lib

Full instructions are on the Advent Calendar at http://www.catalystframework.org/calendar/2007/8.

Troubleshooting

If you run into problems with installation, please verify that your environment is configured correctly. Strange things can happen if CPAN doesn't know where to find gcc, for example.

Help

The Catalyst mailing list or IRC channel (#catalyst on irc.perl.org) are resources to turn to if you are having difficulty getting everything installed.