3 Catalyst::Manual::Tutorial - Getting started with Catalyst
7 This document aims to get you up and running with Catalyst.
9 NOTE: THIS DOCUMENT IS STILL VERY MUCH AT AN ALPHA STAGE.
11 Please send comments, corrections and suggestions for improvements to
12 A.Ford@ford-mason.co.uk
17 The first step is to install Catalyst, and the simplest way to do this is to
18 install the Catalyst bundle from CPAN:
20 $ perl -MCPAN -e 'install Bundle::Catalyst'
22 This will retrieve Catalyst and a number of useful extensions and install them
26 =head2 Setting up your application
28 Catalyst includes a helper script, C<catalyst.pl>, that will set up a skeleton
33 created "My-App/script"
40 created "My-App/lib/My/App"
41 created "My-App/lib/My/App/M"
42 created "My-App/lib/My/App/V"
43 created "My-App/lib/My/App/C"
44 created "My-App/lib/My/App.pm"
45 created "My-App/Makefile.PL"
46 created "My-App/README"
47 created "My-App/Changes"
48 created "My-App/t/01app.t"
49 created "My-App/t/02podcoverage.t"
50 created "My-App/script/cgi.pl"
51 created "My-App/script/nph-cgi.pl"
52 created "My-App/script/fcgi.pl"
53 created "My-App/script/server.pl"
54 created "My-App/script/test.pl"
55 created "My-App/script/create.pl"
57 This creates the directory structure shown.
61 =head2 Testing out the sample application
63 You can test out your new application by running the server script that
68 [Sun Mar 20 12:31:18 2005] [catalyst] [debug] Debug messages enabled
69 [Sun Mar 20 12:31:18 2005] [catalyst] [debug] Loaded engine "Catalyst::Engine::CGI"
70 [Sun Mar 20 12:31:18 2005] [catalyst] [debug] Initialized components ""
71 [Sun Mar 20 12:31:18 2005] [catalyst] [info] My::App powered by Catalyst 4.26
72 [Sun Mar 20 12:31:18 2005] [catalyst] [debug] "My::App" defined "!default" as "CODE(0x83fd570)"
73 You can connect to your server at http://localhost:3000
75 The server is now waiting for you to make requests of it. Try using telnet to
76 manually make a simple GET request of the server (when telnet responds with
77 "Escape character is '^]'.", type "GET / HTTP/1.0" and hit return twice):
79 $ telnet localhost 3000
81 Connected to localhost.
82 Escape character is '^]'.
88 Date: Sun, 20 Mar 2005 12:31:55 GMT
91 Content-Type: text/html; charset=ISO-8859-1
93 Congratulations, My::App is on Catalyst!
94 Connection closed by foreign host.
97 More trace messages will appear in the original terminal window:
99 [Sun Mar 20 12:31:55 2005] [catalyst] [debug] ********************************
100 [Sun Mar 20 12:31:55 2005] [catalyst] [debug] * Request 1 (0.027/s) [9818]
101 [Sun Mar 20 12:31:55 2005] [catalyst] [debug] ********************************
102 [Sun Mar 20 12:31:55 2005] [catalyst] [debug] "GET" request for ""
103 [Sun Mar 20 12:31:55 2005] [catalyst] [debug] Using default action
104 [Sun Mar 20 12:31:55 2005] [catalyst] [info] Processing "!default" took 0.000033s
105 [Sun Mar 20 12:31:55 2005] [catalyst] [info] Request took 0.051399s (19.456/s)
107 The server will continue running until you interrupt it.
109 The application can also be tested from the command line using the generated
110 helper script, C<script/test.pl>.
113 =head2 Getting your application invoked
115 Catalyst applications are intended to be run from mod_perl, but can also be
116 run as CGI scripts. Running under mod_perl gives better performance, but for
117 development purposes you may want to run your application as a CGI script,
118 especially as each changes to your application code take effect under CGI
119 without having to restart the web server.
121 To run from mod_perl you need to add something like this to your Apache
125 SetHandler perl-script
129 To run as a CGI script you need a wrapper script like:
134 use lib '/path/to/MyApp/lib';
139 Catalyst outputs a complete HTTP response, which is not what is expected of a
140 CGI script. You need to configure the script as a so-called "Non-parsed
141 Headers" script for it to function properly. To do this in Apache just name
142 the script starting with C<nph->.
147 =head2 Extending the generated code
149 The generated application code looks like this:
154 use Catalyst qw/-Debug/;
156 our $VERSION = '0.01';
160 root => '/home/andrew/My-App/root',
165 my ( $self, $c ) = @_;
166 $c->res->output('Congratulations, My::App is on Catalyst!');
173 You can start extending the application by adding new actions:
177 my ( $self, $c ) = @_;
178 $c->res->output('In a new test action #1');
181 my ( $self, $c ) = @_;
182 $c->res->output('In a new test action #1');
185 my ( $self, $c ) = @_;
186 $c->res->output('Congratulations, My::App is on Catalyst!');
195 Andrew Ford, C<A.Ford@ford-mason.co.uk>
199 This program is free software, you can redistribute it and/or modify it under
200 the same terms as Perl itself.