Debugging is an essential part of software development.

ANSCA offers a command-line debugger called debugger that offers all the standard debugger features:

• breakpoints
• stepping through code line-by-line
• stepping into functions
• listing the local variables
• inspecting the values of local variables
• inspecting the internal contents of Lua tables
• obtaining function stack traces
• switching into different stack frames
• printing and evaluating Lua expressions
• etc.

Basics

A debugger runs your application in the simulator. It allows you to specify what events trigger the debugger to pause execution of the application.

A most common trigger is a breakpoint. This allows you to pause execution anytime a line of code is about to execute. This provides you with the opportunity to look at the state of the application at that particular point in time, including the values of variables or the function stack trace.

Sample Session

The best way to understand how to use a debugger is to walk through a sample session. To start a debug session, open a Terminal session, go to the directory containing debugger, and invoke debugger at the prompt:

[~]% cd /Volumes/ANSCA
[/Volumes/ANSCA]%./debugger
ANSCA Remote Debugger
Run the program you wish to debug

At this point, an Open dialog will appear just as you saw when launching the simulator. Navigate to a directory containing the main.lua file. As with the simulator, all assets that the main.lua file references must be in the same directory as the main.lua file itself.

Once you click okay, your application will launch under the simulator. The simulator will pause execution waiting for further commands from the debugger. Back in the terminal, the debugger will tell you that your program is paused.

The debugger always pauses at the first line of code to give you the opportunity to set breakpoints in your sample application. You can obtain a list of commands available in the debugger:

> help
backtrace(bt)         -- show backtrace
frame(f) <num>        -- switch to frame <num>
locals(l)             -- show local variables
dump(d)               -- prints value of variable 
setb(b) <file> <line> -- sets a breakpoint
delb <file> <line>    -- removes a breakpoint
delallb               -- removes all breakpoints
setw <exp>            -- adds a new watch expression
delw <index>          -- removes the watch expression at index
delallw               -- removes all watch expressions
run                   -- run until next breakpoint
continue(c)           -- same as 'run'
step(si)              -- run until next line, stepping into function calls
over(so)              -- run until next line, stepping over function calls
listb                 -- lists breakpoints
listw                 -- lists watch expressions
eval <exp>            -- evaluates expression on the current context and returns its value
print(p) <exp>        -- same as 'eval'
exec <stmt>           -- executes statement on the current context
basedir [<path>]      -- sets the base path of the remote application, or shows the current one
exit                  -- exits debugger

Note in the help that certain commands have abbreviations for convenience. These are listed in parentheses. When possible, the abbreviations match those in gdb, a popular open source debugger.

For example, backtraces (i.e. function stack traces) can be obtained using an alias bt instead of typing out backtrace:

> bt
*[  1] (nil) at /Volumes/rtt/apps/SampleCode/Fishies/main.lua:46

Here, we are at the outermost scope because we haven't called any functions. Therefore, the stack trace is one function deep. Note that line 46 is the first line of actual code in main.lua so that’s where the debugger pauses when it launches your application.

Let’s set some breakpoints, step through some code, and display values of local variables. To see what’s happening, here’s a snippet of the main.lua code we’ll be stepping through:

 96  local buttonListener = function( event )
 97    local group = event.target
 98
 99    -- tap only triggers change from original to different color
100    local topObject = group[1]
       ...
114  end

This code is the listener function that gets called when we tap on the fish. We’ll set a breakpoint at line 98 inside the listener (or callback) method that gets invoked when a tap event gets fired. Then tell the debugger to continue execution.

> b main.lua 98
> c

The listener where we set the breakpoint does not get called unless a tap event is fired. So once we click on a fish, the event fires and the debugger will pause execution at the breakpoint we set inside the listener. From there, we’ll be able to step over code one line at a time, and list all the local variables:

Paused at file main.lua line 98
> over
Paused at file main.lua line 100
> locals
group = table: 0x1cda88c0
event = table: 0x160f90

Both group and event are tables, so we can print the value of a specific property of the table or the entire contents of a table via dump:

> dump event.x
event.x(number) = 193
> dump event.y
event.y(number) = 52 
> dump event
event(table: 0x160f90) =
{
   y = 52
   x = 193
   name = "touch"
   phase = "ended"
   target = table: 0x1cda88c0
}

We can also do a stack trace like we did before:

> backtrace
*[  1] ? at /Volumes/rtt/apps/SampleCode/Fishies/main.lua:100
 [  2] (nil) at ?:0
 [  3] (nil) at ?:0

Function stack trace information is only available in your code. In this particular stack trace, no information is available for stack frames 2 and 3 because these are internal to ANSCA.

Finally, we let the application continue running. The debugger remains active until the simulator quits.

> continue
Program finished