lib/Catalyst/Manual/Tutorial/07_Debugging.pod

   1 =head1 NAME
   2
   3 Catalyst::Manual::Tutorial::07_Debugging - Catalyst Tutorial - Chapter 7: Debugging
   4
   5
   6 =head1 OVERVIEW
   7
   8 This is B<Chapter 7 of 10> for the Catalyst tutorial.
   9
  10 L<Tutorial Overview|Catalyst::Manual::Tutorial>
  11
  12 =over 4
  13
  14 =item 1
  15
  16 L<Introduction|Catalyst::Manual::Tutorial::01_Intro>
  17
  18 =item 2
  19
  20 L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics>
  21
  22 =item 3
  23
  24 L<More Catalyst Basics|Catalyst::Manual::Tutorial::03_MoreCatalystBasics>
  25
  26 =item 4
  27
  28 L<Basic CRUD|Catalyst::Manual::Tutorial::04_BasicCRUD>
  29
  30 =item 5
  31
  32 L<Authentication|Catalyst::Manual::Tutorial::05_Authentication>
  33
  34 =item 6
  35
  36 L<Authorization|Catalyst::Manual::Tutorial::06_Authorization>
  37
  38 =item 7
  39
  40 B<07_Debugging>
  41
  42 =item 8
  43
  44 L<Testing|Catalyst::Manual::Tutorial::08_Testing>
  45
  46 =item 9
  47
  48 L<Advanced CRUD|Catalyst::Manual::Tutorial::09_AdvancedCRUD>
  49
  50 =item 10
  51
  52 L<Appendices|Catalyst::Manual::Tutorial::10_Appendices>
  53
  54 =back
  55
  56
  57 =head1 DESCRIPTION
  58
  59 This chapter of the tutorial takes a brief look at the primary options
  60 available for troubleshooting Catalyst applications.
  61
  62 Note that when it comes to debugging and troubleshooting, there are two
  63 camps:
  64
  65 =over 4
  66
  67 =item *
  68
  69 Fans of C<log> and C<print> statements embedded in the code.
  70
  71 =item *
  72
  73 Fans of interactive debuggers.
  74
  75 =back
  76
  77 Catalyst is able to easily accommodate both styles of debugging.
  78
  79
  80 =head1 LOG STATEMENTS
  81
  82 Folks in the former group can use Catalyst's C<$c-E<gt>log> facility.
  83 (See L<Catalyst::Log> for more detail.) For example, if you add the
  84 following code to a controller action method:
  85
  86     $c->log->info("Starting the foreach loop here");
  87
  88     $c->log->debug("Value of \$id is: ".$id);
  89
  90 Then the Catalyst development server will display your message along
  91 with the other debug output. To accomplish the same thing in a TT
  92 template view use:
  93
  94     [% c.log.debug("This is a test log message") %]
  95
  96 As with many other logging facilities, a method is defined for each of
  97 the following "logging levels" (in increasing order of
  98 severity/importance):
  99
 100     $c->log->debug
 101     $c->log->info
 102     $c->log->warn
 103     $c->log->error
 104     $c->log->fatal
 105
 106 You can also use L<Data::Dumper> in both Catalyst code
 107 (C<use Data::Dumper; $c-E<gt>log-E<gt>debug("\$var is: ".Dumper($var));)>)
 108 and TT templates (C<[% Dumper.dump(book) %]>.
 109
 110
 111 =head1 RUNNING CATALYST UNDER THE PERL DEBUGGER
 112
 113 Members of the interactive-debugger fan club will also be at home with
 114 Catalyst applications.  One approach to this style of Perl debugging is
 115 to embed breakpoints in your code.  For example, open
 116 C<lib/MyApp/Controller/Books.pm> in your editor and add the
 117 C<DB::single=1> line as follows inside the C<list> method (I like to
 118 "left-justify" my debug statements so I don't forget to remove them, but
 119 you can obviously indent them if you prefer):
 120
 121     sub list :Local {
 122         # Retrieve the usual Perl OO '$self' for this object. $c is the Catalyst
 123         # 'Context' that's used to 'glue together' the various components
 124         # that make up the application
 125         my ($self, $c) = @_;
 126
 127     $DB::single=1;
 128
 129         # Retrieve all of the book records as book model objects and store in the
 130         # stash where they can be accessed by the TT template
 131         $c->stash->{books} = [$c->model('DB::Book')->all];
 132
 133         # Set the TT template to use.  You will almost always want to do this
 134         # in your action methods.
 135         $c->stash->{template} = 'books/list.tt2';
 136     }
 137
 138 This causes the Perl Debugger to enter "single step mode" when this
 139 command is encountered (it has no effect when Perl is run without the
 140 C<-d> flag).
 141
 142 B<NOTE:> The C<DB> here is the Perl Debugger, not the DB model.
 143
 144 If you haven't done it already, enable SQL logging as before:
 145
 146     $ export DBIC_TRACE=1
 147
 148 To now run the Catalyst development server under the Perl debugger,
 149 simply prepend C<perl -d> to the front of C<script/myapp_server.pl>:
 150
 151     $ perl -d script/myapp_server.pl
 152
 153 This will start the interactive debugger and produce output similar to:
 154
 155     $ perl -d script/myapp_server.pl
 156
 157     Loading DB routines from perl5db.pl version 1.3
 158     Editor support available.
 159
 160     Enter h or `h h' for help, or `man perldebug' for more help.
 161
 162     main::(script/myapp_server.pl:16):      my $debug         = 0;
 163
 164       DB<1>
 165
 166 Press the C<c> key and hit C<Enter> to continue executing the Catalyst
 167 development server under the debugger.  Although execution speed will be
 168 slightly slower than normal, you should soon see the usual Catalyst
 169 startup debug information.
 170
 171 Now point your browser to L<http://localhost:3000/books/list> and log
 172 in.  Once the breakpoint is encountered in the
 173 C<MyApp::Controller::list> method, the console session running the
 174 development server will drop to the Perl debugger prompt:
 175
 176     MyApp::Controller::Books::list(/home/me/MyApp/script/../lib/MyApp/Controller/Books.pm:48):
 177     48:         $c->stash->{books} = [$c->model('DB::Book')->all];
 178
 179       DB<1>
 180
 181 You now have the full Perl debugger at your disposal.  First use the
 182 C<next> feature by typing C<n> to execute the C<all> method on the Book
 183 model (C<n> jumps over method/subroutine calls; you can also use C<s> to
 184 C<single-step> into methods/subroutines):
 185
 186       DB<1> n
 187     SELECT me.id, me.title, me.rating, me.created, me.updated FROM book me:
 188     MyApp::Controller::Books::list(/home/me/MyApp/script/../lib/MyApp/Controller/Books.pm:53):
 189     53:         $c->stash->{template} = 'books/list.tt2';
 190
 191       DB<1>
 192
 193 This takes you to the next line of code where the template name is set.
 194 Notice that because we enabled C<DBIC_TRACE=1> earlier, SQL debug output
 195 also shows up in the development server debug information.
 196
 197 Next, list the methods available on our C<Book> model:
 198
 199       DB<1> m $c->model('DB::Book')
 200     ()
 201     (0+
 202     (bool
 203     __result_class_accessor
 204     __source_handle_accessor
 205     _add_alias
 206     __bool
 207     _build_unique_query
 208     _calculate_score
 209     _collapse_cond
 210     <lines removed for brevity>
 211
 212       DB<2>
 213
 214 We can also play with the model directly:
 215
 216       DB<2> x ($c->model('DB::Book')->all)[1]->title
 217     SELECT me.id, me.title, me.rating, me.created, me.updated FROM book me:
 218     0  'TCP/IP Illustrated, Volume 1'
 219
 220 This uses the Perl debugger C<x> command to display the title of a book.
 221
 222 Next we inspect the C<books> element of the Catalyst C<stash> (the C<4>
 223 argument to the C<x> command limits the depth of the dump to 4 levels):
 224
 225       DB<3> x 4 $c->stash->{books}
 226     0  ARRAY(0xa8f3b7c)
 227        0  MyApp::Model::DB::Book=HASH(0xb8e702c)
 228           '_column_data' => HASH(0xb8e5e2c)
 229              'created' => '2009-05-08 10:19:46'
 230              'id' => 1
 231              'rating' => 5
 232              'title' => 'CCSP SNRS Exam Certification Guide'
 233              'updated' => '2009-05-08 10:19:46'
 234           '_in_storage' => 1
 235     <lines removed for brevity>
 236
 237 Then enter the C<c> command to continue processing until the next
 238 breakpoint is hit (or the application exits):
 239
 240       DB<4> c
 241     SELECT author.id, author.first_name, author.last_name FROM ...
 242
 243 Finally, press C<Ctrl+C> to break out of the development server.
 244 Because we are running inside the Perl debugger, you will drop to the
 245 debugger prompt.
 246
 247     ^CCatalyst::Engine::HTTP::run(/usr/local/share/perl/5.10.0/Catalyst/Engine/HTTP.pm:260):
 248     260:            while ( accept( Remote, $daemon ) ) {
 249
 250     DB<4>
 251
 252 Finally, press C<q> to exit the debugger and return to your OS shell
 253 prompt:
 254
 255       DB<4> q
 256     $
 257
 258 For more information on using the Perl debugger, please see C<perldebug>
 259 and C<perldebtut>.  For those daring souls out there, you can dive down
 260 even deeper into the magical depths of this fine debugger by checking
 261 out C<perldebguts>.
 262
 263 You can also type C<h> or C<h h> at the debugger prompt to view the
 264 built-in help screens.
 265
 266 For an excellent book covering all aspects of the Perl debugger, we
 267 highly recommend reading 'Pro Perl Debugging' by Richard Foley.
 268
 269 Oh yeah, before you forget, be sure to remove the C<DB::single=1> line
 270 you added above in C<lib/MyApp/Controller/Books.pm>.
 271
 272 =head1 DEBUGGING MODULES FROM CPAN
 273
 274 Although the techniques discussed above work well for code you are
 275 writing, what if you want to use print/log/warn messages or set
 276 breakpoints in code that you have installed from CPAN (or in module that
 277 ship with Perl)?  One helpful approach is to place a copy of the module
 278 inside the C<lib> directory of your Catalyst project.  When Catalyst
 279 loads, it will load from inside your C<lib> directory first, only
 280 turning to the global modules if a local copy cannot be found.  You can
 281 then make modifications such as adding a C<$DB::single=1> to the local
 282 copy of the module without risking the copy in the original location.
 283 This can also be a great way to "locally override" bugs in modules while
 284 you wait for a fix on CPAN.
 285
 286 Matt Trout has suggested the following shortcut to create a local copy
 287 of an installed module:
 288
 289     mkdir -p lib/Module; cp `perldoc -l Module::Name` lib/Module/
 290
 291 Note: If you are following along in Debian 6 or Ubuntu, you will need to
 292 install the C<perl-doc> package to use the C<perldoc> command.  Use
 293 C<sudo aptitude install perl-doc> to do that.
 294
 295 For example, you could make a copy of
 296 L<Catalyst::Plugin::Authentication> with the following command:
 297
 298     mkdir -p lib/Catalyst/Plugin; cp \
 299         `perldoc -l Catalyst::Plugin::Authentication` lib/Catalyst/Plugin
 300
 301 You can then use the local copy inside your project to place logging
 302 messages and/or breakpoints for further study of that module.
 303
 304 B<Note:> Matt has also suggested the following tips for Perl debugging:
 305
 306 =over 4
 307
 308 =item *
 309
 310 Check the version of an installed module:
 311
 312     perl -M<mod_name> -e 'print "$<mod_name>::VERSION\n"'
 313
 314 For example:
 315
 316     $ perl -MCatalyst::Plugin::Authentication -e \
 317         'print $Catalyst::Plugin::Authentication::VERSION;'
 318     0.07
 319
 320 and if you are using bash aliases:
 321
 322     alias pmver="perl -le '\$m = shift; eval qq(require \$m) \
 323         or die qq(module \"\$m\" is not installed\\n); \
 324         print \$m->VERSION'"
 325
 326 =item *
 327
 328 Check if a modules contains a given method:
 329
 330     perl -MModule::Name -e 'print Module::Name->can("method");'
 331
 332 For example:
 333
 334     $ perl -MCatalyst::Plugin::Authentication -e \
 335         'print Catalyst::Plugin::Authentication->can("user");'
 336     CODE(0x9c8db2c)
 337
 338 If the method exists, the Perl C<can> method returns a coderef.
 339 Otherwise, it returns undef and nothing will be printed.
 340
 341 =back
 342
 343
 344 =head1 TT DEBUGGING
 345
 346 If you run into issues during the rendering of your template, it might
 347 be helpful to enable TT C<DEBUG> options.  You can do this in a Catalyst
 348 environment by adding a C<DEBUG> line to the C<__PACKAGE__->config>
 349 declaration in C<lib/MyApp/View/HTML.pm>:
 350
 351     __PACKAGE__->config({
 352         TEMPLATE_EXTENSION => '.tt2',
 353         DEBUG              => 'undef',
 354     });
 355
 356 There are a variety of options you can use, such as 'undef', 'all',
 357 'service', 'context', 'parser' and 'provider'.  See
 358 L<Template::Constants> for more information (remove the C<DEBUG_>
 359 portion of the name shown in the TT docs and convert to lower case for
 360 use inside Catalyst).
 361
 362 B<NOTE:> B<Please be sure to disable TT debug options before continuing
 363 with the tutorial> (especially the 'undef' option -- leaving this
 364 enabled will conflict with several of the conventions used by this
 365 tutorial to leave some variables undefined on purpose).
 366
 367 Happy debugging.
 368
 369 =head1 AUTHOR
 370
 371 Kennedy Clark, C<hkclark@gmail.com>
 372
 373 Feel free to contact the author for any errors or suggestions, but the
 374 best way to report issues is via the CPAN RT Bug system at
 375 <https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Manual>.
 376
 377 The most recent version of the Catalyst Tutorial can be found at
 378 L<http://dev.catalyst.perl.org/repos/Catalyst/Catalyst-Manual/5.80/trunk/lib/Catalyst/Manual/Tutorial/>.
 379
 380 Copyright 2006-2010, Kennedy Clark, under the
 381 Creative Commons Attribution Share-Alike License Version 3.0
 382 (L<http://creativecommons.org/licenses/by-sa/3.0/us/>).