Lua Debugger


This Lua debugger is outdated and incompatible with Textadept 5 and higher. It cannot be upgraded to use Lua 5.2. To understand why, the debugger must be described.

Debugger Internals

This debugger runs code in a separate thread (coroutine), but alongside the main thread. This means you do not have to modify your existing code to allow a debugger to connect to it or vice-versa.

A modified _G environment is created for the code to debug. In Lua 5.1, setfenv was used. This "sandboxes" the code so that it will not mess with the debugger's Lua state.

Next the code is wrapped in a coroutine, a debug hook is set, and the coroutine is run. Inside the debug hook, the coroutine is yielded back to the debugger upon hitting a breakpoint, watchpoint, or when stepping through code. This allows the UI to not block and the user to control when to step back into the code. When the user executes an action like "continue", the coroutine is resumed, suspending the main thread and running the code.

What is the Problem Now?

Lua 5.1 does a good job keeping the debugger's global environment and the coroutine's global environment separate. How, I'm not sure, but it might have to do with setfenv. As Lua runs the code, it creates temporary variables. For example, the code

for i = 1, 5 do
  print('i = ', i)

has Lua create a temporary, local loop variable i. When stepping through this code one line at a time, the code yields to the user each time. The debugger code may do many things while the user is interacting with it, including creating more temporary, local variables. However, when the user resumes execution, the coroutine's global environment and temporary, local variables are seemingly untouched and unaffected. Thus execution continues as normal.

In Lua 5.2, the global environments appear to no longer be separated. When testing a new debugger, the variable i in the example above had a string value from a variable in the debugger's global environment after yielding to the user and resuming execution. Because of the seemingly shared environments, the code's global environment appears to be modifiable during debugging which is unacceptable.

What I Have Tried

For the 5.2 debugger I have tried to:

In C:

  1. Set LUA_RIDX_GLOBALS both before and after loading the chunk via luaL_loadfile.
  2. Set the 1st upvalue of the Lua chunk to be a new debug global environment table via lua_setupvalue after luaL_loadfile.

In Lua:

  1. Set the function environment via load.
  2. Set _ENV both before and after the chunk is loaded with load.

In all of these cases, each thread seemed to use the same global environment for their temporary variables and conflicts occurred.


Unzip the above archive into your ~/.textadept directory; it inflates into modules/textadept/debugger.lua and modules/lua/debugger.lua.

In your modules/lua/post_init.lua, add the following:

require 'lua.debugger'

Then you can load and debug Lua files.

















The command entry acts like the Lua interpreter's prompt. There are additional variables available:

so =_LOCALS will display all local variables, etc.

You can use key commands instead of the menu:

keys.lua[keys.LANGUAGE_MODULE_PREFIX].d = {
  d = debugger.start,
  q = debugger.stop,
  c = debugger.continue,
  n = debugger.step_over,
  s = debugger.step_into,
  o = debugger.step_out,
  i = debugger.inspect,
  l = debugger.call_stack,
  b = debugger.toggle_breakpoint,
  B = debugger.delete_breakpoint,
  w = debugger.set_watch,
  W = debugger.delete_watch

To enable a clickable margin for breakpoints, modify your theme's view.lua to have

buffer.margin_width_n[1] = 16
buffer.margin_sensitive_n[1] = true

(By default margin_width_n[1] is 0.)
Added the file “”.
Added the file “debugger01.png”.
Added the file “debugger02.png”.
Added the file “debugger03.png”.
Added the file “debugger04.png”.
Added the file “debugger05.png”.
Added the file “debugger06.png”.
Added the file “debugger07.png”.
Added the file “debugger08.png”.
Added the file “debugger09.png”.
Added the file “debugger10.png”.
Added the file “debugger11.png”.
Added the file “debugger12.png”.
Added the file “debugger13.png”.
Added the file “debugger14.png”.
Added the file “debugger15.png”.
Added the file “debugger16.png”.

Edited on Thursday, September 20th 2012 at 7:39 PM.