Ldb: A debugger for Lua
Ldb is a debugging system for the extension language
Lua,
provided as a C library of Lua functions to be linked with the application
Ldb was developed as part of the master thesis of
Tomás Guisasola who worked
together with his advisor
Roberto Ierusalimschy
at the Computer Graphics Technology Group
(TeCGraf) of
Computer Science Department of
PUC-Rio.
A paper
(gzipped or
zipped
postscript file)
about Ldb, focusing on its reflexive characteristics, was published at the
I SBLP (First Brazilian
Symposium on Programming Languages) in 1996.
Here
you can find the abstract.
Some features of Ldb
- Breakpoints;
- Step-by-step execution;
- Automatic visualization of
variables;
- Line actions; and
- Dynamic code execution.
The Ldb library is not public software.
However, it is available for pure academic, non profit, use
here;
you can also get a postscript version of the Reference Manual in
gzip or
zip formats.
As it is not an essential part of the source code of any application,
one can use it just to develop and remove it on the distribution version.
Ldb is distributed as a simple pair of files, the source (ldblib.c)
and the header (ldblib.h).
You can just add it to the makefile or project and make a few modifications
to your main function.
As an example, here we show the modifications you can make to add the
debugging facilites to the Lua Stand-alone Interpreter (*):
- copy the debugger files (ldblib.c and ldblib.h) to
./lua/src/lua (where lua.c remains)
- edit Makefile to add ldblib.o and ldblib.c
at lines beggining with OBJS= and SRCS=
respectively
- edit lua.c adding:
- #include "ldblib.h"
just after the last include line
(#include "lualib.h")
- ldblib_open();
just after the last open library function invocation
(lua_mathlibopen();)
* In fact, there is still a little problem with this new version of the
command line interpreter since it uses the hooks to trap "Ctrl-C" while
executing the command line.
We have two solutions to make it works.
Ldb has some important concepts:
Dialog Line: The debugger command line interpreter.
It is similar to a dostring-evaluator but it has some special
features like automatically display of expressions and
shortcuts to expressions.
location: A point of the source program. A location is
indicated by a line number and a file name but it can also be
identified by a function. In this case, the function is
converted to the line number and file name where it was defined.
action: A string with a chunck of Lua code. It works like
an anonymous Lua function.
local environment: A simulation of the environment of a certain
point of the execution which "gives access" to local variables.
condition: A string with a Lua boolean expression.
Here are a brief description of each debugger function (arguments between
[] are optional):
break (location)
Creates a breakpoint at a given location.
It is equivalent to doat("stop()",location).
cont ()
Continues the normal execution of the program.
delete (location)
eliminates the break point or the action at a given location.
depth ([number]):number
Selects a specific activation register on the stack to be the local
environment of the Dialog Line.
It returns the number of the activation register being simulated.
The highest activation register is refered to as the zero one.
display (string)
sets expressions to be displayed automatically every time the debugger
stops.
It receives a string with an expression that will be evaluated on the
local environment and displayed by the Dialog Line.
doalways ([action])
defines the Global Action.
This special action is evaluated before each line change and function
call and it doesn't have access to the local environment.
doat (action, location)
defines an action to be executed before the given location on the simulated
local environment.
down ([number])
changes the local environment used by the Dialog Line to another activation
register down on the stack.
The parameter is relative to the current environment.
dump ([number])
lists all local variables at the current location.
It can receive a number of activation records behind the current one to
find the variables (the default is 2 which works fine at the
Dialog Line).
file ():string
returns a string with the name of the current file.
When the debugger stops at the return of a function,
this function will return "<return>".
finish ()
continues the execution until the end of the function in execution.
goto (location)
continues the execution until a given location.
hooks ():number
returns a code that indicates what debugger hooks are turned on.
- 0 none of them are active,
- 1 only the line hook is active,
- 2 only the call hook is active,
- 3 all of them are turned on.
line ():number
returns the number of the current line.
If the current location is at function call or a return, it returns zero.
list ([number [, location]])
lists some lines of the source code.
It can receive the number of lines to be listed and a location where to
start.
Next ([number])
executes the next lines of the program being debugged.
It optionally receives the number of lines to be executed.
It passes over function calls.
setshortcut (string, action)
defines a shortcut to an action.
A shortcut is activated by typing ' and its initial character.
show ()
displays all breakpoints and actions defined and the Global Action.
stack ()
display the execution stack.
step ([number])
executes the next steps of the program being debugged.
It optionally receives the number of lines to be executed.
It traces into function calls.
stop ([condition])
signs an interruption of the execution.
It can receive a condition to stop.
undisplay (number)
eliminates one of the expressions being automatically displayed.
It receives the number of the expression.
up ([number])
changes the local environment used by the Dialog Line to another activation
register up on the stack.
The parameter is relative to the current environment.
where ()
display the execution stack.
The debugger offers a configuration facility to the user.
When it starts, Ldb tries to load the configuration file ldbrc.lua
(or whatever is indicated by the environment variable LDB_CONFIG)
which can contains Lua commands.
These commands can create functions, variables or shortcuts and can be
used to solve conflicts of names with other Lua libraries such as EDG
which has the names line and list, also defined by the
debugger.
The default file ldbrc.lua defines some shortcuts:
| -
| down
| +
| up
| ?
| list of commands
| c
| cont
|
| d
| display
| f
| finish
| g
| goto
| n
| Next
|
| p
| print
| q
| exit
| s
| step
| v
| show
|
| w
| where
|
If the file indicated by LDB_CONFIG can't be found,
Ldb tries to find ldbrc.lua at the current directory or
(if it fails too) at the $HOME directory.
- Zip versions of the SBLP paper and the Reference Manual (7/jul/2000)
- Internal correction in execute_command (3/feb/1999)
- dump new function implemented (7/oct/1998)
- New search path for ldbrc.lua (7/oct/1998)
- hooks new function implemented (17/aug/1998)
- Lua 3.1 update (10/aug/1998)
- Automatic function call when stop
- Global Action definition with cont
Last modification: 07/jul/2000 by Tomás