Guide: Debugging mixed Lua/C projects with VSCode

SDK Development Discussion
, ,
1

This guide walks through configuring VSCode to simultaneously debug Lua and C code. This might be helpful if you are using C code in your Lua game for performance reasons.

This guide currently targets macOS. It should be possible to get a similar configuration working on Windows/Linux, but you will likely need to debug with MSVC or GDB instead of LLDB.

Both Make and CMake are supported, but they are configured slightly differently. Choose your own adventure!

Particles Walkthrough

  1. Open the Particles project in the PlaydateSDK with VSCode (PlaydateSDK/C_API/Examples/Particles)

  2. Install the following VSCode extensions:

  1. Configure the build task:

If using Make:

  • Install the Makefile Tools VSCode extension
  • Run the command Makefile: Configure from the command palette (Command + Shift + P)
  • Click "Yes" on the dialog box that pops up
  • Create .vscode/tasks.json with the following contents:
{
  // See https://go.microsoft.com/fwlink/?LinkId=733558
  // for the documentation about the tasks.json format
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Build",
      "command": "${command:makefile.buildAll}"
    }
  ]
}

If using CMake:

  • Install the CMake Tools VSCode extension
  • Run the command CMake: Configure from the command palette (Command + Shift + P)
  • Select any Clang compiler kit from the dropdown
  • Create .vscode/tasks.json with the following contents:
{
  // See https://go.microsoft.com/fwlink/?LinkId=733558
  // for the documentation about the tasks.json format
  "version": "2.0.0",
  "tasks": [
    {
      "type": "cmake",
      "label": "Build",
      "command": "build",
      "targets": ["all"],
      "group": "build",
      "problemMatcher": []
    }
  ]
}

For both Make/CMake:

  1. Create .vscode/launch.json with the following contents:
{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "name": "(lldb) Launch",
      "type": "cppdbg",
      "request": "launch",
      "program": "/path/to/PlaydateSDK/bin/Playdate Simulator.app/Contents/MacOS/Playdate Simulator",
      "args": [],
      "stopAtEntry": false,
      "cwd": "${workspaceFolder}",
      "environment": [],
      "externalConsole": false,
      "MIMode": "lldb"
    },
    {
      "type": "playdate",
      "request": "launch",
      "name": "Playdate: Debug"
    }
  ],
  "compounds": [
    {
      "name": "Playdate: Lua/C Debug",
      "configurations": ["(lldb) Launch", "Playdate: Debug"],
      "stopAll": true,
      "preLaunchTask": "Build"
    }
  ]
}

  1. Replace /path/to/PlaydateSDK in the above configuration with the path to your local Playdate SDK installation

  2. Launch the "Playdate: Lua/C Debug" configuration from the "Run and Debug" view in the activity bar

VSCode should build your project using either Make or CMake, launch the simulator and attach both the C and Lua debuggers. You should now be able to drop breakpoints inside main.c or main.lua to stop the game for debugging.

9 Likes