lib/Catalyst/Manual/Tutorial/Debugging.pod

   1 =head1 NAME
   2
   3 Catalyst::Manual::Tutorial::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::Intro>
  17
  18 =item 2
  19
  20 L<Catalyst Basics|Catalyst::Manual::Tutorial::CatalystBasics>
  21
  22 =item 3
  23
  24 L<More Catalyst Basics|Catalyst::Manual::Tutorial::MoreCatalystBasics>
  25
  26 =item 4
  27
  28 L<Basic CRUD|Catalyst::Manual::Tutorial::BasicCRUD>
  29
  30 =item 5
  31
  32 L<Authentication|Catalyst::Manual::Tutorial::Authentication>
  33
  34 =item 6
  35
  36 L<Authorization|Catalyst::Manual::Tutorial::Authorization>
  37
  38 =item 7
  39
  40 B<Debugging>
  41
  42 =item 8
  43
  44 L<Testing|Catalyst::Manual::Tutorial::Testing>
  45
  46 =item 9
  47
  48 L<Advanced CRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
  49
  50 =item 10
  51
  52 L<Appendices|Catalyst::Manual::Tutorial::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|Catalyst::Log> for more detail.) For example, if
  84 you add the 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, you a method is defined for
  97 each of 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|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::Books')->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 command is
 139 encountered (it has no effect when Perl is run without the C<-d> flag).
 140
 141 B<NOTE:> The C<DB> here is the Perl Debugger, not the DB model.
 142
 143 To now run the Catalyst development server under the Perl debugger, simply
 144 prepend C<perl -d> to the front of C<script/myapp_server.pl>:
 145
 146     $ perl -d script/myapp_server.pl
 147
 148 This will start the interactive debugger and produce output similar to:
 149
 150     $ perl -d script/myapp_server.pl
 151
 152     Loading DB routines from perl5db.pl version 1.3
 153     Editor support available.
 154
 155     Enter h or `h h' for help, or `man perldebug' for more help.
 156
 157     main::(script/myapp_server.pl:16):      my $debug         = 0;
 158
 159       DB<1>
 160
 161 Press the C<c> key and hit C<Enter> to continue executing the Catalyst
 162 development server under the debugger.  Although execution speed will be
 163 slightly slower than normal, you should soon see the usual Catalyst
 164 startup debug information.
 165
 166 Now point your browser to L<http://localhost:3000/books/list> and log
 167 in.  Once the breakpoint is encountered in the
 168 C<MyApp::Controller::list> method, the console session running the
 169 development server will drop to the Perl debugger prompt:
 170
 171     MyApp::Controller::Books::list(/home/me/MyApp/script/../lib/MyApp/Controller/Books.pm:48):
 172     48:         $c->stash->{books} = [$c->model('DB::Books')->all];
 173
 174       DB<1>
 175
 176 You now have the full Perl debugger at your disposal.  First use the
 177 C<next> feature by typing C<n> to execute the C<all> method on the Book
 178 model (C<n> jumps over method/subroutine calls; you can also use C<s> to
 179 C<single-step> into methods/subroutines):
 180
 181       DB<1> n
 182     SELECT me.id, me.authors, me.title, me.rating FROM books me:
 183     MyApp::Controller::Books::list(/home/me/MyApp/script/../lib/MyApp/Controller/Books.pm:53):
 184     53:         $c->stash->{template} = 'books/list.tt2';
 185
 186       DB<1>
 187
 188 This takes you to the next line of code where the template name is set.
 189 Notice that because we enabled C<DBIC_TRACE=1> earlier, SQL debug
 190 output also shows up in the development server debug information.
 191
 192 Next, list the methods available on our C<Book> model:
 193
 194       DB<1> m $c->model('DB::Books')
 195     ()
 196     (0+
 197     (bool
 198     __source_handle_accessor
 199     _add_alias
 200     _build_unique_query
 201     _calculate_score
 202     _collapse_cond
 203     <lines removed for brevity>
 204
 205       DB<2>
 206
 207 We can also play with the model directly:
 208
 209       DB<2> x ($c->model('DB::Books')->all)[1]->title
 210     SELECT me.id, me.title, me.rating FROM books me:
 211     0  'TCP/IP Illustrated, Volume 1'
 212
 213 This uses the Perl debugger C<x> command to display the title of a book.
 214
 215 Next we inspect the C<books> element of the Catalyst C<stash> (the C<4>
 216 argument to the C<x> command limits the depth of the dump to 4 levels):
 217
 218       DB<3> x 4 $c->stash->{books}
 219     0  ARRAY(0xa8f3b7c)
 220        0  MyApp::Model::DB::Book=HASH(0xb8e702c)
 221           '_column_data' => HASH(0xb8e5e2c)
 222              'id' => 1
 223              'rating' => 5
 224              'title' => 'CCSP SNRS Exam Certification Guide'
 225           '_in_storage' => 1
 226     <lines removed for brevity>
 227
 228 Then enter the C<c> command to continue processing until the next
 229 breakpoint is hit (or the application exits):
 230
 231       DB<4> c
 232     SELECT author.id, author.first_name, author.last_name FROM ...
 233
 234 Finally, press C<Ctrl+C> to break out of the development server.
 235 Because we are running inside the Perl debugger, you will drop to the
 236 debugger prompt.  Press C<q> to exit the debugger and return to your OS
 237 shell prompt:
 238
 239       DB<4> q
 240     $
 241
 242 For more information on using the Perl debugger, please see C<perldebug>
 243 and C<perldebtut>.  You can also type C<h> or C<h h> at the debugger
 244 prompt to view the built-in help screens.
 245
 246
 247 =head1 DEBUGGING MODULES FROM CPAN
 248
 249 Although the techniques discussed above work well for code you are
 250 writing, what if you want to use print/log/warn messages or set
 251 breakpoints in code that you have installed from CPAN (or in module that
 252 ship with Perl)?  One helpful approach is to place a copy of the module
 253 inside the C<lib> directory of your Catalyst project.  When Catalyst
 254 loads, it will load from inside your C<lib> directory first, only
 255 turning to the global modules if a local copy cannot be found.  You can
 256 then make modifications such as adding a C<$DB::single=1> to the local
 257 copy of the module without risking the copy in the original location.
 258 This can also be a great way to "locally override" bugs in modules while
 259 you wait for a fix on CPAN.
 260
 261
 262 Matt Trout has suggested the following shortcut to create a local
 263 copy of an installed module:
 264
 265     mkdir -p lib/Module; cp `perldoc -l Module::Name` lib/Module/
 266
 267 Note: If you are following along in Debian 5, you will need to install
 268 the C<perl-doc> package to use the C<perldoc> command.  Use
 269 C<sudo aptitude install perl-doc> to do that.
 270
 271 For example, you could make a copy of
 272 L<Catalyst::Plugin::Authentication|Catalyst::Plugin::Authentication>
 273 with the following command:
 274
 275     mkdir -p lib/Catalyst/Plugin; cp \
 276         `perldoc -l Catalyst::Plugin::Authentication` lib/Catalyst/Plugin
 277
 278 You can then use the local copy inside your project to place logging
 279 messages and/or breakpoints for further study of that module.
 280
 281 B<Note:> Matt has also suggested the following tips for Perl
 282 debugging:
 283
 284 =over 4
 285
 286 =item *
 287
 288 Check the version of an installed module:
 289
 290     perl -ME<lt>mod_nameE<gt> -e '"print $E<lt>mod_nameE<gt>::VERSION\n"'
 291
 292 For example:
 293
 294     $ perl -MCatalyst::Plugin::Authentication -e \
 295         'print $Catalyst::Plugin::Authentication::VERSION;'
 296     0.07
 297
 298 =item *
 299
 300 Check if a modules contains a given method:
 301
 302     perl -MModule::Name -e 'print Module::Name->can("method");'
 303
 304 For example:
 305
 306     $ perl -MCatalyst::Plugin::Authentication -e \
 307         'print Catalyst::Plugin::Authentication->can("user");'
 308     CODE(0x9c8db2c)
 309
 310 If the method exists, the Perl C<can> method returns a coderef.
 311 Otherwise, it returns undef and nothing will be printed.
 312
 313 =back
 314
 315
 316 =head1 TT DEBUGGING
 317
 318 If you run into issues during the rendering of your template, it might
 319 be helpful to enable TT C<DEBUG> options.  You can do this in a Catalyst
 320 environment by adding a C<DEBUG> line to the C<__PACKAGE__->config>
 321 declaration in C<lib/MyApp/View/TT.pm>:
 322
 323     __PACKAGE__->config({
 324         TEMPLATE_EXTENSION => '.tt2',
 325         DEBUG              => 'undef',
 326     });
 327
 328 There are a variety of options you can use, such as 'undef', 'all',
 329 'service', 'context', 'parser' and 'provider'.  See
 330 L<Template::Constants|Template::Constants> for more information
 331 (remove the C<DEBUG_> portion of the name shown in the TT docs and
 332 convert to lower case for use inside Catalyst).
 333
 334 B<NOTE:> B<Please be sure to disable TT debug options before continuing
 335 with the tutorial> (especially the 'undef' option -- leaving this
 336 enabled will conflict with several of the conventions used by this
 337 tutorial to leave some variables undefined on purpose).
 338
 339
 340 =head1 AUTHOR
 341
 342 Kennedy Clark, C<hkclark@gmail.com>
 343
 344 Please report any errors, issues or suggestions to the author.  The
 345 most recent version of the Catalyst Tutorial can be found at
 346 L<http://dev.catalyst.perl.org/repos/Catalyst/Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/>.
 347
 348 Copyright 2006-2008, Kennedy Clark, under Creative Commons License
 349 (L<http://creativecommons.org/licenses/by-sa/3.0/us/>).