Revision as of 13:50, 18 November 2011

Lua Development Tools Debugger

Remote Debug

The Debugger of Lua Development Tools is based on the DBGP protocol.
The IDE contains a DBGP server. To connect to this server, and begin remote/attach debugging, you need to get our DBGP lua client.

DBGP Client

The DBGP Lua client is composed of two lua files (debugger.lua and debugintrospection.lua).
It runs on Unix-like OS and Windows (XP and later). It is written in Lua 5.1 and depends on lua-socket.
You can get Lua on http://www.lua.org/download.html and install lua-socket thanks to luarocks, or via your official OS repositories.

To use it, you must have these two files in your lua path.
To begin the connection, you must execute this lua code :

> local initconnection = require("debugger")
> initconnection(host, port, idekey)

or shortly

> require("debugger")(host, port, idekey)

• host: the host name or the IP address of the DBGP server (thus, of your IDE).
  • if host is nil, the DBGP_IDEHOST environment variable is used.
  • if the environment variable is nil, the default value '127.0.0.1' is used.
• port: the port of the DBGP server (must be configured in the IDE).
  • if port is nil, the DBGP_IDEPORT environment variable is used.
  • if the environment variable is nil, the default value '10000' is used.
• idekey: a string which is used as session key (must be configured in the IDE).
  • if IDEKEY is nil, the DBGP_IDEKEY environment variable is used.
  • if the environment variable is nil, the default value 'luaidekey' is used.

So, To debug your application you could do :

lua -e "require('debugger')("idehost","ideport");" MyApp.lua 

DBGP Server

The DBGP Server is integrated in LDT.
In order to accept incoming debug sessions, you must create a new Remote Lua Application launch configuration, then launch it.

• Project : Set the LDT project in your workspace which includes the Lua source file(s) of the application you want to debug.
  
• IdeKey : Default value is luaidekey, if you need to debug more than one application at the same time, you should change it to associate a launch configuration with only one application to debug.
  
• Remote Source Mapping : This parameter is used to set the mapping between the source files used at runtime and the source files in the workspace of the IDE.

For example, if your run your application this way:

$cd /my/runtime/path
$lua -e "require('debugger')();" MyApp.lua 

You should define /my/runtime/path as working directory. (On Windows : you should use this notation /x:/myruntime/path)

Debug features

Supported features

Breakpoints, code navigation

You can set breakpoints at a particular file/line, you can do it with the regular double-click on margin:

You can then specify some conditions to stop execution only under certain circumstances:

1. Enable or disable breakpoint globally
   
2. Condition on hit count (stop only after 3rd hit, each 4 reaches, ...)
3. Conditional breakpoint: you can put any expression, it will be evaluated in the local scope each time breakpoint is reached and break only when expression is evaluated to true.

Once a breakpoint has been reached and breaks, you can use usual step into, step over and step out commands.

Coroutine handling
When the current instruction is a coroutine.yield or a coroutine.resume step over will jump over the coroutine until the next resume or yield whereas step into will go into the coroutine and re-break as soon as possible.

Environment inspection

When a breakpoint is reached, you can see any variable visible from any stack frame (local, upvalue and global variables). You can also change values to another.

New values are expressions
When you set a new value, it is evaluated as expression, so math.sqrt will be evaluated to a function, if you want to put a literal string, use Lua syntax: "math.sqrt". In particular you can change an entire table by another table expression. This is sometimes powerful and sometimes dangerous, be careful with that.

Some special values can also be displayed such as metatables or function environments (if it is different from global environment). You can also change these values.

Interactive console and expressions

In addition to variable view, you have two other useful tools to evaluate some code snippets: expressions view and interactive console.

The expressions view allows you to re-evaluate complex expressions at each step

The interactive console allows you to type statements under the local scope

Always on top level
Due to a limitation from DBGP protocol, the interactive console and expressions are always mapped to the top stack frame !

Unsupported features

The dynamic code is not supported, it means that any code that is loaded with load, loadstring will not be supported. The debugger will step over it just like a C function.

The only well tested virtual machine is Lua 5.1. Any other implementation (Lua 5.2, LuaJIT^[1], ...) is not guaranteed to work at this time.

1. ↑ http://lua-users.org/lists/lua-l/2011-11/msg00583.html