lib/Catalyst/Manual/Tutorial/Debugging.pod

   1 =head1 NAME
   2
   3 Catalyst::Manual::Tutorial::Debugging - Catalyst Tutorial - Part 7: Debugging
   4
   5
   6 =head1 OVERVIEW
   7
   8 This is B<Part 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 part 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 You can also use L<Data::Dumper|Data::Dumper> in both Catalyst code
  97 (C<use Data::Dumper; $c-E<gt>log-E<gt>debug("\$var is: ".Dumper($var));)>)
  98 and TT templates (C<[% Dumper.dump(book) %]>.
  99
 100
 101 =head1 RUNNING CATALYST UNDER THE PERL DEBUGGER
 102
 103 Members of the interactive-debugger fan club will also be at home with
 104 Catalyst applications.  One approach to this style of Perl debugging is
 105 to embed breakpoints in your code.  For example, open
 106 C<lib/MyApp/Controller/Books.pm> in your editor and add the
 107 C<DB::single=1> line as follows inside the C<list> method (I like to
 108 "left-justify" my debug statements so I don't forget to remove them, but
 109 you can obviously indent them if you prefer):
 110
 111     sub list : Local {
 112         # Retrieve the usual Perl OO '$self' for this object. $c is the Catalyst
 113         # 'Context' that's used to 'glue together' the various components
 114         # that make up the application
 115         my ($self, $c) = @_;
 116
 117     $DB::single=1;
 118
 119         # Retrieve all of the book records as book model objects and store in the
 120         # stash where they can be accessed by the TT template
 121         $c->stash->{books} = [$c->model('DB::Books')->all];
 122
 123         # Set the TT template to use.  You will almost always want to do this
 124         # in your action methods.
 125         $c->stash->{template} = 'books/list.tt2';
 126     }
 127
 128 This causes the Perl Debugger to enter "single step mode" when this command is
 129 encountered (it has no effect when Perl is run without the C<-d> flag).
 130
 131 B<NOTE:> The C<DB> here is the Perl Debugger, not the DB model.
 132
 133 To now run the Catalyst development server under the Perl debugger, simply
 134 prepend C<perl -d> to the front of C<script/myapp_server.pl>:
 135
 136     $ perl -d script/myapp_server.pl
 137
 138 This will start the interactive debugger and produce output similar to:
 139
 140     $ perl -d script/myapp_server.pl
 141
 142     Loading DB routines from perl5db.pl version 1.27
 143     Editor support available.
 144
 145     Enter h or `h h' for help, or `man perldebug' for more help.
 146
 147     main::(script/myapp_server.pl:14):      my $debug         = 0;
 148
 149       DB<1>
 150
 151 Press the C<c> key and hit C<Enter> to continue executing the Catalyst
 152 development server under the debugger.  Although execution speed will be
 153 slightly slower than normal, you should soon see the usual Catalyst
 154 startup debug information.
 155
 156 Now point your browser to L<http://localhost:3000/books/list> and log
 157 in.  Once the breakpoint is encountered in the
 158 C<MyApp::Controller::list> method, the console session running the
 159 development server will drop to the Perl debugger prompt:
 160
 161     MyApp::Controller::Books::list(/home/me/MyApp/script/../lib/MyApp/Controller/Books.pm:40):
 162     40:         $c->stash->{books} = [$c->model('DB::Books')->all];
 163
 164       DB<1>
 165
 166 You now have the full Perl debugger at your disposal.  First use the
 167 C<next> feature by typing C<n> to execute the C<all> method on the Book
 168 model (C<n> jumps over method/subroutine calls; you can also use C<s> to
 169 C<single-step> into methods/subroutines):
 170
 171       DB<1> n
 172     SELECT me.id, me.authors, me.title, me.rating FROM books me:
 173     MyApp::Controller::Books::list(/home/me/MyApp/script/../lib/MyApp/Controller/Books.pm:44):
 174     44:         $c->stash->{template} = 'books/list.tt2';
 175
 176       DB<1>
 177
 178 This takes you to the next line of code where the template name is set.
 179 Notice that because we enabled C<DBIC_TRACE=1> earlier, SQL debug
 180 output also shows up in the development server debug information.
 181
 182 Next, list the methods available on our C<Book> model:
 183
 184       DB<1> m $c->model('DB::Books')
 185     ()
 186     (0+
 187     (bool
 188     MODIFY_CODE_ATTRIBUTES
 189     _attr_cache
 190     _collapse_result
 191     _construct_object
 192     _count
 193     _result_class_accessor
 194     _result_source_accessor
 195     all
 196     carp
 197     <lines removed for brevity>
 198
 199       DB<2>
 200
 201 We can also play with the model directly:
 202
 203       DB<2> x ($c->model('DB::Books')->all)[1]->title
 204     SELECT me.id, me.title, me.rating FROM books me:
 205     0  'TCP/IP Illustrated, Volume 1'
 206
 207 This uses the Perl debugger C<x> command to display the title of a book.
 208
 209 Next we inspect the C<books> element of the Catalyst C<stash> (the C<4>
 210 argument to the C<x> command limits the depth of the dump to 4 levels):
 211
 212       DB<3> x 4 $c->stash->{books}
 213     0  ARRAY(0xa8f3b7c)
 214        0  MyApp::Model::DB::Book=HASH(0xb8e702c)
 215           '_column_data' => HASH(0xb8e5e2c)
 216              'id' => 1
 217              'rating' => 5
 218              'title' => 'CCSP SNRS Exam Certification Guide'
 219           '_in_storage' => 1
 220     <lines removed for brevity>
 221
 222 Then enter the C<c> command to continue processing until the next
 223 breakpoint is hit (or the application exits):
 224
 225       DB<4> c
 226     SELECT author.id, author.first_name, author.last_name FROM ...
 227
 228 Finally, press C<Ctrl+C> to break out of the development server.
 229 Because we are running inside the Perl debugger, you will drop to the
 230 debugger prompt.  Press C<q> to exit the debugger and return to your OS
 231 shell prompt:
 232
 233       DB<4> q
 234     $
 235
 236 For more information on using the Perl debugger, please see C<perldebug>
 237 and C<perldebtut>.  You can also type C<h> or C<h h> at the debugger
 238 prompt to view the built-in help screens.
 239
 240
 241 =head1 DEBUGGING MODULES FROM CPAN
 242
 243 Although the techniques discussed above work well for code you are
 244 writing, what if you want to use print/log/warn messages or set
 245 breakpoints in code that you have installed from CPAN (or in module that
 246 ship with Perl)?  One helpful approach is to place a copy of the module
 247 inside the C<lib> directory of your Catalyst project.  When Catalyst
 248 loads, it will load from inside your C<lib> directory first, only
 249 turning to the global modules if a local copy cannot be found.  You can
 250 then make modifications such as adding a C<$DB::single=1> to the local
 251 copy of the module without risking the copy in the original location.
 252 This can also be a great way to "locally override" bugs in modules while
 253 you wait for a fix on CPAN.
 254
 255
 256 Matt Trout has suggested the following shortcut to create a local
 257 copy of an installed module:
 258
 259     mkdir -p lib/Module; cp `perldoc -l Module::Name` lib/Module/
 260
 261 Note: If you are following along in Ubuntu, you will need to install
 262 the C<perl-doc> package to use the C<perldoc> command.  Use
 263 C<sudo apt-get install perl-doc> to do that.
 264
 265 For example, you could make a copy of
 266 L<Catalyst::Plugin::Authentication|Catalyst::Plugin::Authentication>
 267 with the following command:
 268
 269     mkdir -p lib/Catalyst/Plugin; cp \
 270         `perldoc -l Catalyst::Plugin::Authentication` lib/Catalyst/Plugin
 271
 272 You can then use the local copy inside your project to place logging
 273 messages and/or breakpoints for further study of that module.
 274
 275 B<Note:> Matt has also suggested the following tips for Perl
 276 debugging:
 277
 278 =over 4
 279
 280 =item *
 281
 282 Check the version of an installed module:
 283
 284     perl -ME<lt>mod_nameE<gt> -e '"print $E<lt>mod_nameE<gt>::VERSION\n"'
 285
 286 For example:
 287
 288     $ perl -MCatalyst::Plugin::Authentication -e \
 289         'print $Catalyst::Plugin::Authentication::VERSION;'
 290     0.07
 291
 292 =item *
 293
 294 Check if a modules contains a given method:
 295
 296     perl -MModule::Name -e 'print Module::Name->can("method");'
 297
 298 For example:
 299
 300     $ perl -MCatalyst::Plugin::Authentication -e \
 301         'print Catalyst::Plugin::Authentication->can("user");'
 302     CODE(0x9c8db2c)
 303
 304 If the method exists, the Perl C<can> method returns a coderef.
 305 Otherwise, it returns undef and nothing will be printed.
 306
 307 =back
 308
 309
 310 =head1 TT DEBUGGING
 311
 312 If you run into issues during the rendering of your template, it might
 313 be helpful to enable TT C<DEBUG> options.  You can do this in a Catalyst
 314 environment by adding a C<DEBUG> line to the C<__PACKAGE__->config>
 315 declaration in C<lib/MyApp/View/TT.pm>:
 316
 317     __PACKAGE__->config({
 318         TEMPLATE_EXTENSION => '.tt2',
 319         DEBUG              => 'undef',
 320     });
 321
 322 There are a variety of options you can use, such as 'undef', 'all',
 323 'service', 'context', 'parser' and 'provider'.  See
 324 L<Template::Constants|Template::Constants> for more information
 325 (remove the C<DEBUG_> portion of the name shown in the TT docs and
 326 convert to lower case for use inside Catalyst).
 327
 328 B<NOTE:> B<Please be sure to disable TT debug options before continuing
 329 with the tutorial> (especially the 'undef' option -- leaving this
 330 enabled will conflict with several of the conventions used by this
 331 tutorial to leave some variables undefined on purpose).
 332
 333
 334 =head1 AUTHOR
 335
 336 Kennedy Clark, C<hkclark@gmail.com>
 337
 338 Please report any errors, issues or suggestions to the author.  The
 339 most recent version of the Catalyst Tutorial can be found at
 340 L<http://dev.catalyst.perl.org/repos/Catalyst/Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/>.
 341
 342 Copyright 2006-2008, Kennedy Clark, under Creative Commons License
 343 (L<http://creativecommons.org/licenses/by-sa/3.0/us/>).