X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FTutorial%2FDebugging.pod;h=fe78ff2752663562b30b866d245a0b8ba8b9bc92;hp=6a958d3dfa32b971748e7327605081afb621c45e;hb=3b1fa91be1d89d2297aa9e8e83462344d9cd9820;hpb=5e6026272f809951ac22fae43b73d2c1dc79c7fc

diff --git a/lib/Catalyst/Manual/Tutorial/Debugging.pod b/lib/Catalyst/Manual/Tutorial/Debugging.pod
index 6a958d3..fe78ff2 100644
--- a/lib/Catalyst/Manual/Tutorial/Debugging.pod
+++ b/lib/Catalyst/Manual/Tutorial/Debugging.pod
@@ -1,10 +1,11 @@
 =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>
 
@@ -20,30 +21,34 @@ L<Catalyst Basics|Catalyst::Manual::Tutorial::CatalystBasics>
 
 =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
@@ -51,7 +56,7 @@ L<Appendices|Catalyst::Manual::Tutorial::Appendices>
 
 =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
@@ -71,26 +76,38 @@ Fans of interactive debuggers.
 
 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);
+    $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
@@ -102,7 +119,7 @@ C<DB::single=1> line as follows inside the C<list> method (I like to
 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) = @_;
@@ -111,7 +128,7 @@ you can obviously indent them if you prefer):
             
         # 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.
@@ -121,6 +138,12 @@ you can obviously indent them if you prefer):
 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>:
 
@@ -130,12 +153,12 @@ This will start the interactive debugger and produce output similar to:
 
     $ 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> 
 
@@ -149,8 +172,8 @@ in.  Once the breakpoint is encountered in the
 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>
 
@@ -160,9 +183,9 @@ model (C<n> jumps over method/subroutine calls; you can also use C<s> to
 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>
 
@@ -172,27 +195,25 @@ output also shows up in the development server debug information.
 
 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.
@@ -202,11 +223,13 @@ argument to the C<x> command limits the depth of the dump to 4 levels):
 
       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>
 
@@ -218,16 +241,32 @@ breakpoint is hit (or the application exits):
 
 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
 
@@ -249,6 +288,10 @@ copy of an installed module:
 
     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:
@@ -256,6 +299,9 @@ 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:
 
@@ -265,7 +311,7 @@ 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:
 
@@ -273,6 +319,12 @@ 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:
@@ -282,7 +334,7 @@ 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.
@@ -291,13 +343,38 @@ Otherwise, it returns undef and nothing will be printed.
 =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-Runtime/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/>).