Project Description

MobDebug is a remote debugger for Lua (including Lua 5.1, Lua 5.2, Lua 5.3, Lua 5.4, and LuaJIT 2.x).

Dependencies

MobDebug depends on LuaSocket 2.0+ and has been tested with Lua 5.1, Lua 5.2, Lua 5.3, and Lua 5.4. MobDebug also works with LuaJIT v2.0+; using loop and scratchpad methods requires v2.0.1.

Troubleshooting

Generally, breakpoints set with in the debugger should work without any additional configuration, but there may be cases when this doesn’t work out of the box, which may happen for several reasons:

• A breakpoint may be inside a coroutine; by default breakpoints inside coroutines are not triggered. To enable debugging in coroutines, including triggering of breakpoints, you may either (1) add require('mobdebug').on() call to that coroutine, which will enable debugging for that particular coroutine, or (2) add require('mobdebug').coro() call to your script, which will enable debugging for all coroutines created using coroutine.create later in the script.
• If you enable coroutine debugging using require('mobdebug').coro(), this will not affect coroutines created using C API or Lua code wrapped into coroutine.wrap. You can still debug those fragments after adding require('mobdebug').on() to the coroutine code.
• The path of the file known to the debugger (the caller of setb command) may not be the same as the path known to the Lua engine (running the code being debugged). For example, if you use an embedded engine, you may want to check if the path reported by the engine is normalized (doesn’t include ../ references) by checking the result of debug.getinfo(1,"S").source.
• The capitalization of the file known to the debugger may not be the same as the capitalization of the file known to the Lua engine with the latter running on a case-sensitive system. For example, if you set a breakpoint on the file TEST.lua in the debugger running on Window (case-insensitive), it may not fire in the application running test.lua on Linux (with case-sensitive file system). To avoid this make sure that the capitalization for your project files is the same on both file systems.
• The script you are debugging may change the current folder (for example, using lfs module) and load the script (using dofile) from the changed folder. To make breakpoints work in this case you may want to use absolute path with dofile.
• You may have a symlink in your path and be referencing paths to your scripts differently in the code and in the debugger (using a path with symlink in one case and not using it in the other case).
• You may be using your own Lua engine that doesn’t report file names relative to the project directory (as set in the debugger). For example, you set the project directory pointing to scripts folder (with common subfolder) and the engine reports the file name as myfile.lua instead of common/myfile.lua; the debugger will be looking for scripts/myfile.lua instead of scripts/common/myfile.lua and the file will not be activated and the breakpoints won’t work. You may also be using inconsistent path separators in the file names; for example, common/myfile.lua in one case and common\myfile.lua in another.
• If you are loading files using luaL_loadbuffer, make sure that the chunk name specified (the last parameter) matches the file location.
• If you set/remove breakpoints while the application is running, these changes may not have any effect if only a small number of Lua commands get executed. To limit the negative impact of socket checks for pending messages, the debugger in the application only checks for incoming requests every 200 statements (by default), so if your tests include fewer statements, then pause/break commands and toggling breakpoints without suspending the application may not work. To make the debugger to check more frequently, you can update checkcount field (require('mobdebug').checkcount = 1) before or after debugging is started.

Author

Paul Kulchenko (paul@kulchenko.com)