This project aims to provide a debug adapter that allows Microsoft's Visual Studio Code to step through Ravi or Lua 5.3 code.
Status
This is work in progress. The basic debugger is working with following features and limitations.
Launch a Ravi/Lua 5.3 script and stop on entry
Step through code
Set breakpoints at line/source level (upto a max of 20 breakpoints)
Local variables and variable arguments are shown in the Variables window; number of variables displayed is limited to 250
Tables are expanded to first few levels only - expansion limited to 250 elements
Lua stdout and stderr are redirected to the debugger
The debugger can step into dynamically generated Lua code
Support limited to x86-64 Windows 10, Ubuntu and OSX platforms
Unlike other Lua debuggers this implementation uses a custom Ravi VM, with extensions to support debugging
Various limitations - see list below
Note: This is work in progress so please expect bugs!
Installation
You can install the Ravi Debug extension from VSCode Marketplace - search for 'Lua and Ravi 5.3 Debugger'.
Pre-built X86 64-bit binaries for Windows 10, OS X Mojave, and Ubuntu 14.04 are included in the installation -
note that these do not have JIT enabled.
Issues and Limitations
The 'pause' function does not work, i.e. you cannot pause a running script
In all cases the number of variables or table entries displayed is truncated to 250 items
The stack trace is truncated to 50 items
Only upto 20 breakpoints can be set
You cannot set a breakpoint against a dynamically generated Lua function
You may not be able to debug Lua 5.0, 5.1 or 5.2 scripts - only 5.3 is tested and officially supported
Table variables can only be expanded to the first few levels
You cannot attach to a script already running somewhere
When the debugger runs the Lua Hook is disabled - so the running script is not allowed to modify the hook
Evaluating expressions is not supported
You cannot modify the variables displayed - the values are readonly
If you amend/edit the script being debugged it will not be recognised in the debug session so you will need to start a new session to recognise changes
Using LUA_PATH and LUA_CPATH has been tested briefly. When using LUA_CPATH you need to ensure that the native shared libraries are available on the system path; otherwise library dependencies can fail to be loaded.
Recent changes
Jul 2021: Updated to fix breaking change in VS Code Debug extension for breakpoints in 1.53 (breaking change in 1.42). Also revised the mechanism for supplying arguments to the script.
Jul 2020: Updated Ravi to 1.0 Beta4a
Dec 2019: Updated Ravi to latest version, added support for arguments to launch script
Feb 2017: Since VSCode 1.8 there is a bug in VSCode that messes up output to stdout - added a workaround for this bug. Details of bug are at issue #17526
Feb 2017: The debugger is now synced with Lua 5.3.4
Oct 2016: Added support for expanding tables to more than 1 level but still limited to first 4 or 5 levels
Oct 2016: Display of variable types - if __name metamethod is defined for user defined types then this is used
Oct 2016: Display of variable contents - if __tostring metamethod is defined for user defined types then this is used
Oct 2016: Variable type names are passed to VSCode so that these get displayed by the UI
Getting Started
Once you have installed the extension, you will need to setup launch.json as shown in the steps below.
The debugger is a standalone executable that can be invoked by VSCode. VSCode communicates
with the debugger via stdin/stdout as per the VSCode debug adapter API which uses
JSON messages exchanged between VSCode and the debugger.
