=head1 DESCRIPTION
-First of all, have you tried using the B<-w> switch?
-
+First of all, have you tried using L<C<use strict;>|strict> and
+L<C<use warnings;>|warnings>?
If you're new to the Perl debugger, you may prefer to read
L<perldebtut>, which is a tutorial introduction to the debugger.
+If you're looking for the nitty gritty details of how the debugger is
+I<implemented>, you may prefer to read L<perldebguts>.
+
=head1 The Perl Debugger
If you invoke Perl with the B<-d> switch, your script runs under the
Interactively supply an arbitrary C<expression> using C<-e>.
-=item perl -d:Ptkdb program_name
+=item perl -d:ptkdb program_name
-Debug a given program via the C<Devel::Ptkdb> GUI.
+Debug a given program via the C<Devel::ptkdb> GUI.
=item perl -dt threaded_program_name
See L<Dumpvalue> if you'd like to do this yourself.
The output format is governed by multiple options described under
-L<"Configurable Options">.
+L</"Configurable Options">.
If the C<maxdepth> is included, it must be a numeral I<N>; the value is
dumped only I<N> levels deep, as if the C<dumpDepth> option had been
List subroutine names [not] matching the regex.
-=item t
+=item t [n]
X<debugger command, t>
Toggle trace mode (see also the C<AutoTrace> option).
+Optional argument is the maximum number of levels to trace below
+the current one; anything deeper than that will be silent.
-=item t expr
+=item t [n] expr
X<debugger command, t>
Trace through execution of C<expr>.
+Optional first argument is the maximum number of levels to trace below
+the current one; anything deeper than that will be silent.
See L<perldebguts/"Frame Listing Output Examples"> for examples.
=item b
b 237 ++$count237 < 11
b 33 /pattern/i
+If the line number is C<.>, sets a breakpoint on the current line:
+
+ b . $n > 100
+
=item b [file]:[line] [condition]
X<breakpoint>
X<debugger command, b>
Delete all installed breakpoints.
+=item disable [file]:[line]
+X<breakpoint>
+X<debugger command, disable>
+X<disable>
+
+Disable the breakpoint so it won't stop the execution of the program.
+Breakpoints are enabled by default and can be re-enabled using the C<enable>
+command.
+
+=item disable [line]
+X<breakpoint>
+X<debugger command, disable>
+X<disable>
+
+Disable the breakpoint so it won't stop the execution of the program.
+Breakpoints are enabled by default and can be re-enabled using the C<enable>
+command.
+
+This is done for a breakpoint in the current file.
+
+=item enable [file]:[line]
+X<breakpoint>
+X<debugger command, disable>
+X<disable>
+
+Enable the breakpoint so it will stop the execution of the program.
+
+=item enable [line]
+X<breakpoint>
+X<debugger command, disable>
+X<disable>
+
+Enable the breakpoint so it will stop the execution of the program.
+
+This is done for a breakpoint in the current file.
+
=item a [line] command
X<debugger command, a>
1 only where it is safe to do so--that is, mostly for Boolean
options. It is always better to assign a specific value using C<=>.
The C<option> can be abbreviated, but for clarity probably should
-not be. Several options can be set together. See L<"Configurable Options">
+not be. Several options can be set together. See L</"Configurable Options">
for a list of these.
=item < ?
X<debugger option, recallCommand>
X<debugger option, ShellBang>
-The characters used to recall command or spawn shell. By
+The characters used to recall a command or spawn a shell. By
default, both are set to C<!>, which is unfortunate.
=item C<pager>
size of strings found in variables in the package. This does not
include lexicals in a module's file scope, or lost in closures.
+=item C<HistFile>
+X<debugger option, history, HistFile>
+
+The path of the file from which the history (assuming a usable
+Term::ReadLine backend) will be read on the debugger's startup, and to which
+it will be saved on shutdown (for persistence across sessions). Similar in
+concept to Bash's C<.bash_history> file.
+
+=item C<HistSize>
+X<debugger option, history, HistSize>
+
+The count of the saved lines in the history (assuming C<HistFile> above).
+
=back
After the rc file is read, the debugger reads the C<$ENV{PERLDB_OPTS}>
Here's an example of what a stack backtrace via C<T> command might
look like:
- $ = main::infested called from file `Ambulation.pm' line 10
- @ = Ambulation::legs(1, 2, 3, 4) called from file `camel_flea' line 7
- $ = main::pests('bactrian', 4) called from file `camel_flea' line 4
+ $ = main::infested called from file 'Ambulation.pm' line 10
+ @ = Ambulation::legs(1, 2, 3, 4) called from file 'camel_flea'
+ line 7
+ $ = main::pests('bactrian', 4) called from file 'camel_flea'
+ line 4
The left-hand character up there indicates the context in which the
function was called, with C<$> and C<@> meaning scalar or list
This shows the sorts of output the C<l> command can produce:
- DB<<13>> l
- 101: @i{@i} = ();
- 102:b @isa{@i,$pack} = ()
- 103 if(exists $i{$prevpack} || exists $isa{$pack});
- 104 }
- 105
- 106 next
- 107==> if(exists $isa{$pack});
- 108
- 109:a if ($extra-- > 0) {
- 110: %isa = ($pack,1);
+ DB<<13>> l
+ 101: @i{@i} = ();
+ 102:b @isa{@i,$pack} = ()
+ 103 if(exists $i{$prevpack} || exists $isa{$pack});
+ 104 }
+ 105
+ 106 next
+ 107==> if(exists $isa{$pack});
+ 108
+ 109:a if ($extra-- > 0) {
+ 110: %isa = ($pack,1);
Breakable lines are marked with C<:>. Lines with breakpoints are
marked by C<b> and those with actions by C<a>. The line that's
breakpoint on the I<load> of some module:
DB<7> b load f:/perllib/lib/Carp.pm
- Will stop on load of `f:/perllib/lib/Carp.pm'.
+ Will stop on load of 'f:/perllib/lib/Carp.pm'.
and then restart the debugger using the C<R> command (if possible). One can use C<b
compile subname> for the same purpose.
=head2 Editor Support for Debugging
-If you have the FSF's version of B<emacs> installed on your system,
+If you have the GNU's version of B<emacs> installed on your system,
it can interact with the Perl debugger to provide an integrated
software development environment reminiscent of its interactions
with C debuggers.
syntax-directed editor that understands (some of) Perl's syntax.
See L<perlfaq3>.
-A similar setup by Tom Christiansen for interacting with any
-vendor-shipped B<vi> and the X11 window system is also available.
-This works similarly to the integrated multiwindow support that
-B<emacs> provides, where the debugger drives the editor. At the
-time of this writing, however, that tool's eventual location in the
-Perl distribution was uncertain.
-
Users of B<vi> should also look into B<vim> and B<gvim>, the mousey
and windy version, for coloring of Perl keywords.
=head1 SEE ALSO
-You did try the B<-w> switch, didn't you?
+You do have C<use strict> and C<use warnings> enabled, don't you?
L<perldebtut>,
L<perldebguts>,