lib/Catalyst/Manual/Tutorial/Debugging.pod

   1 =head1 NAME
   2
   3 Catalyst::Manual::Tutorial::Debugging - Catalyst Tutorial - Part 6: Debugging
   4
   5 =head1 OVERVIEW
   6
   7 This is B<Part 6 of 9> for the Catalyst tutorial.
   8
   9 L<Tutorial Overview|Catalyst::Manual::Tutorial>
  10
  11 =over 4
  12
  13 =item 1
  14
  15 L<Introduction|Catalyst::Manual::Tutorial::Intro>
  16
  17 =item 2
  18
  19 L<Catalyst Basics|Catalyst::Manual::Tutorial::CatalystBasics>
  20
  21 =item 3
  22
  23 L<Basic CRUD|Catalyst::Manual::Tutorial_BasicCRUD>
  24
  25 =item 4
  26
  27 L<Authentication|Catalyst::Manual::Tutorial::Authentication>
  28
  29 =item 5
  30
  31 L<Authorization|Catalyst::Manual::Tutorial::Authorization>
  32
  33 =item 6
  34
  35 B<Debugging>
  36
  37 =item 7
  38
  39 L<Testing|Catalyst::Manual::Tutorial::Testing>
  40
  41 =item 8
  42
  43 L<AdvancedCRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
  44
  45 =item 9
  46
  47 L<Appendices|Catalyst::Manual::Tutorial::Appendices>
  48
  49 =back
  50
  51
  52 =head1 DESCRIPTION
  53
  54 This part of the tutorial takes a brief look at the primary options
  55 available for troubleshooting Catalyst applications.
  56
  57 Note that when it comes to debugging and troubleshooting, there are two
  58 camps:
  59
  60 =over 4
  61
  62 =item *
  63
  64 Fans of C<log> and C<print> statements embedded in the code.
  65
  66 =item *
  67
  68 Fans of interactive debuggers.
  69
  70 =back
  71
  72 Catalyst is able to easily accommodate both styles of debugging.
  73
  74 =head1 LOG STATEMENTS
  75
  76 Folks in the former group can use Catalyst's C<$c-E<gt>log> facility.
  77 (See L<Catalyst::Log> for more detail.) For example, if you add the
  78 following code to a controller action method:
  79
  80     $c->log->info("Starting the foreach loop here");
  81
  82     $c->log->debug("Value of \$id is: ".$id);
  83
  84 Then the Catalyst development server will display your message along
  85 with the other debug output. To accomplish the same thing in a TTSite
  86 view use:
  87
  88     [% Catalyst.log.debug("This is a test log message") %]
  89
  90 You can also use L<Data::Dumper|Data::Dumper> in both Catalyst code
  91 (C<use Data::Dumper; $c-E<gt>log-E<gt>debug("$var is: ".Dumper($var));)>)
  92 and TT templates (C<[% Dumper.dump(book) %]>.
  93
  94 =head1 RUNNING CATALYST UNDER THE PERL DEBUGGER
  95
  96 Members of the interactive-debugger fan club will also be at home with
  97 Catalyst applications.  One approach to this style of Perl debugging is
  98 to embed breakpoints in your code.  For example, open
  99 C<lib/MyApp/Controller/Books.pm> in your editor and add the
 100 C<DB::single=1> line as follows inside the C<list> method (I like to
 101 "left-justify" my debug statements so I don't forget to remove them, but
 102 you can obviously indent them if you prefer):
 103
 104     sub list : Local {
 105         # Retrieve the usual perl OO '$self' for this object. $c is the Catalyst
 106         # 'Context' that's used to 'glue together' the various components
 107         # that make up the application
 108         my ($self, $c) = @_;
 109
 110     $DB::single=1;
 111
 112         # Retrieve all of the book records as book model objects and store in the
 113         # stash where they can be accessed by the TT template
 114         $c->stash->{books} = [$c->model('MyAppDB::Book')->all];
 115
 116         # Set the TT template to use.  You will almost always want to do this
 117         # in your action methods.
 118         $c->stash->{template} = 'books/list.tt2';
 119     }
 120
 121 This causes the Perl Debugger to enter "single step mode" when this command is
 122 encountered (it has no effect when Perl is run without the C<-d> flag).
 123
 124 To now run the Catalyst development server under the Perl debugger, simply
 125 prepend C<perl -d> to the front of C<script/myapp_server.pl>:
 126
 127     $ perl -d script/myapp_server.pl
 128
 129 This will start the interactive debugger and produce output similar to:
 130
 131     $ perl -d script/myapp_server.pl
 132
 133     Loading DB routines from perl5db.pl version 1.27
 134     Editor support available.
 135
 136     Enter h or `h h' for help, or `man perldebug' for more help.
 137
 138     main::(script/myapp_server.pl:14):      my $debug         = 0;
 139
 140       DB<1>
 141
 142 Press the C<c> key and hit C<Enter> to continue executing the Catalyst
 143 development server under the debugger.  Although execution speed will be
 144 slightly slower than normal, you should soon see the usual Catalyst
 145 startup debug information.
 146
 147 Now point your browser to L<http://localhost:3000/books/list> and log
 148 in.  Once the breakpoint is encountered in the
 149 C<MyApp::Controller::list> method, the console session running the
 150 development server will drop to the Perl debugger prompt:
 151
 152     MyApp::Controller::Books::list(/home/me/MyApp/script/../lib/MyApp/Controller/Books.pm:40):
 153     40:         $c->stash->{books} = [$c->model('MyAppDB::Book')->all];
 154
 155       DB<1>
 156
 157 You now have the full Perl debugger at your disposal.  First use the
 158 C<next> feature by typing C<n> to execute the C<all> method on the Book
 159 model (C<n> jumps over method/subroutine calls; you can also use C<s> to
 160 C<single-step> into methods/subroutines):
 161
 162       DB<1> n
 163     SELECT me.id, me.authors, me.title, me.rating FROM books me:
 164     MyApp::Controller::Books::list(/home/me/MyApp/script/../lib/MyApp/Controller/Books.pm:44):
 165     44:         $c->stash->{template} = 'books/list.tt2';
 166
 167       DB<1>
 168
 169 This takes you to the next line of code where the template name is set.
 170 Notice that because we enabled C<DBIC_TRACE=1> earlier, SQL debug
 171 output also shows up in the development server debug information.
 172
 173 Next, list the methods available on our C<Book> model:
 174
 175       DB<1> m $c->model('MyAppDB::Book')
 176     ()
 177     (0+
 178     (bool
 179     MODIFY_CODE_ATTRIBUTES
 180     _attr_cache
 181     _collapse_result
 182     _construct_object
 183     _count
 184     _result_class_accessor
 185     _result_source_accessor
 186     all
 187     carp
 188     <lines removed for brevity>
 189
 190       DB<2>
 191
 192 We can also play with the model directly:
 193
 194       DB<2> x ($c->model('MyAppDB::Book')->all)[1]->title
 195     SELECT me.id, me.title, me.rating FROM books me:
 196     0  'TCP/IP Illustrated, Volume 1'
 197
 198 This uses the Perl debugger C<x> command to display the title of a book.
 199
 200 Next we inspect the C<books> element of the Catalyst C<stash> (the C<4>
 201 argument to the C<x> command limits the depth of the dump to 4 levels):
 202
 203       DB<3> x 4 $c->stash->{books}
 204     0  ARRAY(0xa8f3b7c)
 205        0  MyApp::Model::MyAppDB::Book=HASH(0xb8e702c)
 206           '_column_data' => HASH(0xb8e5e2c)
 207              'id' => 1
 208              'rating' => 5
 209              'title' => 'CCSP SNRS Exam Certification Guide'
 210           '_in_storage' => 1
 211     <lines removed for brevity>
 212
 213 Then enter the C<c> command to continue processing until the next
 214 breakpoint is hit (or the application exits):
 215
 216       DB<4> c
 217     SELECT author.id, author.first_name, author.last_name FROM ...
 218
 219 Finally, press C<Ctrl+C> to break out of the development server.
 220 Because we are running inside the Perl debugger, you will drop to the
 221 debugger prompt.  Press C<q> to exit the debugger and return to your OS
 222 shell prompt:
 223
 224       DB<4> q
 225     $
 226
 227 For more information on using the Perl debugger, please see C<perldebug>
 228 and C<perldebtut>.  You can also type C<h> or C<h h> at the debugger
 229 prompt to view the built-in help screens.
 230
 231
 232 =head1 DEBUGGING MODULES FROM CPAN
 233
 234 Although the techniques discussed above work well for code you are
 235 writing, what if you want to use print/log/warn messages or set
 236 breakpoints in code that you have installed from CPAN (or in module that
 237 ship with Perl)?  One helpful approach is to place a copy of the module
 238 inside the C<lib> directory of your Catalyst project.  When Catalyst
 239 loads, it will load from inside your C<lib> directory first, only
 240 turning to the global modules if a local copy cannot be found.  You can
 241 then make modifications such as adding a C<$DB::single=1> to the local
 242 copy of the module without risking the copy in the original location.
 243 This can also be a great way to "locally override" bugs in modules while
 244 you wait for a fix on CPAN.
 245
 246
 247 Matt Trout has suggested the following shortcut to create a local
 248 copy of an installed module:
 249
 250     mkdir -p lib/Module; cp `perldoc -l Module::Name` lib/Module/
 251
 252 For example, you could make a copy of
 253 L<Catalyst::Plugin::Authentication|Catalyst::Plugin::Authentication>
 254 with the following command:
 255
 256     mkdir -p lib/Catalyst/Plugin; cp \
 257         `perldoc -l Catalyst::Plugin::Authentication` lib/Catalyst/Plugin
 258
 259 B<Note:> Matt has also suggested the following tips for Perl
 260 debugging:
 261
 262 =over 4
 263
 264 =item *
 265
 266 Check the version of an installed module:
 267
 268     perl -MModule::Name -e 'print $Module::Name::VERSION;'
 269
 270 For example:
 271
 272     $ perl -MCatalyst::Plugin::Authentication -e \
 273         'print $Catalyst::Plugin::Authentication::VERSION;'
 274     0.07
 275
 276 =item *
 277
 278 Check if a modules contains a given method:
 279
 280     perl -MModule::Name -e 'print Module::Name->can("method");'
 281
 282 For example:
 283
 284     $ perl -MCatalyst::Plugin::Authentication -e \
 285         'print Catalyst::Plugin::Authentication->can("prepare");'
 286     CODE(0x9c8db2c)
 287
 288 If the method exists, the Perl C<can> method returns a coderef.
 289 Otherwise, it returns undef and nothing will be printed.
 290
 291 =back
 292
 293
 294 =head1 AUTHOR
 295
 296 Kennedy Clark, C<hkclark@gmail.com>
 297
 298 Please report any errors, issues or suggestions to the author.  The
 299 most recent version of the Catalyst Tutorial can be found at
 300 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Manual/lib/Catalyst/Manual/Tutorial/>.
 301
 302 Copyright 2006, Kennedy Clark, under Creative Commons License
 303 (L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).