RemDebug

Introduction

RemDebug is a Lua debugger that uses LuaSocket to allow the remote debugging of Lua and CGILua scripts.

RemDebug allows you to run the debugger user interface on one system (the local system or the client), while running the debug engine on another system (the remote system or the engine).

Advantages of remote debugging

Remote debugging offers the following advantages over a local debugging session:

• It allows the debugging of programming running on other user's system. Sometimes you don't have direct access to that system or the behavior there is different than on your local system for some reason.

• It allows the debugging of a program that has a graphical user interface. On such cases the use of the debugger in the same machine as the target application can interfere with the drawing routines for example.

• It allows the debugging of web based programs. CGILua for example does not offer any debugging facility built in, so Rem Debugs? makes it a lot easier to follow the execution of Lua Scripts or Lua Pages.

Using RemDebug

To execute a RemDebug session you have to start first the RemDebug client, then start the engine. The client will listen for connections from the engine and, after a connection is made, the client will be able to send commands.

• RemDebug offers an API that abstracts local and remote sessions. The API has commands for setting breakpoints, watch expressions, and to control the script's execution. RemDebug implements that API using the low-level concepts of the Lua debug API. A module exports this API via a socket (the API becomes a protocol, in other words). Pipes could be another form of communication.

• A use case for a web debugging session would be: the user begins the debugging session by starting the RemDebug client, the client starts listening to a socket, the user runs the application (which does a require"remdebug.engine"), the engine connects with the client and waits for commands.
  • Configuration for this debugging session would be through a configuration file that the debug engine loads. The default would be to use localhost and some port. Using this setup the client can be started before the engine, and this is critical for the debugging of web scripts.

  • For web apps, you first put the application one step short of the request you want to debug, then start the debug client and do the last request. Using this approach you would need some way to tell the web application to run the debugger, but that is easily done through the use of configuration files in the web app.

  • Letting the debug client listen and the debug engine initiate the connection makes the debugging of web apps easier, and could allow several Xavante threads to be debugged at the same time for example.

• RemDebug will offer one or more instances of the API with IDEs such as Eclipse and a command line version like gdb. Once we have a protocol, this is a case of implementing a client for it as a plugin for the IDE.

The Protocol

RemDebug uses a text-based protocol very similar to FTP, where requests made by the client get responses from the engine.

Requests can be Breakpoints, Watch expressions, Evaluations and Executions. Requests and responses can refer to expressions, handles, filenames and line numbers:

• Breakpoints are defined by a line in a filename
  • SETB filename line - Defines a breakpoint
  • DELB filename line - Deletes a breakpoint

• Watch expressions are evaluated at each engine step and causes the pause of the execution when true.
  • SETW filename expression - Defines a watch expression for a filename. The engine response is a handle to the expression.
  • DELW handle - Deletes the watch expression corresponding to handle from the engine.

• Evaluations can be done during pauses in the execution.
  • EVAL expression - Evaluates an expression on the current execution environment. The engine response is the result of the expression evaluation

• Executions are sequences of engine steps.
  • GOTO filename line - Executes the program until a line in a filename is reached or the program ends.
  • RUN - Runs the program until a breakpoint is found, a watch expression evaluates to true or the program ends
  • INTO - Steps into a function call
  • OVER - Steps over a function call

Responses uses codes to indicate the result of a request. Codes can be:

• 200 OK [result]
  • Denotes that the operation was succesful.
  • Applies to all requests.
  • In the case of Evaluations, there is an optional result value. Obs: we need to find out how to handle line breaks in the result.

• 201 Created handle
  • Denotes that a new watch expression has been created and associated with the returned handle.
  • Applies to SETW.

• 202 Paused filename line
  • Denotes a pause in the application execution occurred at a line in a filename.
  • Applies to Executions.

• 400 Bad Request
  • Denotes a syntactical error in the request.
  • Applies to all requests.

• 500 Server Error
  • Denotes an error in the engine during the request processing.
  • Applies to all requests