Skip to content

Latest commit

 

History

History
126 lines (115 loc) · 3.47 KB

README.md

File metadata and controls

126 lines (115 loc) · 3.47 KB

Luau Debugger

A debugger for Luau with debug adapter protocol(DAP) support.

Usage

  • Install luau-debugger extension
  • There are three ways to use this extension:
    • Launch: Directly run the debugger installed with the extension.
    • Attach: Attach to the luau runtime running externally.
    • Advance: Integrate luau-debugger into your own project.

Launch

  • Add a launch configuration in launch.json 
    {
  "configurations": [
    {
      "type": "luau",
      "request": "launch",
      "name": "launch luau debugger",
      "program": "${workspaceFolder}/main.lua",
      "port": 58000
    },
  ]
}
    • program: The path to the lua script you want to debug
    • port: The port number to communicate with the debugger
  • Press F5 to start debugging, enjoy!

Attach

  • Get a luaud executable from release which a luau runtime with debug support
  • Open lua folders in VSCode
  • Add a launch configuration in launch.json 
    {
  "configurations": [
    {
      "type": "luau",
      "request": "attach",
      "name": "attach to luau debugger",
      "address": "localhost",
      "port": 58000
    }
  ]
}
  • Using luaud [PORT] [LUA_ENTRY] to execute lua script with debug support: 
    luaud 58000 D:/my_lua_projects/hello_world.lua
  • Press F5 to start debugging, enjoy!

Integrate with luau-debugger in your project

  • Build luau-debugger from source
  • Use the interface provided by luau-debugger library.
    • You can refer to the implementation of luaud which is a minimal luau runtime integrated with luau-debugger.
  • Run your project and debug the luau code using a configuration similar to Attach.

Source File Mapping

  • Source file mapping is used to map the source file path from remote debugger server to VSCode workspace. Example: 
    {
  {
    "type": "luau",
    "request": "attach",
    "name": "attach with source map",
    "address": "localhost",
    "port": 58000,
    "sourceMap": {
      "D:/my_lua_projects": "${workspaceFolder}"
    }
  }
}
    • The above configuration will map the source file path D:/my_lua_projects/hello_world.lua to ${workspaceFolder}/hello_world.lua.

Features

  • Debugger features
    • Attach
    • Launch
    • Stop on entry
    • Breakpoints
      • Add break points when running (Considering thread safety)
      • Conditional breakpoints
      • Data breakpoints
      • Breakpoint hit count
    • Continue
    • Pause
    • StackTrace
      • StackTrace across coroutine boundary
      • Support switching stacktrace between different coroutines
    • Scopes
    • Get variables
      • Locals
      • Upvalues
    • Display variables
      • nil
      • boolean
      • number
      • string
      • table
        • nested table
        • table with cycle reference
      • vector
      • function
      • userdata
    • Set variables
    • Repl
    • Watch
    • Hover
    • Single step
      • Step in
      • Step over
      • Step out
    • Disconnect and reconnect
    • Print to debug console
    • Coroutine
    • Multiple lua vm
    • Source file mapping
    • Break from lua code (Call debug.break_here())