Devel::Trepan -- A modular gdb-like Perl debugger
A modular, testable, gdb-like debugger in the family of the Ruby trepanning debuggers.
extensive pod-formatted online-help
syntax highlighting of Perl code
context-sensitive command completion
out-of-process and remote debugging
gdb syntax
easy extensibility at several levels: aliases, commands, and plugins
comes with extensive tests
interactive shell support (via an optional plugin)
code deparsing and disassembly (via an optional plugins)
is not as ugly as perl5db
Some of the features above require additional modules before they take effect. See "Plugins" and "Recommended Modules" below.
From a shell:
$ trepan.pl [trepan-opts] [--] perl-program [perl-program-opts]
Or for those who prefer the traditional Perlish way:
$ perl -d:Trepan perl-program [perl-program-opts]
The problem with the above "perlish" approach is that you get the default trepan options. If you want to set any of these, you'll have to set them either with a debugger command, possibly via startup script, e.g. ~/.treplrc or via environment variable TREPANPL_OPTS.
To see the environement variables, run trepan.pl with the --verbose option or run eval $ENV{TREPANPL_OPTS} inside of the debugger.
--verbose
eval $ENV{TREPANPL_OPTS}
For out-of-process (and possibly out-of server) debugging:
$ trepan.pl --server [trepan-opts] -- perl-program [perl-program-opts]
and then from another process or computer:
$ trepan.pl --client [--host DNS-NAME-OR-IP]
Calling the debugger from inside your Perl program using Joshua ben Jore's Enbugger:
# This needs to be done once and could even be in some sort of # conditional code require Enbugger; Enbugger->load_debugger( 'trepan' ); # Alternatively, to unconditionally load Enbugger and trepan: use Enbugger 'trepan'; # work, work, work... # Oops! there was an error! Enable the debugger now! Enbugger->stop; # or Enbugger->stop if ...
Or if you just want POSIX-shell-like set -x line tracing:
set -x
$ trepan.pl -x -- perl-program [perl-program-opts]
Inside the debugger tracing is turned on using the command set trace print. There is extensive help from the help command.
set trace print
help
The help system follows the gdb classificiation.
"Making the program stop at certain points"
"Examining data"
"Specifying and examining files"
"Commands involving running the program"
"Examining the call stack"
"Status inquiries"
"Support facilities"
"Syntax of Debugger Commands"
A breakpoint is a way to have the program stop at a pre-determined location. A breakpoint can be perminant or one-time. A one-time breakpoint is removed as soon as it is hit. In a sense, stepping is like setting one-time breakpoints. Breakpoints can also be disabled which allows you to temporarily ignore stopping at that breakpoint while it is disabled. Finally one can control conditions under which a breakpoint is enacted upon.
Another way to force a stop is to watch to see if the value of an expression changes. Often that expression is simply examinging a variable's value.
Set an action to be done before the line is executed (action)
Set a breakpoint (break)
Add or modify a condition on a breakpoint (condition)
Clear some breakpoints by line number (clear)
Delete some breakpoints (delete)
Disable some breakpoints (disable)
Enable some breakpoints (enable)
Set a temporary breakpoint (tbreak)
Stop when an expression changes value (watch)
Debug into a Perl expression or statement (debug)
Disassemble (de-parse) Perl code
Disassemble Perl OP codes (disassemble)
Display expressions when entering the debugger (display)
Evaluate Perl code (eval)
Evaluate Perl code (deval) via Deparse
Cancel some expressions to be displayed when program stops (undisplay)
Invoke an editor on some source code (edit)
List source code (list)
The commands in the section involve controlling execution of the program, either by kinds of stepping (step into, step over, step out) restarting or termintating the program altogether. However setting breakpoints is in "Making the program stop at certain points".
Continue execution (continue)
Step out (finish)
Specify a how to handle a signal (handle)
Step over (next)
Step into (step)
Hard termination (kill)
Gently exit debugged program (quit)
Restart execution (run)
The commands in this section show the call stack and let set a reference for the default call stack which other commands like list or break use as a position when one is not specified.
list
break
The most recent call stack entry is 0. Except for the relative motion commands up and down, you can refer to the oldest or top-level stack entry with -1 and negative numbers refer to the stack from the other end.
up
down
Beware that in contrast to debuggers in other programming languages, Perl really doesn't have an easy way for one to evaluate statements and expressions other than at the most recent call stack. There are ways to see lexical variables my and our, however localized variables which can hide global variables and other lexicals variables can be problematic.
Print all or parts of the call stack (backtrace)
Move to a less recent frame (down)
Select a call frame (frame)
Move to a more recent frame (up)
Information for showing things about the program being debugged (info)
Showing things about the debugger (show)
Define an alias (alias)
List the completions for the rest of the line (complete)
Loading or reloading Debugger or Perlish things (load)
Define a macro (macro)
Allow remote connections (server)
Run shell via re.pl (shell)
Run debugger commands from a file (source)
Modify parts of the Debugger Environment (set)
Remove an alias (unalias)
Overall Debugger Command Syntax
Location Syntax
Filename syntax
Command suffixes which have special meaning
Debugger Command Examples
Because this should be useful in all sorts of environments such as back to perl 5.008, we often can not make use of newer Perlisms nor can we require by default all of the modules, say for data printing, stack inspection, or interactive terminal handling. That said, if you have a newer Perl or the recommended modules or install plugins, you'll get more.
Although modular, this program is even larger than perl5db and so it loads a little slower. I think part of the slowness is the fact that there are over 70 or so (smallish) files (rather than one nearly 10K file) and because relative linking via rlib is used to glue them together.
perl5db
Rocky Bernstein
On writing a new Perl Debugger (Part 1 - Why?)
Devel::Trepan Debugger command aliases and command completion
Devel::Trepan Debugger evaluation of Perl statements
Location, Location, Location
Exact Perl location with B::DeparseTree (and Devel::Callsite)
Devel::Trepan github wiki
Devel::Trepan::Shell adds a debugger shell command support via Devel::REPL
shell
Devel::Trepan::Deparse adds Perl code disassembly (de-parsing). With this, you can find out exactly where you are stopped. It also allows for a more reliably eval command, called deval. See Exact Perl location with B::Deparse (and Devel::Callsite)
eval
deval
Devel::Trepan::Disassemble adds a command disassemble for disassembly of Perl OP codes. Post-processing is done to colorize the listings.
disassemble
Devel::Trepan will detect automatically whether any of these modules are present. If so, additional capabilies are available.
Enbugger allows you to enter the debugger without previously having your program compiled for debugging.
Eval::WithLexicals allows you to inspect my and our variables up the call stack. Commands info variables my and info variables our become available when this module is detected.
info variables my
info variables our
Data::Printer allows one to Use Data::Printer to format evaluation output
Data::Dumper::Perltidy allows one to Use Data::Dumper::Perltidy to format evaluation output
Term::ReadLine::Perl5 allows editing on the command line, command completion, and saving command history. This Module is preferred over Term::ReadLine::Perl or Term::ReadLine::Gnu.
Term::ReadLine::Gnu allows editing of the command line and command completion. Command completion isn't as good here as with Term::ReadLine::Perl5.
perldebug is perl's built-in tried-and-true debugger that other debuggers will ultimately be compared with
Devel::ebug
DB is a somewhat abandoned debugger API interface. I've tried to use some parts of this along with perl5db.
Devel::Hdb
A Perl debugger that uses HTML and javascript to implement the GUI. The front end talks via a REST service. (via Websocket would be cooler though.) It too uses ideas from DB.
Copyright (C) 2011, 2012, 2014-2015 Rocky Bernstein <rocky@cpan.org>
This program is distributed WITHOUT ANY WARRANTY, including but not limited to the implied warranties of merchantability or fitness for a particular purpose.
The program is free software. You may distribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation (either version 2 or any later version) and the Perl Artistic License as published by O'Reilly Media, Inc. Please open the files named gpl-2.0.txt and Artistic for a copy of these licenses.
To install Devel::Trepan, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Devel::Trepan
CPAN shell
perl -MCPAN -e shell install Devel::Trepan
For more information on module installation, please visit the detailed CPAN module installation guide.