File: 07_Debugging.pod

package info (click to toggle)
libcatalyst-manual-perl 5.9004-1
  • links: PTS, VCS
  • area: main
  • in suites: wheezy
  • size: 820 kB
  • sloc: perl: 1,974; makefile: 2
file content (402 lines) | stat: -rw-r--r-- 12,512 bytes parent folder | download | duplicates (4)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
=head1 NAME

Catalyst::Manual::Tutorial::07_Debugging - Catalyst Tutorial - Chapter 7: Debugging


=head1 OVERVIEW

This is B<Chapter 7 of 10> for the Catalyst tutorial.

L<Tutorial Overview|Catalyst::Manual::Tutorial>

=over 4

=item 1

L<Introduction|Catalyst::Manual::Tutorial::01_Intro>

=item 2

L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics>

=item 3

L<More Catalyst Basics|Catalyst::Manual::Tutorial::03_MoreCatalystBasics>

=item 4

L<Basic CRUD|Catalyst::Manual::Tutorial::04_BasicCRUD>

=item 5

L<Authentication|Catalyst::Manual::Tutorial::05_Authentication>

=item 6

L<Authorization|Catalyst::Manual::Tutorial::06_Authorization>

=item 7

B<07_Debugging>

=item 8

L<Testing|Catalyst::Manual::Tutorial::08_Testing>

=item 9

L<Advanced CRUD|Catalyst::Manual::Tutorial::09_AdvancedCRUD>

=item 10

L<Appendices|Catalyst::Manual::Tutorial::10_Appendices>

=back


=head1 DESCRIPTION

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 * 

Fans of C<log> and C<print> statements embedded in the code.

=item * 

Fans of interactive debuggers.

=back

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> for more detail.) For example, if you add the
following code to a controller action method:

    $c->log->info("Starting the foreach loop here");
    
    $c->log->debug("Value of \$id is: ".$id);

Then the Catalyst development server will display your message along
with the other debug output. To accomplish the same thing in a TT
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
severity/importance):

    $c->log->debug
    $c->log->info
    $c->log->warn
    $c->log->error
    $c->log->fatal

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

Members of the interactive-debugger fan club will also be at home with
Catalyst applications.  One approach to this style of Perl debugging is
to embed breakpoints in your code.  For example, open
C<lib/MyApp/Controller/Books.pm> in your editor and add the
C<DB::single=1> line as follows inside the C<list> method (I like to
"left-justify" my debug statements so I don't forget to remove them, but
you can obviously indent them if you prefer):

    sub list :Local {
        # Retrieve the usual Perl OO '$self' for this object. $c is the Catalyst
        # '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).

B<NOTE:> The C<DB> here is the Perl Debugger, not the DB model.

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>:

    $ perl -d script/myapp_server.pl

This will start the interactive debugger and produce output similar to:

    $ 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> 

Press the C<c> key and hit C<Enter> to continue executing the Catalyst
development server under the debugger.  Although execution speed will be
slightly slower than normal, you should soon see the usual Catalyst
startup debug information.

Now point your browser to L<http://localhost:3000/books/list> and log
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/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
C<next> feature by typing C<n> to execute the C<all> method on the Book
model (C<n> jumps over method/subroutine calls; you can also use C<s> to
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/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.

Next, list the methods available on our C<Book> model:

      DB<1> m $c->model('DB::Book')
    ()
    (0+
    (bool
    __result_class_accessor
    __source_handle_accessor
    _add_alias
    __bool
    _build_unique_query
    _calculate_score
    _collapse_cond
    <lines removed for brevity>
    
      DB<2>

We can also play with the model directly:

      DB<2> x ($c->model('DB::Book')->all)[1]->title
    SELECT me.id, me.title, me.rating, me.created, me.updated FROM book me:
    0  'TCP/IP Illustrated, Volume 1'

This uses the Perl debugger C<x> command to display the title of a book.

Next we inspect the C<books> element of the Catalyst C<stash> (the C<4>
argument to the C<x> command limits the depth of the dump to 4 levels):

      DB<3> x 4 $c->stash->{books}
    0  ARRAY(0xa8f3b7c)
       0  MyApp::Model::DB::Book=HASH(0xb8e702c)
          '_column_data' => HASH(0xb8e5e2c)
             'created' => '2009-05-08 10:19:46'
             'id' => 1
             'rating' => 5
             'title' => 'CCSP SNRS Exam Certification Guide'
             'updated' => '2009-05-08 10:19:46'
          '_in_storage' => 1
    <lines removed for brevity>

Then enter the C<c> command to continue processing until the next
breakpoint is hit (or the application exits):

      DB<4> c
    SELECT author.id, author.first_name, author.last_name FROM ...

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.

    ^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:

      DB<4> q
    $

For more information on using the Perl debugger, please see C<perldebug>
and C<perldebtut>.  For those daring souls out there, you can dive down
even deeper into the magical depths of this fine debugger by checking
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.

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
you wait for a fix on CPAN.

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 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> with the following command:

    mkdir -p lib/Catalyst/Plugin; cp \
        `perldoc -l Catalyst::Plugin::Authentication` lib/Catalyst/Plugin

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:

=over 4

=item * 

Check the version of an installed module:

    perl -M<mod_name> -e 'print "$<mod_name>::VERSION\n"'

For example:

    $ perl -MCatalyst::Plugin::Authentication -e \
        'print $Catalyst::Plugin::Authentication::VERSION;'
    0.07

and if you are using bash aliases:

    alias pmver="perl -le '\$m = shift; eval qq(require \$m) \
        or die qq(module \"\$m\" is not installed\\n); \
        print \$m->VERSION'"

=item * 

Check if a modules contains a given method:

    perl -MModule::Name -e 'print Module::Name->can("method");'

For example:

    $ perl -MCatalyst::Plugin::Authentication -e \
        'print Catalyst::Plugin::Authentication->can("user");'
    CODE(0x9c8db2c)

If the method exists, the Perl C<can> method returns a coderef.
Otherwise, it returns undef and nothing will be printed.

=back


=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>
declaration in C<lib/MyApp/View/HTML.pm>:

    __PACKAGE__->config({
        TEMPLATE_EXTENSION => '.tt2',
        DEBUG              => 'undef',
    });

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
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
L<https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Manual>.

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/>).