|
Perl has special debugging hooks at compile-time and run-time used to create debugging
environments. These hooks are not to be confused with the perl -Dxxx command described
in perlrun, which is usable
only if a special Perl is built per the instructions in the INSTALL podpage in the Perl
source tree.
For example, whenever you call Perl's built-in caller function from the
package DB, the arguments that the corresponding stack frame was called with are
copied to the @DB::args array. These mechanisms are enabled by calling Perl with
the -d switch. Specifically, the following additional features are enabled (cf. perlvar/$^P):
- Perl inserts the contents of
$ENV{PERL5DB} (or BEGIN {require
'perl5db.pl'} if not present) before the first line of your program.
-
Each array @{"_<$filename"} holds the lines of $filename for
a file compiled by Perl. The same is also true for evaled strings that
contain subroutines, or which are currently being executed. The $filename for evaled
strings looks like (eval 34). Code assertions in regexes look like (re_eval
19).
Values in this array are magical in numeric context: they compare equal to zero only if
the line is not breakable.
-
Each hash %{"_<$filename"} contains breakpoints and actions
keyed by line number. Individual entries (as opposed to the whole hash) are settable. Perl
only cares about Boolean true here, although the values used by perl5db.pl have the
form "$break_condition\0$action".
The same holds for evaluated strings that contain subroutines, or which are currently
being executed. The $filename for evaled strings looks like (eval 34)
or (re_eval 19).
- Each scalar
${"_<$filename"} contains "_<$filename".
This is also the case for evaluated strings that contain subroutines, or which are
currently being executed. The $filename for evaled strings looks like (eval
34) or (re_eval 19).
- After each
required file is compiled, but before it is executed, DB::postponed(*{"_<$filename"})
is called if the subroutine DB::postponed exists. Here, the $filename is the
expanded name of the required file, as found in the values of %INC.
- After each subroutine
subname is compiled, the existence of $DB::postponed{subname}
is checked. If this key exists, DB::postponed(subname) is called if the DB::postponed
subroutine also exists.
- A hash
%DB::sub is maintained, whose keys are subroutine names and whose
values have the form filename:startline-endline. filename has
the form (eval 34) for subroutines defined inside evals, or (re_eval
19) for those within regex code assertions.
- When the execution of your program reaches a point that can hold a breakpoint, the
DB::DB()
subroutine is called if any of the variables $DB::trace, $DB::single,
or $DB::signal is true. These variables are not localizable.
This feature is disabled when executing inside DB::DB(), including functions
called from it unless $^D & (1<<30) is true.
- When execution of the program reaches a subroutine call, a call to
&DB::sub(args)
is made instead, with $DB::sub holding the name of the called subroutine.
(This doesn't happen if the subroutine was compiled in the DB package.)
Note that if &DB::sub needs external data for it to work, no subroutine
call is possible without it. As an example, the standard debugger's &DB::sub
depends on the $DB::deep variable (it defines how many levels of recursion deep
into the debugger you can go before a mandatory break). If $DB::deep is not
defined, subroutine calls are not possible, even though &DB::sub exists.
=head3 Environment Variables
The PERL5DB environment variable can be used to define a debugger. For
example, the minimal "working" debugger (it actually doesn't do anything) consists
of one line:
It can easily be defined like this:
$ PERL5DB="sub DB::DB {}" perl -d your-script
|
|
Another brief debugger, slightly more useful, can be created with only the line:
sub DB::DB {print ++$i; scalar <STDIN>}
|
|
This debugger prints a number which increments for each statement encountered and waits for
you to hit a newline before continuing to the next statement.
The following debugger is actually useful:
{
package DB;
sub DB {}
sub sub {print ++$i, " $sub\n"; &$sub}
}
|
|
It prints the sequence number of each subroutine call and the name of the called
subroutine. Note that &DB::sub is being compiled into the package DB
through the use of the package directive.
When it starts, the debugger reads your rc file (./.perldb or ~/.perldb under
Unix), which can set important options. (A subroutine (&afterinit) can be
defined here as well; it is executed after the debugger completes its own initialization.)
After the rc file is read, the debugger reads the PERLDB_OPTS environment variable and uses
it to set debugger options. The contents of this variable are treated as if they were the
argument of an o ... debugger command (q.v. in perldebug/Options).
=head3 Debugger internal variables In addition to the file and subroutine-related variables
mentioned above, the debugger also maintains various magical internal variables.
-
@DB::dbline is an alias for @{"::_<current_file"},
which holds the lines of the currently-selected file (compiled by Perl), either explicitly
chosen with the debugger's f command, or implicitly by flow of execution.
Values in this array are magical in numeric context: they compare equal to zero only if
the line is not breakable.
-
%DB::dbline, is an alias for %{"::_<current_file"},
which contains breakpoints and actions keyed by line number in the currently-selected
file, either explicitly chosen with the debugger's f command, or implicitly
by flow of execution.
As previously noted, individual entries (as opposed to the whole hash) are settable.
Perl only cares about Boolean true here, although the values used by perl5db.pl
have the form "$break_condition\0$action".
=head3 Debugger customization functions
Some functions are provided to simplify customization.
- See perldebug/"Options"
for description of options parsed by
DB::parse_options(string) parses
debugger options; see pperldebug/Options
for a description of options recognized.
DB::dump_trace(skip[,count]) skips the specified number of frames and
returns a list containing information about the calling frames (all of them, if count
is missing). Each entry is reference to a hash with keys context (either .,
$, or @), sub (subroutine name, or info about eval),
args (undef or a reference to an array), file, and line.
DB::print_trace(FH, skip[, count[, short]]) prints formatted info about
caller frames. The last two functions may be convenient as arguments to <,
<< commands.
Note that any variables and functions that are not documented in this manpages (or in perldebug) are considered for
internal use only, and as such are subject to change without notice.
|
|
