Ldb: A debugger for Lua

What is Ldb?

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


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 (*):

  1. copy the debugger files (ldblib.c and ldblib.h) to ./lua/src/lua (where lua.c remains)
  2. edit Makefile to add ldblib.o and ldblib.c at lines beggining with OBJS= and SRCS= respectively
  3. edit lua.c adding:
* 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.

On-line Reference

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.

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.

Predefined shortcuts

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.


Future improvements

Last modification: 07/jul/2000 by Tomás