1Catalyst::Manual::TutorUisaelr::C0o7n_tDreibbuugtCgeaidtnagPl(ey3rs)lt:D:oMcaunmueanlt:a:tTiuotnorial::07_Debugging(3)
2
3
4

NAME

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

OVERVIEW

10       This is Chapter 7 of 10 for the Catalyst tutorial.
11
12       Tutorial Overview
13
14       1.  Introduction
15
16       2.  Catalyst Basics
17
18       3.  More Catalyst Basics
19
20       4.  Basic CRUD
21
22       5.  Authentication
23
24       6.  Authorization
25
26       7.  07_Debugging
27
28       8.  Testing
29
30       9.  Advanced CRUD
31
32       10. Appendices
33

DESCRIPTION

35       This chapter of the tutorial takes a brief look at the primary options
36       available for troubleshooting Catalyst applications.
37
38       Source code for the tutorial in included in the /home/catalyst/Final
39       directory of the Tutorial Virtual machine (one subdirectory per
40       chapter).  There are also instructions for downloading the code in
41       Catalyst::Manual::Tutorial::01_Intro.
42
43       Note that when it comes to debugging and troubleshooting, there are two
44       camps:
45
46       ·   Fans of "log" and "print" statements embedded in the code.
47
48       ·   Fans of interactive debuggers.
49
50       Catalyst is able to easily accommodate both styles of debugging.
51

LOG STATEMENTS

53       Folks in the former group can use Catalyst's "$c->log" facility.  (See
54       Catalyst::Log for more detail.) For example, if you add the following
55       code to a controller action method:
56
57           $c->log->info("Starting the foreach loop here");
58
59           $c->log->debug("Value of \$id is: ".$id);
60
61       Then the Catalyst development server will display your message along
62       with the other debug output. To accomplish the same thing in a TT
63       template view use:
64
65           [% c.log.debug("This is a test log message") %]
66
67       As with many other logging facilities, a method is defined for each of
68       the following "logging levels" (in increasing order of
69       severity/importance):
70
71           $c->log->debug
72           $c->log->info
73           $c->log->warn
74           $c->log->error
75           $c->log->fatal
76
77       You can also use Data::Dumper in both Catalyst code and in TT
78       templates.  For use in Catalyst code:
79
80        use Data::Dumper;
81        $c->log->debug("\$var is: ".Dumper($c->stash->{something}));
82
83       and TT templates:
84
85        [% USE Dumper ; Dumper.dump(c.stash.something) %].
86
87       NOTE: Whether you are a logging fanatic or not, we strongly recommend
88       that you take advantage of Log::Log4perl or Log::Dispatch.  It's easy
89       to use Catalyst::Log with either of these and they will provide a huge
90       amount of extra functionality that you will want in virtually every
91       production application you run or support.
92

RUNNING CATALYST UNDER THE PERL DEBUGGER

94       Members of the interactive-debugger fan club will also be at home with
95       Catalyst applications.  One approach to this style of Perl debugging is
96       to embed breakpoints in your code.  For example, open
97       "lib/MyApp/Controller/Books.pm" in your editor and add the
98       "DB::single=1" line as follows inside the "list" method (I like to
99       "left-justify" my debug statements so I don't forget to remove them,
100       but you can obviously indent them if you prefer):
101
102           sub list :Local {
103               # Retrieve the usual Perl OO '$self' for this object. $c is the Catalyst
104               # 'Context' that's used to 'glue together' the various components
105               # that make up the application
106               my ($self, $c) = @_;
107
108           $DB::single=1;
109
110               # Retrieve all of the book records as book model objects and store in the
111               # stash where they can be accessed by the TT template
112               $c->stash->{books} = [$c->model('DB::Book')->all];
113
114               # Set the TT template to use.  You will almost always want to do this
115               # in your action methods.
116               $c->stash->{template} = 'books/list.tt2';
117           }
118
119       This causes the Perl Debugger to enter "single step mode" when this
120       command is encountered (it has no effect when Perl is run without the
121       "-d" flag).
122
123       NOTE: The "DB" here is the Perl Debugger, not the DB model.
124
125       If you haven't done it already, enable SQL logging as before:
126
127           $ export DBIC_TRACE=1
128
129       To now run the Catalyst development server under the Perl debugger,
130       simply prepend "perl -d" to the front of "script/myapp_server.pl":
131
132           $ perl -d script/myapp_server.pl
133
134       This will start the interactive debugger and produce output similar to:
135
136           $ perl -d script/myapp_server.pl
137
138           Loading DB routines from perl5db.pl version 1.3
139           Editor support available.
140
141           Enter h or `h h' for help, or `man perldebug' for more help.
142
143           main::(script/myapp_server.pl:16):      my $debug         = 0;
144
145             DB<1>
146
147       Press the "c" key and hit "Enter" to continue executing the Catalyst
148       development server under the debugger.  Although execution speed will
149       be slightly slower than normal, you should soon see the usual Catalyst
150       startup debug information.
151
152       Now point your browser to <http://localhost:3000/books/list> and log
153       in.  Once the breakpoint is encountered in the
154       "MyApp::Controller::list" method, the console session running the
155       development server will drop to the Perl debugger prompt:
156
157           MyApp::Controller::Books::list(/home/catalyst/MyApp/script/../lib/MyApp/Controller/Books.pm:48):
158           48:         $c->stash->{books} = [$c->model('DB::Book')->all];
159
160             DB<1>
161
162       You now have the full Perl debugger at your disposal.  First use the
163       "next" feature by typing "n" to execute the "all" method on the Book
164       model ("n" jumps over method/subroutine calls; you can also use "s" to
165       "single-step" into methods/subroutines):
166
167             DB<1> n
168           SELECT me.id, me.title, me.rating, me.created, me.updated FROM book me:
169           MyApp::Controller::Books::list(/home/catalyst/MyApp/script/../lib/MyApp/Controller/Books.pm:53):
170           53:         $c->stash->{template} = 'books/list.tt2';
171
172             DB<1>
173
174       This takes you to the next line of code where the template name is set.
175       Notice that because we enabled "DBIC_TRACE=1" earlier, SQL debug output
176       also shows up in the development server debug information.
177
178       Next, list the methods available on our "Book" model:
179
180             DB<1> m $c->model('DB::Book')
181           ()
182           (0+
183           (bool
184           __result_class_accessor
185           __source_handle_accessor
186           _add_alias
187           __bool
188           _build_unique_query
189           _calculate_score
190           _collapse_cond
191           <lines removed for brevity>
192
193             DB<2>
194
195       We can also play with the model directly:
196
197             DB<2> x ($c->model('DB::Book')->all)[1]->title
198           SELECT me.id, me.title, me.rating, me.created, me.updated FROM book me:
199           0  'TCP/IP Illustrated, Volume 1'
200
201       This uses the Perl debugger "x" command to display the title of a book.
202
203       Next we inspect the "books" element of the Catalyst "stash" (the 4
204       argument to the "x" command limits the depth of the dump to 4 levels):
205
206             DB<3> x 4 $c->stash->{books}
207           0  ARRAY(0xa8f3b7c)
208              0  MyApp::Model::DB::Book=HASH(0xb8e702c)
209                 '_column_data' => HASH(0xb8e5e2c)
210                    'created' => '2009-05-08 10:19:46'
211                    'id' => 1
212                    'rating' => 5
213                    'title' => 'CCSP SNRS Exam Certification Guide'
214                    'updated' => '2009-05-08 10:19:46'
215                 '_in_storage' => 1
216           <lines removed for brevity>
217
218       Then enter the "c" command to continue processing until the next
219       breakpoint is hit (or the application exits):
220
221             DB<4> c
222           SELECT author.id, author.first_name, author.last_name FROM ...
223
224       Finally, press "Ctrl+C" to break out of the development server.
225       Because we are running inside the Perl debugger, you will drop to the
226       debugger prompt.
227
228           ^CCatalyst::Engine::HTTP::run(/usr/local/share/perl/5.10.0/Catalyst/Engine/HTTP.pm:260):
229           260:            while ( accept( Remote, $daemon ) ) {
230
231           DB<4>
232
233       Finally, press "q" to exit the debugger and return to your OS shell
234       prompt:
235
236             DB<4> q
237           $
238
239       For more information on using the Perl debugger, please see "perldebug"
240       and "perldebtut".  For those daring souls out there, you can dive down
241       even deeper into the magical depths of this fine debugger by checking
242       out "perldebguts".
243
244       You can also type "h" or "h h" at the debugger prompt to view the
245       built-in help screens.
246
247       For an excellent book covering all aspects of the Perl debugger, we
248       highly recommend reading 'Pro Perl Debugging' by Richard Foley.
249
250       Oh yeah, before you forget, be sure to remove the "DB::single=1" line
251       you added above in "lib/MyApp/Controller/Books.pm".
252

DEBUGGING MODULES FROM CPAN

254       Although the techniques discussed above work well for code you are
255       writing, what if you want to use print/log/warn messages or set
256       breakpoints in code that you have installed from CPAN (or in module
257       that ship with Perl)?  One helpful approach is to place a copy of the
258       module inside the "lib" directory of your Catalyst project.  When
259       Catalyst loads, it will load from inside your "lib" directory first,
260       only turning to the global modules if a local copy cannot be found.
261       You can then make modifications such as adding a "$DB::single=1" to the
262       local copy of the module without risking the copy in the original
263       location.  This can also be a great way to "locally override" bugs in
264       modules while you wait for a fix on CPAN.
265
266       Matt Trout has suggested the following shortcut to create a local copy
267       of an installed module:
268
269           mkdir -p lib/Module; cp `perldoc -l Module::Name` lib/Module/
270
271       Note: If you are following along in Debian 6 or Ubuntu, you will need
272       to install the "perl-doc" package to use the "perldoc" command.  Use
273       "sudo aptitude install perl-doc" to do that.
274
275       For example, you could make a copy of Catalyst::Plugin::Authentication
276       with the following command:
277
278           mkdir -p lib/Catalyst/Plugin; cp \
279               `perldoc -l Catalyst::Plugin::Authentication` lib/Catalyst/Plugin
280
281       You can then use the local copy inside your project to place logging
282       messages and/or breakpoints for further study of that module.
283
284       Note: Matt has also suggested the following tips for Perl debugging:
285
286       ·   Check the version of an installed module:
287
288               perl -M<mod_name> -e 'print "$<mod_name>::VERSION\n"'
289
290           For example:
291
292               $ perl -MCatalyst::Plugin::Authentication -e \
293                   'print $Catalyst::Plugin::Authentication::VERSION;'
294               0.07
295
296           and if you are using bash aliases:
297
298               alias pmver="perl -le '\$m = shift; eval qq(require \$m) \
299                   or die qq(module \"\$m\" is not installed\\n); \
300                   print \$m->VERSION'"
301
302       ·   Check if a modules contains a given method:
303
304               perl -MModule::Name -e 'print Module::Name->can("method");'
305
306           For example:
307
308               $ perl -MCatalyst::Plugin::Authentication -e \
309                   'print Catalyst::Plugin::Authentication->can("user");'
310               CODE(0x9c8db2c)
311
312           If the method exists, the Perl "can" method returns a coderef.
313           Otherwise, it returns undef and nothing will be printed.
314

TT DEBUGGING

316       If you run into issues during the rendering of your template, it might
317       be helpful to enable TT "DEBUG" options.  You can do this in a Catalyst
318       environment by adding a "DEBUG" line to the "__PACKAGE__-"config>
319       declaration in "lib/MyApp/View/HTML.pm":
320
321           __PACKAGE__->config({
322               TEMPLATE_EXTENSION => '.tt2',
323               DEBUG              => 'undef',
324           });
325
326       There are a variety of options you can use, such as 'undef', 'all',
327       'service', 'context', 'parser' and 'provider'.  See Template::Constants
328       for more information (remove the "DEBUG_" portion of the name shown in
329       the TT docs and convert to lower case for use inside Catalyst).
330
331       NOTE: Please be sure to disable TT debug options before continuing with
332       the tutorial (especially the 'undef' option -- leaving this enabled
333       will conflict with several of the conventions used by this tutorial to
334       leave some variables undefined on purpose).
335
336       Happy debugging.
337
338       You can jump to the next chapter of the tutorial here: Testing
339

AUTHOR

341       Kennedy Clark, "hkclark@gmail.com"
342
343       Feel free to contact the author for any errors or suggestions, but the
344       best way to report issues is via the CPAN RT Bug system at
345       <https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Manual>.
346
347       Copyright 2006-2011, Kennedy Clark, under the Creative Commons
348       Attribution Share-Alike License Version 3.0
349       (<https://creativecommons.org/licenses/by-sa/3.0/us/>).
350
351
352
353perl v5.30.1                      20C2a0t-a0l1y-s2t9::Manual::Tutorial::07_Debugging(3)