3 Catalyst::Manual::Tutorial::Debugging - Catalyst Tutorial - Part 6: Debugging
7 This is B<Part 6 of 9> for the Catalyst tutorial.
9 L<Tutorial Overview|Catalyst::Manual::Tutorial>
15 L<Introduction|Catalyst::Manual::Tutorial::Intro>
19 L<Catalyst Basics|Catalyst::Manual::Tutorial::CatalystBasics>
23 L<Basic CRUD|Catalyst::Manual::Tutorial_BasicCRUD>
27 L<Authentication|Catalyst::Manual::Tutorial::Authentication>
31 L<Authorization|Catalyst::Manual::Tutorial::Authorization>
39 L<Testing|Catalyst::Manual::Tutorial::Testing>
43 L<AdvancedCRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
47 L<Appendices|Catalyst::Manual::Tutorial::Appendices>
54 This part of the tutorial takes a brief look at the primary options
55 available for troubleshooting Catalyst applications.
57 Note that when it comes to debugging and troubleshooting, there are two
64 Fans of C<log> and C<print> statements embedded in the code.
68 Fans of interactive debuggers.
72 Catalyst is able to easily accommodate both styles of debugging.
76 Folks in the former group can use Catalyst's C<$c-E<gt>log> facility.
77 (See L<Catalyst::Log> for more detail.) For example, if you add the
78 following code to a controller action method:
80 $c->log->info("Starting the foreach loop here");
82 $c->log->debug("Value of $id is: ".$id);
84 Then the Catalyst development server will display your message along
85 with the other debug output. To accomplish the same thing in a TTSite
88 [% Catalyst.log.debug("This is a test log message") %]
90 You can also use L<Data::Dumper|Data::Dumper> in both Catalyst code
91 (C<use Data::Dumper; $c-E<gt>log-E<gt>debug("$var is: ".Dumper($var));)>)
92 and TT templates (C<[% Dumper.dump(book) %]>.
94 =head1 RUNNING CATALYST UNDER THE PERL DEBUGGER
96 Members of the interactive-debugger fan club will also be at home with
97 Catalyst applications. One approach to this style of Perl debugging is
98 to embed breakpoints in your code. For example, open
99 C<lib/MyApp/Controller/Books.pm> in your editor and add the
100 C<DB::single=1> line as follows inside the C<list> method (I like to
101 "left-justify" my debug statements so I don't forget to remove them, but
102 you can obviously indent them if you prefer):
105 # Retrieve the usual perl OO '$self' for this object. $c is the Catalyst
106 # 'Context' that's used to 'glue together' the various components
107 # that make up the application
112 # Retrieve all of the book records as book model objects and store in the
113 # stash where they can be accessed by the TT template
114 $c->stash->{books} = [$c->model('MyAppDB::Book')->all];
116 # Set the TT template to use. You will almost always want to do this
117 # in your action methods.
118 $c->stash->{template} = 'books/list.tt2';
121 This causes the Perl Debugger to enter "single step mode" when this command is
122 encountered (it has no effect when Perl is run without the C<-d> flag).
124 To now run the Catalyst development server under the Perl debugger, simply
125 prepend C<perl -d> to the front of C<script/myapp_server.pl>:
127 $ perl -d script/myapp_server.pl
129 This will start the interactive debugger and produce output similar to:
131 $ perl -d script/myapp_server.pl
133 Loading DB routines from perl5db.pl version 1.27
134 Editor support available.
136 Enter h or `h h' for help, or `man perldebug' for more help.
138 main::(script/myapp_server.pl:14): my $debug = 0;
142 Press the C<c> key and hit C<Enter> to continue executing the Catalyst
143 development server under the debugger. Although execution speed will be
144 slightly slower than normal, you should soon see the usual Catalyst
145 startup debug information.
147 Now point your browser to L<http://localhost:3000/books/list> and log
148 in. Once the breakpoint is encountered in the
149 C<MyApp::Controller::list> method, the console session running the
150 development server will drop to the Perl debugger prompt:
152 MyApp::Controller::Books::list(/home/me/MyApp/script/../lib/MyApp/Controller/Books.pm:40):
153 40: $c->stash->{books} = [$c->model('MyAppDB::Book')->all];
157 You now have the full Perl debugger at your disposal. First use the
158 C<next> feature by typing C<n> to execute the C<all> method on the Book
159 model (C<n> jumps over method/subroutine calls; you can also use C<s> to
160 C<single-step> into methods/subroutines):
163 SELECT me.id, me.authors, me.title, me.rating FROM books me:
164 MyApp::Controller::Books::list(/home/me/MyApp/script/../lib/MyApp/Controller/Books.pm:44):
165 44: $c->stash->{template} = 'books/list.tt2';
169 This takes you to the next line of code where the template name is set.
170 Notice that because we enabled C<DBIX_CLASS_STORAGE_DBI_DEBUG=1>
171 earlier, SQL debug output also shows up in the development server debug
174 Next, list the methods available on our C<Book> model:
176 DB<1> m $c->model('MyAppDB::Book')
180 MODIFY_CODE_ATTRIBUTES
185 _result_class_accessor
186 _result_source_accessor
189 <lines removed for brevity>
193 We can also play with the model directly:
195 DB<2> x ($c->model('MyAppDB::Book')->all)[1]->title
196 SELECT me.id, me.title, me.rating FROM books me:
197 0 'TCP/IP Illustrated, Volume 1'
199 This uses the Perl debugger C<x> command to display the title of a book.
201 Next we inspect the C<books> element of the Catalyst C<stash> (the C<4>
202 argument to the C<x> command limits the depth of the dump to 4 levels):
204 DB<3> x 4 $c->stash->{books}
206 0 MyApp::Model::MyAppDB::Book=HASH(0xb8e702c)
207 '_column_data' => HASH(0xb8e5e2c)
210 'title' => 'CCSP SNRS Exam Certification Guide'
212 <lines removed for brevity>
214 Then enter the C<c> command to continue processing until the next
215 breakpoint is hit (or the application exits):
218 SELECT author.id, author.first_name, author.last_name FROM ...
220 Finally, press C<Ctrl+C> to break out of the development server.
221 Because we are running inside the Perl debugger, you will drop to the
222 debugger prompt. Press C<q> to exit the debugger and return to your OS
228 For more information on using the Perl debugger, please see C<perldebug>
229 and C<perldebtut>. You can also type C<h> or C<h h> at the debugger
230 prompt to view the built-in help screens.
233 =head1 DEBUGGING MODULES FROM CPAN
235 Although the techniques discussed above work well for code you are
236 writing, what if you want to use print/log/warn messages or set
237 breakpoints in code that you have installed from CPAN (or in module that
238 ship with Perl)? One helpful approach is to place a copy of the module
239 inside the C<lib> directory of your Catalyst project. When Catalyst
240 loads, it will load from inside your C<lib> directory first, only
241 turning to the global modules if a local copy cannot be found. You can
242 then make modifications such as adding a C<$DB::single=1> to the local
243 copy of the module without risking the copy in the original location.
244 This can also be a great way to "locally override" bugs in modules while
245 you wait for a fix on CPAN.
248 Matt Trout has suggested the following shortcut to create a local
249 copy of an installed module:
251 mkdir -p lib/Module; cp `perldoc -l Module::Name` lib/Module/
253 For example, you could make a copy of
254 L<Catalyst::Plugin::Authentication|Catalyst::Plugin::Authentication>
255 with the following command:
257 mkdir -p lib/Catalyst/Plugin; cp \
258 `perldoc -l Catalyst::Plugin::Authentication` lib/Catalyst/Plugin
260 B<Note:> Matt has also suggested the following tips for Perl
267 Check the version of an installed module:
269 perl -MModule::Name -e 'print $Module::Name::VERSION;'
273 $ perl -MCatalyst::Plugin::Authentication -e \
274 'print $Catalyst::Plugin::Authentication::VERSION;'
279 Check if a modules contains a given method:
281 perl -MModule::Name -e 'print Module::Name->can("method");'
285 $ perl -MCatalyst::Plugin::Authentication -e \
286 'print Catalyst::Plugin::Authentication->can("prepare");'
289 If the method exists, the Perl C<can> method returns a coderef.
290 Otherwise, it returns undef and nothing will be printed.
297 Kennedy Clark, C<hkclark@gmail.com>
299 Please report any errors, issues or suggestions to the author. The
300 most recent version of the Catalyst Tutorial can be found at
301 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Runtime/lib/Catalyst/Manual/Tutorial/>.
303 Copyright 2006, Kennedy Clark, under Creative Commons License
304 (L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).