If you're new to the Perl debugger, you may prefer to read
-L<perldebtut>, which is a tutorial introduction to the debugger .
+L<perldebtut>, which is a tutorial introduction to the debugger.
=head1 The Perl Debugger
as a leading C<;> or perhaps a C<+>, or by wrapping it with parentheses
or braces.
+=head2 Calling the Debugger
+
+There are several ways to call the debugger:
+
+=over 4
+
+=item perl -d program_name
+
+On the given program identified by C<program_name>.
+
+=item perl -d -e 0
+
+Interactively supply an arbitrary C<expression> using C<-e>.
+
+=item perl -d:ptkdb program_name
+
+Debug a given program via the C<Devel::ptkdb> GUI.
+
+=item perl -dt threaded_program_name
+
+Debug a given program using threads (experimental).
+
+=back
+
=head2 Debugger Commands
-The debugger understands the following commands:
+The interactive debugger understands the following commands:
=over 12
You may change the pager which is used via C<o pager=...> command.
-
=item p expr
X<debugger command, p>
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>
+
+Set a breakpoint before the given line in a (possibly different) file. If a
+condition is specified, it's evaluated each time the statement is reached: a
+breakpoint is taken only if the condition is true. Breakpoints may only be set
+on lines that begin an executable statement. Conditions don't use C<if>:
+
+ b lib/MyModule.pm:237 $x > 30
+ b /usr/lib/perl5/site_perl/CGI.pm:100 ++$count100 < 11
+
=item b subname [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>
=item w expr
X<debugger command, w>
-Add a global watch-expression. We hope you know what one of these
-is, because they're supposed to be obvious.
+Add a global watch-expression. Whenever a watched global changes the
+debugger will stop and display the old and new values.
=item W expr
X<debugger command, W>
=item o
X<debugger command, o>
-Display all options
+Display all options.
=item o booloption ...
X<debugger command, o>
Set an action (Perl command) to happen after the prompt when you've
just given a command to return to executing the script. A multi-line
command may be entered by backslashing the newlines (we bet you
-couldn't've guessed this by now).
+couldn't have guessed this by now).
=item > *
X<< debugger command, > >>
=item M
X<debugger command, M>
-Displays all loaded modules and their versions
-
+Display all loaded modules and their versions.
=item man [manpage]
X<debugger command, man>
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>
Level of verbosity. By default, the debugger leaves your exceptions
and warnings alone, because altering them can break correctly running
programs. It will attempt to print a message when uncaught INT, BUS, or
-SEGV signals arrive. (But see the mention of signals in L<BUGS> below.)
+SEGV signals arrive. (But see the mention of signals in L</BUGS> below.)
To disable this default safe mode, set these values to something higher
than 0. At a level of 1, you get backtraces upon receiving any kind
often valuable). Unfortunately, the debugger cannot discern fatal
exceptions from non-fatal ones. If C<dieLevel> is even 1, then your
non-fatal exceptions are also traced and unceremoniously altered if they
-came from C<eval'd> strings or from any kind of C<eval> within modules
+came from C<eval'ed> strings or from any kind of C<eval> within modules
you're attempting to load. If C<dieLevel> is 2, the debugger doesn't
care where they came from: It usurps your exception handler and prints
out a trace, then modifies all exceptions with its own embellishments.
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}>
See L<perldebguts/"Debugger Internals"> for details.
-=head2 Debugger input/output
+=head2 Debugger Input/Output
=over 8
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
If you execute the C<T> command from inside an active C<use>
statement, the backtrace will contain both a C<require> frame and
-an C<eval>) frame.
+an C<eval> frame.
=item Line Listing Format
=back
-=head2 Debugging compile-time statements
+=head2 Debugging Compile-Time Statements
If you have compile-time executable statements (such as code within
-BEGIN and CHECK blocks or C<use> statements), these will I<not> be
-stopped by debugger, although C<require>s and INIT blocks will, and
-compile-time statements can be traced with C<AutoTrace> option set
-in C<PERLDB_OPTS>). From your own Perl code, however, you can
-transfer control back to the debugger using the following statement,
-which is harmless if the debugger is not running:
+BEGIN, UNITCHECK and CHECK blocks or C<use> statements), these will
+I<not> be stopped by debugger, although C<require>s and INIT blocks
+will, and compile-time statements can be traced with the C<AutoTrace>
+option set in C<PERLDB_OPTS>). From your own Perl code, however, you
+can transfer control back to the debugger using the following
+statement, which is harmless if the debugger is not running:
$DB::single = 1;
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.
The debugger probably contains enough configuration hooks that you
won't ever have to modify it yourself. You may change the behaviour
-of debugger from within the debugger using its C<o> command, from
+of the debugger from within the debugger using its C<o> command, from
the command line via the C<PERLDB_OPTS> environment variable, and
from customization files.
this document (or in L<perldebguts>) are considered for internal
use only, and as such are subject to change without notice.
-=head2 Readline Support
+=head2 Readline Support / History in the Debugger
As shipped, the only command-line history supplied is a simplistic one
that checks for leading exclamation points. However, if you install
-the Term::ReadKey and Term::ReadLine modules from CPAN, you will
-have full editing capabilities much like GNU I<readline>(3) provides.
+the Term::ReadKey and Term::ReadLine modules from CPAN (such as
+Term::ReadLine::Gnu, Term::ReadLine::Perl, ...) you will
+have full editing capabilities much like those GNU I<readline>(3) provides.
Look for these in the F<modules/by-module/Term> directory on CPAN.
These do not support normal B<vi> command-line editing, however.
-A rudimentary command-line completion is also available.
-Unfortunately, the names of lexical variables are not available for
-completion.
+A rudimentary command-line completion is also available, including
+lexical variables in the current scope if the C<PadWalker> module
+is installed.
+
+Without Readline support you may see the symbols "^[[A", "^[[C", "^[[B",
+"^[[D"", "^H", ... when using the arrow keys and/or the backspace key.
=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.
-Perl comes with a start file for making B<emacs> act like a
+Recent versions of Emacs come with a
+start file for making B<emacs> act like a
syntax-directed editor that understands (some of) Perl's syntax.
-Look in the I<emacs> directory of the Perl source distribution.
-
-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.
+See L<perlfaq3>.
Users of B<vi> should also look into B<vim> and B<gvim>, the mousey
and windy version, for coloring of Perl keywords.
=head2 The Perl Profiler
X<profile> X<profiling> X<profiler>
-If you wish to supply an alternative debugger for Perl to run, just
+If you wish to supply an alternative debugger for Perl to run,
invoke your script with a colon and a package argument given to the
-B<-d> flag. The most popular alternative debuggers for Perl is the
-Perl profiler. Devel::DProf is now included with the standard Perl
+B<-d> flag. Perl's alternative debuggers include a Perl profiler,
+L<Devel::NYTProf>, which is available separately as a CPAN
distribution. To profile your Perl program in the file F<mycode.pl>,
just type:
- $ perl -d:DProf mycode.pl
+ $ perl -d:NYTProf mycode.pl
-When the script terminates the profiler will dump the profile
-information to a file called F<tmon.out>. A tool like B<dprofpp>,
-also supplied with the standard Perl distribution, can be used to
-interpret the information in that profile.
+When the script terminates the profiler will create a database of the
+profile information that you can turn into reports using the profiler's
+tools. See <perlperf> for details.
-=head1 Debugging regular expressions
+=head1 Debugging Regular Expressions
X<regular expression, debugging>
X<regex, debugging> X<regexp, debugging>
expression matching works in general, but also know how Perl's regular
expressions are internally compiled into an automaton. These matters
are explored in some detail in
-L<perldebguts/"Debugging regular expressions">.
+L<perldebguts/"Debugging Regular Expressions">.
-=head1 Debugging memory usage
+=head1 Debugging Memory Usage
X<memory usage>
Perl contains internal support for reporting its own memory usage,
but this is a fairly advanced concept that requires some understanding
of how memory allocation works.
-See L<perldebguts/"Debugging Perl memory usage"> for the details.
+See L<perldebguts/"Debugging Perl Memory Usage"> for the details.
=head1 SEE ALSO
L<perldebguts>,
L<re>,
L<DB>,
-L<Devel::DProf>,
-L<dprofpp>,
+L<Devel::NYTProf>,
L<Dumpvalue>,
and
L<perlrun>.
https://perl5.git.perl.org / perl5.git / blobdiff