3 Catalyst::Manual::Tutorial::Debugging - Catalyst Tutorial - Part 7: Debugging
8 This is B<Part 7 of 10> for the Catalyst tutorial.
10 L<Tutorial Overview|Catalyst::Manual::Tutorial>
16 L<Introduction|Catalyst::Manual::Tutorial::Intro>
20 L<Catalyst Basics|Catalyst::Manual::Tutorial::CatalystBasics>
24 L<More Catalyst Basics|Catalyst::Manual::Tutorial::MoreCatalystBasics>
28 L<Basic CRUD|Catalyst::Manual::Tutorial::BasicCRUD>
32 L<Authentication|Catalyst::Manual::Tutorial::Authentication>
36 L<Authorization|Catalyst::Manual::Tutorial::Authorization>
44 L<Testing|Catalyst::Manual::Tutorial::Testing>
48 L<Advanced CRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
52 L<Appendices|Catalyst::Manual::Tutorial::Appendices>
59 This part of the tutorial takes a brief look at the primary options
60 available for troubleshooting Catalyst applications.
62 Note that when it comes to debugging and troubleshooting, there are two
69 Fans of C<log> and C<print> statements embedded in the code.
73 Fans of interactive debuggers.
77 Catalyst is able to easily accommodate both styles of debugging.
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:
86 $c->log->info("Starting the foreach loop here");
88 $c->log->debug("Value of \$id is: ".$id);
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
94 [% c.log.debug("This is a test log message") %]
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) %]>.
101 =head1 RUNNING CATALYST UNDER THE PERL DEBUGGER
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):
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
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];
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';
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).
131 B<NOTE:> The C<DB> here is the Perl Debugger, not the DB model.
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>:
136 $ perl -d script/myapp_server.pl
138 This will start the interactive debugger and produce output similar to:
140 $ perl -d script/myapp_server.pl
142 Loading DB routines from perl5db.pl version 1.27
143 Editor support available.
145 Enter h or `h h' for help, or `man perldebug' for more help.
147 main::(script/myapp_server.pl:14): my $debug = 0;
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.
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:
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];
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):
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';
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.
182 Next, list the methods available on our C<Book> model:
184 DB<1> m $c->model('DB::Books')
188 MODIFY_CODE_ATTRIBUTES
193 _result_class_accessor
194 _result_source_accessor
197 <lines removed for brevity>
201 We can also play with the model directly:
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'
207 This uses the Perl debugger C<x> command to display the title of a book.
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):
212 DB<3> x 4 $c->stash->{books}
214 0 MyApp::Model::DB::Book=HASH(0xb8e702c)
215 '_column_data' => HASH(0xb8e5e2c)
218 'title' => 'CCSP SNRS Exam Certification Guide'
220 <lines removed for brevity>
222 Then enter the C<c> command to continue processing until the next
223 breakpoint is hit (or the application exits):
226 SELECT author.id, author.first_name, author.last_name FROM ...
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
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.
241 =head1 DEBUGGING MODULES FROM CPAN
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.
256 Matt Trout has suggested the following shortcut to create a local
257 copy of an installed module:
259 mkdir -p lib/Module; cp `perldoc -l Module::Name` lib/Module/
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.
265 For example, you could make a copy of
266 L<Catalyst::Plugin::Authentication|Catalyst::Plugin::Authentication>
267 with the following command:
269 mkdir -p lib/Catalyst/Plugin; cp \
270 `perldoc -l Catalyst::Plugin::Authentication` lib/Catalyst/Plugin
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.
275 B<Note:> Matt has also suggested the following tips for Perl
282 Check the version of an installed module:
284 perl -ME<lt>mod_nameE<gt> -e '"print $E<lt>mod_nameE<gt>::VERSION\n"'
288 $ perl -MCatalyst::Plugin::Authentication -e \
289 'print $Catalyst::Plugin::Authentication::VERSION;'
294 Check if a modules contains a given method:
296 perl -MModule::Name -e 'print Module::Name->can("method");'
300 $ perl -MCatalyst::Plugin::Authentication -e \
301 'print Catalyst::Plugin::Authentication->can("user");'
304 If the method exists, the Perl C<can> method returns a coderef.
305 Otherwise, it returns undef and nothing will be printed.
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>:
317 __PACKAGE__->config({
318 TEMPLATE_EXTENSION => '.tt2',
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).
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).
336 Kennedy Clark, C<hkclark@gmail.com>
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/trunk/Catalyst-Manual/lib/Catalyst/Manual/Tutorial/>.
342 Copyright 2006-2008, Kennedy Clark, under Creative Commons License
343 (L<http://creativecommons.org/licenses/by-sa/3.0/us/>).