X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FTutorial%2F07_Debugging.pod;h=faca57fc22aa08b6e593930615167ba6f146d323;hp=f46b9a8e17f244de1b4f7dc1937aecc53b979afc;hb=429d1caf111575afa4c25287cc48d7ed712af327;hpb=532433240eb30ab0ea416cd43bfd5bbe70dfa661

diff --git a/lib/Catalyst/Manual/Tutorial/07_Debugging.pod b/lib/Catalyst/Manual/Tutorial/07_Debugging.pod
index f46b9a8..faca57f 100644
--- a/lib/Catalyst/Manual/Tutorial/07_Debugging.pod
+++ b/lib/Catalyst/Manual/Tutorial/07_Debugging.pod
@@ -56,19 +56,25 @@ L<Appendices|Catalyst::Manual::Tutorial::10_Appendices>
 
 =head1 DESCRIPTION
 
-This chapter 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.
 
+Source code for the tutorial in included in the F</home/catalyst/Final>
+directory of the Tutorial Virtual machine (one subdirectory per
+chapter).  There are also instructions for downloading the code in
+L<Catalyst::Manual::Tutorial::01_Intro>.
+
+
 Note that when it comes to debugging and troubleshooting, there are two
 camps:
 
 =over 4
 
-=item * 
+=item *
 
 Fans of C<log> and C<print> statements embedded in the code.
 
-=item * 
+=item *
 
 Fans of interactive debuggers.
 
@@ -79,9 +85,9 @@ 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|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->log >> facility.
+(See L<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");
 
@@ -93,8 +99,8 @@ template view use:
 
     [% c.log.debug("This is a test log message") %]
 
-As with many other logging facilities, a method is defined for
-each of the following "logging levels" (in increasing order of
+As with many other logging facilities, a method is defined for each of
+the following "logging levels" (in increasing order of
 severity/importance):
 
     $c->log->debug
@@ -103,9 +109,21 @@ severity/importance):
     $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));)>) 
-and TT templates (C<[% Dumper.dump(book) %]>.
+You can also use Data::Dumper in both Catalyst code and in TT templates.
+For use in Catalyst code:
+
+ use Data::Dumper;
+ $c->log->debug("\$var is: ".Dumper($c->stash->{something}));
+
+and TT templates:
+
+ [% USE Dumper ; Dumper.dump(c.stash.something) %].
+
+B<NOTE:> Whether you are a logging fanatic or not, we strongly recommend
+that you take advantage of L<Log::Log4perl> or L<Log::Dispatch>.  It's
+easy to use L<Catalyst::Log> with either of these and they will provide
+a huge amount of extra functionality that you will want in virtually
+every production application you run or support.
 
 
 =head1 RUNNING CATALYST UNDER THE PERL DEBUGGER
@@ -123,20 +141,21 @@ you can obviously indent them if you prefer):
         # 'Context' that's used to 'glue together' the various components
         # that make up the application
         my ($self, $c) = @_;
-    
+
     $DB::single=1;
-    
+
         # 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('DB::Book')->all];
-            
+
         # Set the TT template to use.  You will almost always want to do this
         # in your action methods.
         $c->stash->{template} = 'books/list.tt2';
     }
 
-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).
+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.
 
@@ -144,23 +163,23 @@ 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>:
+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
 
 This will start the interactive debugger and produce output similar to:
 
-    $ perl -d script/myapp_server.pl  
-    
+    $ perl -d script/myapp_server.pl
+
     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:16):      my $debug         = 0;
-    
-      DB<1> 
+
+      DB<1>
 
 Press the C<c> key and hit C<Enter> to continue executing the Catalyst
 development server under the debugger.  Although execution speed will be
@@ -172,9 +191,9 @@ 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:48):
+    MyApp::Controller::Books::list(/home/catalyst/MyApp/script/../lib/MyApp/Controller/Books.pm:48):
     48:         $c->stash->{books} = [$c->model('DB::Book')->all];
-    
+
       DB<1>
 
 You now have the full Perl debugger at your disposal.  First use the
@@ -184,14 +203,14 @@ C<single-step> into methods/subroutines):
 
       DB<1> n
     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):
+    MyApp::Controller::Books::list(/home/catalyst/MyApp/script/../lib/MyApp/Controller/Books.pm:53):
     53:         $c->stash->{template} = 'books/list.tt2';
-    
+
       DB<1>
 
 This takes you to the next line of code where the template name is set.
-Notice that because we enabled C<DBIC_TRACE=1> earlier, SQL debug 
-output also shows up in the development server debug information.
+Notice that because we enabled C<DBIC_TRACE=1> earlier, SQL debug output
+also shows up in the development server debug information.
 
 Next, list the methods available on our C<Book> model:
 
@@ -207,7 +226,7 @@ Next, list the methods available on our C<Book> model:
     _calculate_score
     _collapse_cond
     <lines removed for brevity>
-    
+
       DB<2>
 
 We can also play with the model directly:
@@ -241,15 +260,15 @@ 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.  
+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:
+Finally, press C<q> to exit the debugger and return to your OS shell
+prompt:
 
       DB<4> q
     $
@@ -262,39 +281,37 @@ 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.
+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>.
+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
 
-Although the techniques discussed above work well for code you are 
-writing, what if you want to use print/log/warn messages or set 
-breakpoints in code that you have installed from CPAN (or in module that 
-ship with Perl)?  One helpful approach is to place a copy of the module 
-inside the C<lib> directory of your Catalyst project.  When Catalyst 
-loads, it will load from inside your C<lib> directory first, only 
-turning to the global modules if a local copy cannot be found.  You can 
-then make modifications such as adding a C<$DB::single=1> to the local 
-copy of the module without risking the copy in the original location. 
-This can also be a great way to "locally override" bugs in modules while 
+Although the techniques discussed above work well for code you are
+writing, what if you want to use print/log/warn messages or set
+breakpoints in code that you have installed from CPAN (or in module that
+ship with Perl)?  One helpful approach is to place a copy of the module
+inside the C<lib> directory of your Catalyst project.  When Catalyst
+loads, it will load from inside your C<lib> directory first, only
+turning to the global modules if a local copy cannot be found.  You can
+then make modifications such as adding a C<$DB::single=1> to the local
+copy of the module without risking the copy in the original location.
+This can also be a great way to "locally override" bugs in modules while
 you wait for a fix on CPAN.
 
-
-Matt Trout has suggested the following shortcut to create a local
-copy of an installed module:
+Matt Trout has suggested the following shortcut to create a local 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.
+Note: If you are following along in Debian 6 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:
+For example, you could make a copy of
+L<Catalyst::Plugin::Authentication> with the following command:
 
     mkdir -p lib/Catalyst/Plugin; cp \
         `perldoc -l Catalyst::Plugin::Authentication` lib/Catalyst/Plugin
@@ -302,12 +319,11 @@ with the following command:
 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:
+B<Note:> Matt has also suggested the following tips for Perl debugging:
 
 =over 4
 
-=item * 
+=item *
 
 Check the version of an installed module:
 
@@ -325,7 +341,7 @@ and if you are using bash aliases:
         or die qq(module \"\$m\" is not installed\\n); \
         print \$m->VERSION'"
 
-=item * 
+=item *
 
 Check if a modules contains a given method:
 
@@ -345,9 +361,9 @@ Otherwise, it returns undef and nothing will be printed.
 
 =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> 
+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/HTML.pm>:
 
     __PACKAGE__->config({
@@ -355,30 +371,32 @@ declaration in C<lib/MyApp/View/HTML.pm>:
         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).
+There are a variety of options you can use, such as 'undef', 'all',
+'service', 'context', 'parser' and 'provider'.  See
+L<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 
+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.
 
+
+You can jump to the next chapter of the tutorial here:
+L<Testing|Catalyst::Manual::Tutorial::08_Testing>
+
+
 =head1 AUTHOR
 
 Kennedy Clark, C<hkclark@gmail.com>
 
 Feel free to contact the author for any errors or suggestions, but the
 best way to report issues is via the CPAN RT Bug system at
-<https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Manual>.
-
-The 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/>.
+L<https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Manual>.
 
-Copyright 2006-2010, Kennedy Clark, under the
+Copyright 2006-2011, Kennedy Clark, under the
 Creative Commons Attribution Share-Alike License Version 3.0
 (L<http://creativecommons.org/licenses/by-sa/3.0/us/>).