/ 
DB-Hooks-0.0201
/ README.md

Perl Debugger

[!IMPORTANT] Free evaluation is permitted. Production and commercial use require a paid license. Redistribution is not permitted.

Buy Perl Debugger — CA$170, one-time payment →

Support Perl Debugger

I hope Perl Debugger makes your work easier and saves you time tracking down bugs.

If you support this product, you also support the Perl community. Ten percent of Perl Debugger revenue will be donated to The Perl & Raku Foundation.

The source is available for free evaluation, investigation, learning, teaching, and educational use. Regular, ongoing, production, or commercial use requires a paid license. See LICENSE for the complete terms.

How to run

DB::Hooks runs through Perl's normal debugger interface. It stops at a DBG> prompt, where you can step through code, inspect variables, and view the call stack without adding print statements to the program.

Requirements

Try the debugger

Install the module into a local directory without changing your system Perl:

cpanm -L local DB::Hooks

Start a small debugging session with the local installation:

PERL5DB="use DB::Hooks qw'::Terminal'" \
PERL5LIB=local/lib/perl5 \
PERLDB_OPTS="white_box" \
perl -d -e 0

PERL5DB loads the debugger and its terminal interface. PERLDB_OPTS passes debugger options, and PERL5LIB lets Perl find the local installation.

-e 0 tells Perl to run the expression 0. The debugger stops before it:

-e
    0: use DB::Hooks qw'::Terminal';
  >>1: 0


DBG> n

At DBG>, begin with n to execute the current statement and stop at the next one. Use s to step into a subroutine call, r to return from the current subroutine, T to view the call stack, and q to quit.

To debug your own program, run the same command with your script in place of -e 0:

PERL5DB="use DB::Hooks qw'::Terminal'" \
PERL5LIB=local/lib/perl5 \
PERLDB_OPTS="white_box" \
perl -d script.pl

Debug a Mojolicious application

Start the application's morbo process under the debugger:

cd <your-mojolicious-app>
PERLDB_OPTS="white_box" \
PERL5DB="use DB::Hooks qw'::Terminal ::TraceVariable NonStop'" \
perl -d "$(which morbo)" script/mojo_app

The ::TraceVariable extension enables variable-access tracing. NonStop skips the initial debugger stop so the server can start normally. Add DB::x; where you want execution to stop, or set a breakpoint after connecting a debugger client.

Establish remote debugging session

Use two terminals when the program being debugged cannot share the same terminal as the debugger client.

In the first terminal, start the program and the remote debugger listener. DB::x creates a debugger stop:

PERL5LIB=local/lib/perl5 \
PERL5DB="use DB::Hooks qw'::Terminal ::Remote ::TraceVariable NonStop'" \
perl -d -e 'DB::x; 1'

In the second terminal, connect the debugger client to the default local listener:

dclient.pl 127.0.0.1 9001

If dclient.pl is not on your PATH, run the copy installed under local/bin/ instead. Set DBG_PORT in the first terminal to use a port other than 9001.

Quick guide to commands

s - step into the next statement
n - step over the next statement
r - return from a subroutine
go - run the script until the end or the next trap
go N - run the script to line N
q - quit debugger
R - restart debugging. Works only while remotely debugging a script run under uWSGI

f - list all files
f regex - list all files that match the regex
f N - set file N as current

l . - list source at the current step
l - list next source page
l $coderef - deparse the subroutine
l -N - list source for frame N
l &N - deparse the subroutine for frame N

vars - show variables visible from the current step
vars N - show variables visible from frame N
vars N $var - show the value of $var at frame N

t [$x|@x|%x] - trace access to the given variable and log it to 'vars.log'

T - show stack trace
T N - show only the last N frames
NOTICE: stack trace also shows GOTO frames

b - list all traps
b . - set trap at current step
b . condition - set a conditional trap
b [+|-][file:|M:]N - set trap at the given file:line
	+ - enable trap
	- - disable trap
	file - absolute path to the file
	M - number from the 'f' command output
	N - line number in the file
save|load - save/load trap information in the ~/.dbginit file

a expr - set action
A expr - remove action
w expr - set watch
W expr - remove watch

expr - evaluate 'expr' from the user's script perspective
e expr - evaluate 'expr' from the user's script perspective and show Data::Dump::pp results

ge - run the editor for the current file
ge file:N - run the editor for the given file

More materials