2.4. Module tdb

Module tdb

The Tarantool Debugger (abbreviation = tdb) can be used with any Lua program. The operational features include: setting breakpoints, examining variables, going forward one line at a time, backtracing, and showing information about fibers. The display features include: using different colors for different situations, including line numbers, and adding hints.

It is not supplied as part of the Tarantool repository; it must be installed separately. Here is the usual way:

git clone --recursive https://github.com/Sulverus/tdb
cd tdb
sudo make install prefix=/usr/share/tarantool/

To initiate tdb within a Lua program and set a breakpoint, edit the program to include these lines:

tdb = require('tdb')

To start the debugging session, execute the Lua program. Execution will stop at the breakpoint, and it will be possible to enter debugging commands.

Debugger Commands

Backtrace – show the stack (in red), with program/function names and line numbers of whatever has been invoked to reach the current line.
Continue till next breakpoint or till program ends.
Enter evaluation mode. When the program is in evaluation mode, one can execute certain Lua statements that would be valid in the context. This is particularly useful for displaying the values of the program’s variables. Other debugger commands will not work until one exits evaluation mode by typing -e.
Exit evaluation mode.
Display the fiber id, the program name, and the percentage of memory used, as a table.
Go to the next line, skipping over any function calls.
Display names of variables or functions which are defined as global.
Display a list of debugger commands.
Display names and values of variables, for example the control variables of a Lua “for” statement.
Quit immediately.

Example Session

Put the following program in a default directory and call it “example.lua”:

tdb = require('tdb')
i = 1
j = 'a' .. i
print('end of program')

Now start Tarantool, using example.lua as the initialization file

$ tarantool example.lua

The screen should now look like this:

$ tarantool example.lua
(TDB)  Tarantool debugger v.0.0.3. Type h for help
(TDB)  [example.lua]
(TDB)  3: i = 1

Debugger prompts are blue, debugger hints and information are green, and the current line – line 3 of example.lua – is the default color. Now enter six debugger commands:

n  -- go to next line
n  -- go to next line
e  -- enter evaluation mode
j  -- display j
-e -- exit evaluation mode
q  -- quit

The screen should now look like this:

$ tarantool example.lua
(TDB)  Tarantool debugger v.0.0.3. Type h for help
(TDB)  [example.lua]
(TDB)  3: i = 1
(TDB)> n
(TDB)  4: j = 'a' .. i
(TDB)> n
(TDB)  5: print('end of program')
(TDB)> e
(TDB)  Eval mode ON
(TDB)> j
j       a1
(TDB)> -e
(TDB)  Eval mode OFF
(TDB)> q

Another debugger example can be found here.