Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tomblind/local-lua-debugger-vscode
Local Lua Debugger for VSCode
https://github.com/tomblind/local-lua-debugger-vscode
Last synced: 9 days ago
JSON representation
Local Lua Debugger for VSCode
- Host: GitHub
- URL: https://github.com/tomblind/local-lua-debugger-vscode
- Owner: tomblind
- License: mit
- Created: 2019-04-17T13:15:01.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-04-30T22:19:09.000Z (over 1 year ago)
- Last Synced: 2024-10-31T12:50:56.971Z (16 days ago)
- Language: TypeScript
- Size: 599 KB
- Stars: 107
- Watchers: 10
- Forks: 26
- Open Issues: 37
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Local Lua Debugger for Visual Studio Code
A simple Lua debugger which requires no additional dependencies.
---
## Notice of Breaking Change
Beginning in version 0.3.0, projects which use sourcemaps to debug code transpiled from another language (such as TypescriptToLua), **must** specify the [`scriptFiles`](#scriptFiles) launch configuration option in order to use breakpoints in the original source files. This allows these to be resolved at startup instead of at runtime which allows for a significant performance increase.
---
## Features
- Debug Lua using stand-alone interpretor or a custom executable
- Supports Lua versions 5.1, 5.2, 5.3 and [LuaJIT](https://luajit.org/)
- Basic debugging features (stepping, inspecting, breakpoints, etc...)
- Conditional breakpoints
- Debug coroutines as separate threads
- Basic support for source maps, such as those generated by [TypescriptToLua](https://typescripttolua.github.io/)
---
## Usage
### Lua Stand-Alone Interpreter
To debug a Lua program using a stand-alone interpreter, set `lua-local.interpreter` in your user or workspace settings:
!["lua-local.interpreter": "lua5.1"](resources/settings.png '"lua-local.interpreter": "lua5.1"')
Alternatively, you can set the interpreter and file to run in `launch.json`:
```json
{
"configurations": [
{
"type": "lua-local",
"request": "launch",
"name": "Debug",
"program": {
"lua": "lua5.1",
"file": "main.lua"
}
}
]
}
```
### Custom Lua Environment
To debug using a custom Lua executable, you must set up your `launch.json` with the name/path of the executable and any additional arguments that may be needed.
```json
{
"configurations": [
{
"type": "lua-local",
"request": "launch",
"name": "Debug Custom Executable",
"program": {
"command": "executable"
},
"args": [
"${workspaceFolder}"
]
}
]
}
```
You must then manually start the debugger in your Lua code:
```lua
require("lldebugger").start()
```
Note that the path to `lldebugger` will automatically be appended to the `LUA_PATH` environment variable, so it can be found by Lua.
---
## Requirements & Limitations
- The Lua environment must support communication via either stdio or pipes (named pipes on Windows, fifos on Linux).
- Some enviroments may require command line options to support stdio communication (ex. Solar2D requires `/no-console` flag)
- Use of `io.read` or other calls that require user input will cause problems in stdio mode. Set [`program.communication`](#program.communication) to `pipe` to work around this.
- The Lua environment must be built with the `debug` library, and no other code should attempt to set debug hooks.
- You cannot manually pause debugging while the program is running.
- In Lua 5.1 and LuaJIT, the main thread cannot be accessed while stopped inside of a coroutine.
---
## Tips
- For convenience, a global reference to the debugger is always stored as `lldebugger`.
- You can detect that the debugger extension is attached by inspecting the environment variable `LOCAL_LUA_DEBUGGER_VSCODE`. This is useful for conditionally starting the debugger in custom environments.
```lua
if os.getenv("LOCAL_LUA_DEBUGGER_VSCODE") == "1" then
require("lldebugger").start()
end
```
- Some custom environments will not break on uncaught runtime errors. To catch a runtime error, you can wrap the code with `lldebugger.call()`:
```lua
lldebugger.call(function()
--code causing runtime error
end)
```
- Some environments will not load required files from the standard filesystem. In these cases, you may be able to load the debugger manually using the file path stored in `LOCAL_LUA_DEBUGGER_FILEPATH`:
```lua
package.loaded["lldebugger"] = assert(loadfile(os.getenv("LOCAL_LUA_DEBUGGER_FILEPATH")))()
require("lldebugger").start()
```
---
## Additional Configuration Options
#### `scriptRoots`
A list of alternate paths to find Lua scripts. This is useful for environments like LÖVE, which use custom resolvers to find scripts in other locations than what is in `package.config`.
#### `scriptFiles`
A list of glob patterns identifying where to find Lua scripts in the workspace when debugging. This is required for placing breakpoints in sourcemapped files (ex. 'ts' scripts when using TypescriptToLua), as the source files must be looked up ahead of time so that breakpoints can be resolved.
Example: `scriptFiles: ["**/*.lua"]`
#### `ignorePatterns`
A list of [Lua patterns](https://www.lua.org/manual/5.4/manual.html#6.4.1) that specifies files to skip when stepping through code.
Example: `ignorePatterns: ["^/usr"]`
#### `stepUnmappedLines`
Step into Lua when stepping through source-mapped code and no mapping is available for the current line.
#### `breakInCoroutines`
Break into the debugger when errors occur inside coroutines.
- Coroutines created with `coroutine.wrap` will always break, regardless of this option.
- In Lua 5.1, this will break where the coroutine was resumed and the message will contain the actual location of the error.
#### `stopOnEntry`
Automatically break on first line after debug hook is set.
#### `cwd`
Specify working directory to launch executable in. Default is the project directory.
#### `args`
List of arguments to pass to Lua script or custom environment when launching.
#### `env`
Specify environment variables to set when launching executable.
#### `program.communication`
Specifies how the extension communicates with the debugger.
Possible values:
- `stdio` (default): Messages are embeded in stdin and stdout.
- `pipe`: Pipes are created for passing messages (named pipes on Windows, fifos on Linux). Use this if your environment has issues with stdio communication.
#### `verbose`
Enable verbose output from debugger. Only useful when trying to identify problems with the debugger itself.
---
## Custom Environment Examples
### LÖVE
```json
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug Love",
"type": "lua-local",
"request": "launch",
"program": {
"command": "love"
},
"args": [
"game"
],
"scriptRoots": [
"game"
]
}
]
}
```
```lua
if os.getenv("LOCAL_LUA_DEBUGGER_VSCODE") == "1" then
require("lldebugger").start()
end
function love.load()
...
```
**Note** that `console` must be set to `false` (the default value) in `conf.lua`, or the debugger will not be able to communicate with the running program.
**game/conf.lua**
```lua
function love.conf(t)
t.console = false
end
```
### Busted
Note that even when using busted via a lua interpreter, it must be set up as a custom environment to work correctly.
```json
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug Busted CLI",
"type": "lua-local",
"request": "launch",
"program": {
"command": "busted"
},
"args": [
"test/start-cli.lua"
],
"ignorePatterns": "^/usr"
},
{
"name": "Debug Busted via Lua Interpreter",
"type": "lua-local",
"request": "launch",
"program": {
"command": "lua"
},
"args": [
"test/start-interpreter.lua"
],
"ignorePatterns": "^/usr"
}
]
}
```
**test/start-cli.lua**
```lua
if os.getenv("LOCAL_LUA_DEBUGGER_VSCODE") == "1" then
require("lldebugger").start()
end
describe("a test", function()
...
end)
```
**test/start-interpreter.lua**
```lua
--busted should be required before hooking debugger to avoid double-hooking
require("busted.runner")()
if os.getenv("LOCAL_LUA_DEBUGGER_VSCODE") == "1" then
require("lldebugger").start()
end
describe("a test", function()
...
end)
```
### Defold
```js
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug",
"type": "lua-local",
"request": "launch",
"program": {
"command": "dmengine"
},
"args": ["./build/default/game.projectc"],
"scriptRoots": ["."] // Required for debugger to find scripts
}
]
}
```
```lua
if os.getenv("LOCAL_LUA_DEBUGGER_VSCODE") == "1" then
local lldebugger = loadfile(os.getenv("LOCAL_LUA_DEBUGGER_FILEPATH"))()
lldebugger.start()
end
function init(self)
...
end
```
Information on downloading dmengine for your platform can be found [here](https://forum.defold.com/t/editor-2-dmengine-versions/9605).
### Solar2D / Corona
```json
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug",
"type": "lua-local",
"request": "launch",
"windows": {
"program": {
"command": "C:\\Program Files (x86)\\Corona Labs\\Corona\\Corona Simulator.exe",
},
"args": [
"/no-console",
"/debug",
"${workspaceFolder}\\main.lua"
]
},
"osx": {
"program": {
"command": "/Applications/Corona/CoronaSimulator.app/Contents/MacOS/CoronaSimulator",
},
"args": [
"-no-console"
"YES"
"-debug"
"1"
"-project"
"${workspaceFolder}/main.lua"
]
}
}
]
}
```
```lua
if os.getenv("LOCAL_LUA_DEBUGGER_VSCODE") == "1" then
local lldebugger = loadfile(os.getenv("LOCAL_LUA_DEBUGGER_FILEPATH"))()
lldebugger.start()
end
...
```
### TypescriptToLua (Custom Environment)
```js
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug TSTL",
"type": "lua-local",
"request": "launch",
"program": {
"command": "my_custom_environment"
},
"args": [
...
],
"scriptFiles": ["**/*.lua"] // Required for breakpoints in ts files to work
}
]
}
```
```lua
if os.getenv("LOCAL_LUA_DEBUGGER_VSCODE") == "1" then
require("lldebugger").start()
end
...
```
**tsconfig.json**
```js
{
"compilerOptions": {
"sourceMap": true,
...
},
"tstl": {
"noResolvePaths": ["lldebugger"] // Required so TSTL ignores the missing dependency
}
}
```