Gentoo Wiki


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc
Wikipedia has an article on:
Catalyst Framework



Catalyst Framework is the bleeding edge in web application development. More information on the project can be found on its home page[1]. Also note that this has nothing to do with Catalyst, the Gentoo build system.

This HOWTO aims to teach you how to install Catalyst under Gentoo Linux using non-official ebuilds, as there's nothing Catalyst-related in Portage at present time.

Please note that the ebuilds are tested only on x86 and amd64 architectures. Some users reported success under ppc, but I can't guarantee for it or for other platforms (well, I do not guarantee the x86 and amd64 ones will work on your system either ;-)).


All you need is - basically - Perl. ;-) Catalyst developers recommend at least version 5.8.1: they say 5.8.0 is enough, but 5.8.1 contains several bugfixes. I recommend you get the latest stable, 5.8.8 as of now, especially if you plan to work with UTF-8 data. Said this, your Gentoo system most likely already has the latest stable version of Perl, so you should be ready to go without installing anything else.

Catalyst and its related modules depend on several ebuilds which are already in Portage. Some of them are masked. Depending on your platform, you might need to add some packages lines to your /etc/portage/package.keywords.

Creating a Portage overlay for Catalyst

Important: you can skip this step if you plan to use layman to get the Catalyst ebuilds.

Although you could use an overlay directory you already have, it is recommended that you create a specific one for Catalyst framework. This is because you might already have a dev-perl directory in your overlay, and ebuilds might clash. So, if you already have one or more overlays, just add another one in /etc/make.conf:

PORTDIR_OVERLAY="/my/other/overlay1 /usr/local/catalyst-portage"

If you don't have any, you can just add this line to /etc/make.conf:


If you are not familiar with Portage overlays, it is recommended that you read one of the may HOWTOs an tutorials you can find in the Gentoo community web sites.

Getting the Catalyst framework ebuilds

The are two ways to get the unofficial ebuilds: using the handy Layman tool (recommended way), or via anonymous Subversion (SVN).


Catalyst framework is now part of the perl-experimental overlay, which is available via layman. Layman is very easy and allows to stay up-to-date with the latest ebuilds without knowing about Subversion and other things. If you never used layman, please read the Portage Overlay Listing.

Once you have layman installed and properly configured, issue the following commands:

layman -f
layman -a perl-experimental

This will download the latest ebuilds from the SVN (Subversion) repository. When you want to check for updated, do:

layman -s perl-experimental

or (if you manage also other things with layman);

layman -s ALL

You can find more information on layman and on unofficial Portage overlays in the Portage Overlay Listing.

Note: if you switch from for example gensync to layman for easier maintenance of the catalystframework, make sure to clean the PORTAGE_OVERLAY variable in /etc/make.conf.


Subversion is another popular way to get unofficial ebuilds. If you are familiar with SVN, to grab the whole perl-experimental overlay just do:

svn checkout

when you are in the Catalyst overlay directory. If you are upgrading your ebuilds just enter the dev-perl directory and say:

svn update


Choosing the correct USE flags

Some USE flags for your /etc/make.conf are supported:

Installing Catalyst

First of all please do:

emerge --sync

Perl modules in Portage update quite often, so you need to ensure you're using the latest versions available.

You have two installation choices: catalystframework and catalystframework-most. Saying this:

emerge -av catalystframework 

will pull in everything Task::Catalyst[2] depends on plus Catalyst::Manual[3], which is what is needed for most Catalyst developers.

There are a lot of other ebuilds in the overlay, for several Catalyst, DBIx::Class and TT extensions, plus some more.

Additional modules

Besides the ones pulled in by the catalystframework meta ebuild, many other modules are available. They're not installed with the meta ebuilds as fewer people need them. Browse the contents of the repository to see which are available, and drop me (see bottom of the HOWTO for contact) a line if you wish others to be added.

To install, just emerge ebuildname.

Other resources

  1. - Catalyst Framework ebuilds and very concise description of the project. This is also the place where to ask questions.
  2. - The home of the Catalyst project.


This document is written by the maintainer of the unofficial Catalyst framework ebuilds, Michele Beltrame (LordArthas on Gentoo Forums).

Retrieved from ""

Last modified: Fri, 05 Sep 2008 22:45:00 +0000 Hits: 16,790