svn co http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/ CatalystTutorial
-This will download the most recent tarball for each chapter of the
-tutorial into the CatalystTutorial directory on your machine.
+This will download the most recent code for each chapter of the
+tutorial into the CatalystTutorial directory on your machine.
B<These reference implementations are provided so that when you follow
the tutorial, you can use the code from the subversion repository to
for some of the key modules), so B<if you think you might be running
into an issue related to versions> (for example, a module changed its
behavior in a newer version or a bug was introduced), B<it might be
-worth giving Debian 5 a try>. See the "CATALYST INSTALLATION"
-section below for more information.
+worth giving Debian 5 a try>.
-If you're reading this manual online, you can download the example
+If you plan to follow along with Debian 5, you can jump down to the
+"Debian" section under L</"CATALYST INSTALLATION"> below and it will walk you
+though the setup of a fully functional Catalyst environment. If you
+would prefer to install directly from CPAN, you can download the example
program and all the necessary dependencies to your local machine by
-installing the C<Task::Catalyst::Tutorial> distribution from CPAN:
+installing the C<Task::Catalyst::Tutorial> distribution:
cpan Task::Catalyst::Tutorial
=item *
The use of SQLite as a database (with code also provided for MySQL and
-PostgreSQL).
+PostgreSQL). (Note: Because we make use of the DBIx::Class Object
+Relational Mapping [ORM] layer, out our application will be database
+agnostic and can easily be used by any of the databases supported
+by DBIx::Class.)
=item *
-The use of L<HTML::FormFu|HTML::FormFu> for automated form processing
-and validation.
+The use of L<HTML::FormFu|HTML::FormFu> or L<HTML::FormHandler|HTML::FormHandler>
+for automated form processing and validation.
=back
L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/>.
+=head1 QUICK START
+
+For those who want to get going quickly, here is a short "cookbook-style
+recipe" to quickly get you up and running. Although there are many
+different ways to get a Catalyst environment going, this tutorial has
+been written with and tested against Debian 5 Live CD, using the steps
+in this Quick Start.
+
+If you want, you can follow the directions in this section and then jump
+right to L<Chapter 2|Catalyst::Manual::Tutorial::02_CatalystBasics> of
+the tutorial. However, it would be a good idea to come back and read the
+sections below the Quick Start when you have time. Or, continue reading
+those other sections for suggestions if you do not wish to use the
+Debian 5 Live CD.
+
+
+=over 4
+
+=item 1
+
+Download the C<debian-live-503-i386-rescue.iso> image from
+L<http://cdimage.debian.org/cdimage/release/current-live/i386/iso-cd/>.
+
+=item 2
+
+Boot this disk, either in a physical machine, or possibly some sort
+of virtual machine (can be a very handy way to practice).
+
+=item 3
+
+Select "C<Live>" from the initial boot menu.
+
+=item 4
+
+At the "C<user@debian:~$>" prompt, type:
+
+ sudo aptitude -y install subversion
+
+=item 5
+
+If you want to be able to remotely SSH to this system, set a
+password for root:
+
+ sudo passwd
+ ...
+
+=item 6
+
+Add the "unstable" Debian package repository:
+
+ sudo vi /etc/apt/sources.list
+
+Add the following line to the bottom of this file:
+
+ deb http://ftp.us.debian.org/debian/ unstable main
+
+=item 7
+
+Install Catalyst and related libraries:
+
+ sudo aptitude update
+ sudo aptitude -y install sqlite3 libdbd-sqlite3-perl libcatalyst-perl \
+ libcatalyst-modules-perl libdbix-class-timestamp-perl \
+ libdatetime-format-sqlite-perl libconfig-general-perl \
+ libhtml-formfu-model-dbic-perl libterm-readline-perl-perl \
+ libdbix-class-encodedcolumn-perl libperl6-junction-perl \
+ libtest-pod-perl
+ sudo aptitude clean
+
+=item 8
+
+Test example code:
+
+ mkdir test
+ cd test
+ svn co http://dev.catalystframework.org/repos/Catalyst/trunk/examples/Tutorial/MyApp_Chapter8
+ cd MyApp_Chapter8/MyApp
+ CATALYST_DEBUG=0 prove -wl t
+ cd
+
+=back
+
+
=head1 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL
This tutorial was built using the following resources. Please note that
you may need to make adjustments for different environments and
-versions:
+versions (note that trailing zeros in version numbers are not
+significant and may get dropped with techniques for viewing them;
+for example, Catalyst v5.80020 might show up as 5.8002):
=over 4
=item *
-Catalyst v5.80004
+Catalyst v5.80020 (note: may show up as '5.8002' without the trailing zero)
=item *
-Catalyst::Devel v1.10
+Catalyst::Devel v1.26
=item *
-DBIx::Class v0.08102
+DBIx::Class v0.08115
+
+=item *
+
+Catalyst::Model::DBIC::Schema v0.40
=item *
Template Toolkit v2.20
+
=item *
Catalyst Plugins
=item *
-Catalyst::Plugin::Authentication -- v0.10011
+Catalyst::Plugin::Authentication -- v0.10016
=item *
-Catalyst::Plugin::Authorization::Roles -- v0.07
+Catalyst::Plugin::Authorization::Roles -- v0.08
=item *
-Catalyst::Plugin::ConfigLoader -- v0.22
+Catalyst::Plugin::ConfigLoader -- v0.27
=item *
-Catalyst::Plugin::Session -- v0.20
+Catalyst::Plugin::Session -- v0.29
=item *
-Catalyst::Plugin::Session::State::Cookie -- v0.10
+Catalyst::Plugin::Session::State::Cookie -- v0.17
=item *
-Catalyst::Plugin::Session::Store::FastMmap -- v0.07
+Catalyst::Plugin::Session::Store::FastMmap -- v0.13
=item *
-Catalyst::Plugin::StackTrace -- v0.09
+Catalyst::Plugin::StackTrace -- v0.11
=item *
-Catalyst::Plugin::Static::Simple -- v0.21
+Catalyst::Plugin::Static::Simple -- v0.29
=back
+=item *
+
+HTML::FormFu -- v0.06001
+
=item *
B<NOTE:> You can check the versions you have installed with the
perl -M<_mod_name_> -e '"print $<_mod_name_>::VERSION\n"'
For example:
- perl -MCatalyst::Plugin::StackTrace -e 'print "$Catalyst::Plugin::StackTrace::VERSION\n"'
-Since the web browser is being used on the same box where Perl and the
-Catalyst development server is running, the URL of
-C<http://localhost:3000> will be used (the Catalyst development server
-defaults to port 3000). If you are running Perl on a different box than
-where your web browser is located (or using a different port number via
-the C<-p> I<port_number> option to the development server), then you
-will need to update the URL you use accordingly.
+ perl -MCatalyst -e 'print "$Catalyst::VERSION\n";'
+
+or:
+
+ perl -MCatalyst::Devel -e 'print "$Catalyst::Devel::VERSION\n";'
=item *
-Depending on the web browser you are using, you might need to hit
-C<Shift+Reload> or C<Ctrl+Reload> to pull a fresh page when testing
-your application at various points (see
-L<http://en.wikipedia.org/wiki/Bypass_your_cache> for a comprehensive
+This tutorial will assume that the web browser is located on the same
+system where the Catalyst development server is running, and
+therefore use a URL of C<http://localhost:3000> (the Catalyst
+development server defaults to port 3000). If you are running Perl on
+a different box than where your web browser is located (or using a
+different port number via the C<-p> I<port_number> option to the
+development server), then you will need to update the URL you use
+accordingly.
+
+Please Note: Depending on the web browser you are using, you might
+need to hit C<Shift+Reload> or C<Ctrl+Reload> to pull a fresh page
+when testing your application at various points (see
+L<http://en.wikipedia.org/wiki/Bypass_your_cache> for a comprehensive
list of options for each browser). Also, the C<-k> keepalive option
to the development server can be necessary with some browsers
(especially Internet Explorer).
=item *
Download one of the ISO files from
-L<http://cdimage.debian.org/cdimage/release/current-live/i386/iso-cd/>.
+L<http://cdimage.debian.org/cdimage/release/current-live/i386/iso-cd/>
+(the current version at the time this was written was 5.0.3).
You can pick any one of the live CD variations will work, but
you may wish to consider the following points:
=item *
-"C<debian-live-500-i386-rescue.iso>" is probably the best all-around
+"C<debian-live-503-i386-rescue.iso>" is probably the best all-around
option for most people because it includes many extra tools such as
the GCC compiler, therefore saving RAM (every package you need to
install when running from live CD consumes memory because RAM disk is
=item *
-"C<debian-live-500-i386-standard.iso>" is a great option because of
+"C<debian-live-503-i386-standard.iso>" is a great option because of
its compact size, but you will probably need approximately 1 GB of RAM
in the computer where you will run the tutorial. Because the
"standard" live CD comes with with a minimal set of tools, we will
=item *
-Once the system has booted to a "C<user@debian:~$>" prompt, enter the
-following command to add the more current "unstable" package
-repository:
+Once the system has booted to a "C<user@debian:~$>" prompt, first
+install the Subversion client in case you want to check out the
+completed chapter example code:
+
+ sudo aptitude -y install subversion
+
+If you want to be able to remotely SSH to this system, set a
+password for root:
+
+ sudo passwd
+ ...
+
+Then enter the following command to add the more current "unstable"
+package repository so we get the latest versions of Catalyst and
+related packages:
sudo vi /etc/apt/sources.list
sudo aptitude update
sudo aptitude -y install sqlite3 libdbd-sqlite3-perl libcatalyst-perl \
- libcatalyst-modules-perl libconfig-general-perl libsql-translator-perl \
- libdatetime-perl libdatetime-format-mysql-perl libio-all-perl \
- libperl6-junction-perl libmoosex-emulate-class-accessor-fast-perl \
- libdbix-class-timestamp-perl
-
-Let it install (normally about a 30-second operaton) and you are done.
-(Note the '\' above. Depending on your environment, you might be able
-to cut and paste the text as shown or need to remove the '\'
+ libcatalyst-modules-perl libdbix-class-timestamp-perl \
+ libdatetime-format-sqlite-perl libconfig-general-perl \
+ libhtml-formfu-model-dbic-perl libterm-readline-perl-perl \
+ libdbix-class-encodedcolumn-perl libperl6-junction-perl \
+ libtest-pod-perl
+
+Let it install (normally about a 30 to 90-second operaton) and you are
+done. (Note the '\' above. Depending on your environment, you might
+be able to cut and paste the text as shown or need to remove the '\'
characters to that the command is all on a single line.)
If you are using an image other than the "rescue" ISO, you will also need
=item *
If you are installing modules from CPAN, you can free up some space
-with "C<rm -rf /root/.cpan/*>".
+with "C<rm -rf /root/.cpan/*>" (change "/root/" in the previous
+command to match your home directory or the location where CPAN
+has been configured to perform build operations).
=item *
B<NOTE:> You can run the test cases for the final code through Chapter 8
with the following commands:
- sudo cpan Catalyst::Model::DBIC::Schema Time::Warp DBICx::TestDatabase \
- DBIx::Class::DynamicDefault DBIx::Class::EncodedColumn
- wget http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/MyApp_Chapter8.tgz
- tar zxvf MyApp_Chapter8.tgz
- cd MyApp
- CATALYST_DEBUG=0 prove --lib lib t
+ svn co http://dev.catalystframework.org/repos/Catalyst/trunk/examples/Tutorial/MyApp_Chapter8
+ cd MyApp_Chapter8/MyApp
+ CATALYST_DEBUG=0 prove -wl t
-If you wish to include the L<HTML::FormFu|HTML::FormFu> section in
-your tests, substitute C<MyApp_Chapter9_FormFu.tgz> for
-C<MyApp_Chapter8.tgz> in the URL above. However, you will also need to
-run the following additional commands:
+If you wish to include the L<HTML::FormFu|HTML::FormFu> section in your tests,
+substitute C<MyApp_Chapter9_FormFu> for C<MyApp_Chapter8> in the URL
+above (don't forget to "cd" out of the Ch8 directory if you ran the code above).
- sudo aptitude -y install libhtml-formfu-perl libmoose-perl \
- libregexp-assemble-perl libhtml-formfu-model-dbic-perl
- sudo aptitude clean
- sudo cpan Catalyst::Component::InstancePerContext Catalyst::Controller::HTML::FormFu
+ svn co http://dev.catalystframework.org/repos/Catalyst/trunk/examples/Tutorial/MyApp_Chapter9_FormFu
+ cd MyApp_Chapter9_FormFu/MyApp
+ CATALYST_DEBUG=0 prove -wl t
You can also fire up the application under the development server that is conveniently
built in to Catalyst. Just issue this command from the C<MyApp> directory where you
most recent version of the Catalyst Tutorial can be found at
L<http://dev.catalyst.perl.org/repos/Catalyst/Catalyst-Manual/5.80/trunk/lib/Catalyst/Manual/Tutorial/>.
-Copyright 2006-2008, Kennedy Clark, under Creative Commons License
+Copyright 2006-2010, Kennedy Clark, under Creative Commons License
(L<http://creativecommons.org/licenses/by-sa/3.0/us/>).
projects / catagits/Catalyst-Manual.git / blobdiff