=head1 NAME
-Catalyst::Manual::Tutorial::Debugging - Catalyst Tutorial - Part 6: Debugging
+Catalyst::Manual::Tutorial::Debugging - Catalyst Tutorial - Chapter 7: Debugging
+
=head1 OVERVIEW
-This is B<Part 6 of 9> for the Catalyst tutorial.
+This is B<Chapter 7 of 10> for the Catalyst tutorial.
L<Tutorial Overview|Catalyst::Manual::Tutorial>
=item 3
-L<Basic CRUD|Catalyst::Manual::Tutorial_BasicCRUD>
+L<More Catalyst Basics|Catalyst::Manual::Tutorial::MoreCatalystBasics>
=item 4
-L<Authentication|Catalyst::Manual::Tutorial::Authentication>
+L<Basic CRUD|Catalyst::Manual::Tutorial::BasicCRUD>
=item 5
-L<Authorization|Catalyst::Manual::Tutorial::Authorization>
+L<Authentication|Catalyst::Manual::Tutorial::Authentication>
=item 6
-B<Debugging>
+L<Authorization|Catalyst::Manual::Tutorial::Authorization>
=item 7
-L<Testing|Catalyst::Manual::Tutorial::Testing>
+B<Debugging>
=item 8
-L<AdvancedCRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
+L<Testing|Catalyst::Manual::Tutorial::Testing>
=item 9
+L<Advanced CRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
+
+=item 10
+
L<Appendices|Catalyst::Manual::Tutorial::Appendices>
=back
=head1 DESCRIPTION
-This part of the tutorial takes a brief look at the primary options
+This chapter of the tutorial takes a brief look at the primary options
available for troubleshooting Catalyst applications.
Note that when it comes to debugging and troubleshooting, there are two
Catalyst is able to easily accommodate both styles of debugging.
+
=head1 LOG STATEMENTS
-Folks in the former group can use Catalyst's C<$c-E<gt>log> facility.
-(See L<Catalyst::Log> for more detail.) For example, if you add the
-following code to a controller action method:
+Folks in the former group can use Catalyst's C<$c-E<gt>log> facility.
+(See L<Catalyst::Log|Catalyst::Log> for more detail.) For example, if
+you add the following code to a controller action method:
$c->log->info("Starting the foreach loop here");
$c->log->debug("Value of \$id is: ".$id);
Then the Catalyst development server will display your message along
-with the other debug output. To accomplish the same thing in a TTSite
-view use:
+with the other debug output. To accomplish the same thing in a TT
+template view use:
+
+ [% c.log.debug("This is a test log message") %]
- [% Catalyst.log.debug("This is a test log message") %]
+As with many other logging facilities, you a method is defined for
+each of the following "logging levels" (in increasing order of
+severity/importance):
+
+ $c->log->debug
+ $c->log->info
+ $c->log->warn
+ $c->log->error
+ $c->log->fatal
You can also use L<Data::Dumper|Data::Dumper> in both Catalyst code
-(C<use Data::Dumper; $c-E<gt>log-E<gt>debug("$var is: ".Dumper($var));)>)
+(C<use Data::Dumper; $c-E<gt>log-E<gt>debug("\$var is: ".Dumper($var));)>)
and TT templates (C<[% Dumper.dump(book) %]>.
+
=head1 RUNNING CATALYST UNDER THE PERL DEBUGGER
Members of the interactive-debugger fan club will also be at home with
you can obviously indent them if you prefer):
sub list : Local {
- # Retrieve the usual perl OO '$self' for this object. $c is the Catalyst
+ # Retrieve the usual Perl OO '$self' for this object. $c is the Catalyst
# 'Context' that's used to 'glue together' the various components
# that make up the application
my ($self, $c) = @_;
# Retrieve all of the book records as book model objects and store in the
# stash where they can be accessed by the TT template
- $c->stash->{books} = [$c->model('MyAppDB::Book')->all];
+ $c->stash->{books} = [$c->model('DB::Book')->all];
# Set the TT template to use. You will almost always want to do this
# in your action methods.
This causes the Perl Debugger to enter "single step mode" when this command is
encountered (it has no effect when Perl is run without the C<-d> flag).
+B<NOTE:> The C<DB> here is the Perl Debugger, not the DB model.
+
+If you haven't done it already, enable SQL logging as before:
+
+ $ export DBIC_TRACE=1
+
To now run the Catalyst development server under the Perl debugger, simply
prepend C<perl -d> to the front of C<script/myapp_server.pl>:
$ perl -d script/myapp_server.pl
- Loading DB routines from perl5db.pl version 1.27
+ Loading DB routines from perl5db.pl version 1.3
Editor support available.
Enter h or `h h' for help, or `man perldebug' for more help.
- main::(script/myapp_server.pl:14): my $debug = 0;
+ main::(script/myapp_server.pl:16): my $debug = 0;
DB<1>
C<MyApp::Controller::list> method, the console session running the
development server will drop to the Perl debugger prompt:
- MyApp::Controller::Books::list(/home/me/MyApp/script/../lib/MyApp/Controller/Books.pm:40):
- 40: $c->stash->{books} = [$c->model('MyAppDB::Book')->all];
+ MyApp::Controller::Books::list(/home/me/MyApp/script/../lib/MyApp/Controller/Books.pm:48):
+ 48: $c->stash->{books} = [$c->model('DB::Book')->all];
DB<1>
C<single-step> into methods/subroutines):
DB<1> n
- SELECT me.id, me.authors, me.title, me.rating FROM books me:
- MyApp::Controller::Books::list(/home/me/MyApp/script/../lib/MyApp/Controller/Books.pm:44):
- 44: $c->stash->{template} = 'books/list.tt2';
+ SELECT me.id, me.title, me.rating, me.created, me.updated FROM book me:
+ MyApp::Controller::Books::list(/home/me/MyApp/script/../lib/MyApp/Controller/Books.pm:53):
+ 53: $c->stash->{template} = 'books/list.tt2';
DB<1>
Next, list the methods available on our C<Book> model:
- DB<1> m $c->model('MyAppDB::Book')
+ DB<1> m $c->model('DB::Book')
()
(0+
(bool
- MODIFY_CODE_ATTRIBUTES
- _attr_cache
- _collapse_result
- _construct_object
- _count
- _result_class_accessor
- _result_source_accessor
- all
- carp
+ __result_class_accessor
+ __source_handle_accessor
+ _add_alias
+ __bool
+ _build_unique_query
+ _calculate_score
+ _collapse_cond
<lines removed for brevity>
DB<2>
We can also play with the model directly:
- DB<2> x ($c->model('MyAppDB::Book')->all)[1]->title
- SELECT me.id, me.title, me.rating FROM books me:
+ DB<2> x ($c->model('DB::Book')->all)[1]->title
+ SELECT me.id, me.title, me.rating, me.created, me.updated FROM book me:
0 'TCP/IP Illustrated, Volume 1'
This uses the Perl debugger C<x> command to display the title of a book.
DB<3> x 4 $c->stash->{books}
0 ARRAY(0xa8f3b7c)
- 0 MyApp::Model::MyAppDB::Book=HASH(0xb8e702c)
+ 0 MyApp::Model::DB::Book=HASH(0xb8e702c)
'_column_data' => HASH(0xb8e5e2c)
+ 'created' => '2009-05-08 10:19:46'
'id' => 1
'rating' => 5
'title' => 'CCSP SNRS Exam Certification Guide'
+ 'updated' => '2009-05-08 10:19:46'
'_in_storage' => 1
<lines removed for brevity>
Finally, press C<Ctrl+C> to break out of the development server.
Because we are running inside the Perl debugger, you will drop to the
-debugger prompt. Press C<q> to exit the debugger and return to your OS
+debugger prompt.
+
+ ^CCatalyst::Engine::HTTP::run(/usr/local/share/perl/5.10.0/Catalyst/Engine/HTTP.pm:260):
+ 260: while ( accept( Remote, $daemon ) ) {
+
+ DB<4>
+
+Finally, press C<q> to exit the debugger and return to your OS
shell prompt:
DB<4> q
$
For more information on using the Perl debugger, please see C<perldebug>
-and C<perldebtut>. You can also type C<h> or C<h h> at the debugger
-prompt to view the built-in help screens.
+and C<perldebtut>. For those daring souls out there, you can dive down
+even deeper into the magical depths of this fine debugger by checking
+out C<perldebguts>.
+You can also type C<h> or C<h h> at the debugger prompt to view the
+built-in help screens.
+
+For an excellent book covering all aspects of the Perl debugger, we highly
+recommend reading 'Pro Perl Debugging' by Richard Foley.
+
+Oh yeah, before you forget, be sure to remove the C<DB::single=1> line you
+added above in C<lib/MyApp/Controller/Books.pm>.
=head1 DEBUGGING MODULES FROM CPAN
mkdir -p lib/Module; cp `perldoc -l Module::Name` lib/Module/
+Note: If you are following along in Debian 5 or Ubuntu, you will
+need to install the C<perl-doc> package to use the C<perldoc> command.
+Use C<sudo aptitude install perl-doc> to do that.
+
For example, you could make a copy of
L<Catalyst::Plugin::Authentication|Catalyst::Plugin::Authentication>
with the following command:
mkdir -p lib/Catalyst/Plugin; cp \
`perldoc -l Catalyst::Plugin::Authentication` lib/Catalyst/Plugin
+You can then use the local copy inside your project to place logging
+messages and/or breakpoints for further study of that module.
+
B<Note:> Matt has also suggested the following tips for Perl
debugging:
Check the version of an installed module:
- perl -MModule::Name -e 'print $Module::Name::VERSION;'
+ perl -ME<lt>mod_nameE<gt> -e '"print $E<lt>mod_nameE<gt>::VERSION\n"'
For example:
'print $Catalyst::Plugin::Authentication::VERSION;'
0.07
+and if you are using bash aliases:
+
+ alias pmver="perl -le '\$m = shift; eval qq(require \$m) \
+ or die qq(module \"\$m\" is not installed\\n); \
+ print \$m->VERSION'"
+
=item *
Check if a modules contains a given method:
For example:
$ perl -MCatalyst::Plugin::Authentication -e \
- 'print Catalyst::Plugin::Authentication->can("prepare");'
+ 'print Catalyst::Plugin::Authentication->can("user");'
CODE(0x9c8db2c)
If the method exists, the Perl C<can> method returns a coderef.
=back
+=head1 TT DEBUGGING
+
+If you run into issues during the rendering of your template, it might
+be helpful to enable TT C<DEBUG> options. You can do this in a Catalyst
+environment by adding a C<DEBUG> line to the C<__PACKAGE__->config>
+declaration in C<lib/MyApp/View/TT.pm>:
+
+ __PACKAGE__->config({
+ TEMPLATE_EXTENSION => '.tt2',
+ DEBUG => 'undef',
+ });
+
+There are a variety of options you can use, such as 'undef', 'all',
+'service', 'context', 'parser' and 'provider'. See
+L<Template::Constants|Template::Constants> for more information
+(remove the C<DEBUG_> portion of the name shown in the TT docs and
+convert to lower case for use inside Catalyst).
+
+B<NOTE:> B<Please be sure to disable TT debug options before continuing
+with the tutorial> (especially the 'undef' option -- leaving this
+enabled will conflict with several of the conventions used by this
+tutorial to leave some variables undefined on purpose).
+
+Happy debugging.
+
=head1 AUTHOR
Kennedy Clark, C<hkclark@gmail.com>
Please report any errors, issues or suggestions to the author. The
most recent version of the Catalyst Tutorial can be found at
-L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Manual/lib/Catalyst/Manual/Tutorial/>.
+L<http://dev.catalyst.perl.org/repos/Catalyst/Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/>.
-Copyright 2006, Kennedy Clark, under Creative Commons License
-(L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).
+Copyright 2006-2008, Kennedy Clark, under Creative Commons License
+(L<http://creativecommons.org/licenses/by-sa/3.0/us/>).