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.
81 Folks in the former group can use Catalyst's C<$c-E<gt>log> facility.
82 (See L<Catalyst::Log> for more detail.) For example, if you add the
83 following code to a controller action method:
85 $c->log->info("Starting the foreach loop here");
87 $c->log->debug("Value of \$id is: ".$id);
89 Then the Catalyst development server will display your message along
90 with the other debug output. To accomplish the same thing in a TTSite
93 [% Catalyst.log.debug("This is a test log message") %]
95 You can also use L<Data::Dumper|Data::Dumper> in both Catalyst code
96 (C<use Data::Dumper; $c-E<gt>log-E<gt>debug("\$var is: ".Dumper($var));)>)
97 and TT templates (C<[% Dumper.dump(book) %]>.
99 =head1 RUNNING CATALYST UNDER THE PERL DEBUGGER
101 Members of the interactive-debugger fan club will also be at home with
102 Catalyst applications. One approach to this style of Perl debugging is
103 to embed breakpoints in your code. For example, open
104 C<lib/MyApp/Controller/Books.pm> in your editor and add the
105 C<DB::single=1> line as follows inside the C<list> method (I like to
106 "left-justify" my debug statements so I don't forget to remove them, but
107 you can obviously indent them if you prefer):
110 # Retrieve the usual Perl OO '$self' for this object. $c is the Catalyst
111 # 'Context' that's used to 'glue together' the various components
112 # that make up the application
117 # Retrieve all of the book records as book model objects and store in the
118 # stash where they can be accessed by the TT template
119 $c->stash->{books} = [$c->model('DB::Books')->all];
121 # Set the TT template to use. You will almost always want to do this
122 # in your action methods.
123 $c->stash->{template} = 'books/list.tt2';
126 This causes the Perl Debugger to enter "single step mode" when this command is
127 encountered (it has no effect when Perl is run without the C<-d> flag).
129 B<NOTE:> The C<DB> here is the Perl Debugger, not the DB model.
131 To now run the Catalyst development server under the Perl debugger, simply
132 prepend C<perl -d> to the front of C<script/myapp_server.pl>:
134 $ perl -d script/myapp_server.pl
136 This will start the interactive debugger and produce output similar to:
138 $ perl -d script/myapp_server.pl
140 Loading DB routines from perl5db.pl version 1.27
141 Editor support available.
143 Enter h or `h h' for help, or `man perldebug' for more help.
145 main::(script/myapp_server.pl:14): my $debug = 0;
149 Press the C<c> key and hit C<Enter> to continue executing the Catalyst
150 development server under the debugger. Although execution speed will be
151 slightly slower than normal, you should soon see the usual Catalyst
152 startup debug information.
154 Now point your browser to L<http://localhost:3000/books/list> and log
155 in. Once the breakpoint is encountered in the
156 C<MyApp::Controller::list> method, the console session running the
157 development server will drop to the Perl debugger prompt:
159 MyApp::Controller::Books::list(/home/me/MyApp/script/../lib/MyApp/Controller/Books.pm:40):
160 40: $c->stash->{books} = [$c->model('DB::Books')->all];
164 You now have the full Perl debugger at your disposal. First use the
165 C<next> feature by typing C<n> to execute the C<all> method on the Book
166 model (C<n> jumps over method/subroutine calls; you can also use C<s> to
167 C<single-step> into methods/subroutines):
170 SELECT me.id, me.authors, me.title, me.rating FROM books me:
171 MyApp::Controller::Books::list(/home/me/MyApp/script/../lib/MyApp/Controller/Books.pm:44):
172 44: $c->stash->{template} = 'books/list.tt2';
176 This takes you to the next line of code where the template name is set.
177 Notice that because we enabled C<DBIC_TRACE=1> earlier, SQL debug
178 output also shows up in the development server debug information.
180 Next, list the methods available on our C<Book> model:
182 DB<1> m $c->model('DB::Books')
186 MODIFY_CODE_ATTRIBUTES
191 _result_class_accessor
192 _result_source_accessor
195 <lines removed for brevity>
199 We can also play with the model directly:
201 DB<2> x ($c->model('DB::Books')->all)[1]->title
202 SELECT me.id, me.title, me.rating FROM books me:
203 0 'TCP/IP Illustrated, Volume 1'
205 This uses the Perl debugger C<x> command to display the title of a book.
207 Next we inspect the C<books> element of the Catalyst C<stash> (the C<4>
208 argument to the C<x> command limits the depth of the dump to 4 levels):
210 DB<3> x 4 $c->stash->{books}
212 0 MyApp::Model::DB::Book=HASH(0xb8e702c)
213 '_column_data' => HASH(0xb8e5e2c)
216 'title' => 'CCSP SNRS Exam Certification Guide'
218 <lines removed for brevity>
220 Then enter the C<c> command to continue processing until the next
221 breakpoint is hit (or the application exits):
224 SELECT author.id, author.first_name, author.last_name FROM ...
226 Finally, press C<Ctrl+C> to break out of the development server.
227 Because we are running inside the Perl debugger, you will drop to the
228 debugger prompt. Press C<q> to exit the debugger and return to your OS
234 For more information on using the Perl debugger, please see C<perldebug>
235 and C<perldebtut>. You can also type C<h> or C<h h> at the debugger
236 prompt to view the built-in help screens.
239 =head1 DEBUGGING MODULES FROM CPAN
241 Although the techniques discussed above work well for code you are
242 writing, what if you want to use print/log/warn messages or set
243 breakpoints in code that you have installed from CPAN (or in module that
244 ship with Perl)? One helpful approach is to place a copy of the module
245 inside the C<lib> directory of your Catalyst project. When Catalyst
246 loads, it will load from inside your C<lib> directory first, only
247 turning to the global modules if a local copy cannot be found. You can
248 then make modifications such as adding a C<$DB::single=1> to the local
249 copy of the module without risking the copy in the original location.
250 This can also be a great way to "locally override" bugs in modules while
251 you wait for a fix on CPAN.
254 Matt Trout has suggested the following shortcut to create a local
255 copy of an installed module:
257 mkdir -p lib/Module; cp `perldoc -l Module::Name` lib/Module/
259 Note: If you are following along in Ubuntu, you will need to install
260 the C<perl-doc> package to use the C<perldoc> command. Use
261 C<sudo apt-get install perl-doc> to do that.
263 For example, you could make a copy of
264 L<Catalyst::Plugin::Authentication|Catalyst::Plugin::Authentication>
265 with the following command:
267 mkdir -p lib/Catalyst/Plugin; cp \
268 `perldoc -l Catalyst::Plugin::Authentication` lib/Catalyst/Plugin
270 You can then use the local copy inside your project to place logging
271 messages and/or breakpoints for further study of that module.
273 B<Note:> Matt has also suggested the following tips for Perl
280 Check the version of an installed module:
282 perl -MModule::Name -e 'print $Module::Name::VERSION;'
286 $ perl -MCatalyst::Plugin::Authentication -e \
287 'print $Catalyst::Plugin::Authentication::VERSION;'
292 Check if a modules contains a given method:
294 perl -MModule::Name -e 'print Module::Name->can("method");'
298 $ perl -MCatalyst::Plugin::Authentication -e \
299 'print Catalyst::Plugin::Authentication->can("user");'
302 If the method exists, the Perl C<can> method returns a coderef.
303 Otherwise, it returns undef and nothing will be printed.
310 Kennedy Clark, C<hkclark@gmail.com>
312 Please report any errors, issues or suggestions to the author. The
313 most recent version of the Catalyst Tutorial can be found at
314 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Manual/lib/Catalyst/Manual/Tutorial/>.
316 Copyright 2006-2008, Kennedy Clark, under Creative Commons License
317 (L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).