nim-debugger-mi

A GDB/MI proxy for Nim that provides transparent symbol mangling/demangling for a better debugging experience in IDEs.

Features

• Transparent Symbol Translation: Automatically demangles Nim symbols in GDB output and mangles user input
• Function Name Demangling: Shows readable function names in call stacks (both Nim and C++ styles)
• Internal Variable Renaming: Displays compiler-generated variables with readable names
• Native Debugging: Works with standard GDB/LLDB through the MI protocol
• VSCode Integration: Seamless integration with VSCode's native debugger
• Cross-platform: Linux/MacOS/Windows

TODO: wrap around msvscode-cpptools DAP

Installation

nimble install nim_debugger_mi

Usage

With VSCode

Install the "Nim Debugger" VSCode extension for automatic configuration, or manually configure your launch.json:

Linux/WSL

{
    "name": "Nim",
    "type": "cppdbg",
    "request": "launch",
    "program": "${fileDirname}/${fileBasenameNoExtension}",
    "miDebuggerPath": "${userHome}/.nimble/bin/nim_debugger_mi",
    "miDebuggerArgs": "", //you may specify gdb path by --gdb=/path/to/your/gdb
    "MIMode": "gdb",
    "args": [],
    "cwd": "${workspaceFolder}"
}

Mac

{
    "name": "Nim",
    "type": "cppdbg",
    "request": "launch",
    "program": "${fileDirname}/${fileBasenameNoExtension}",
    "miDebuggerPath": "${userHome}/.nimble/bin/nim_debugger_mi",
    "miDebuggerArgs": "--lldb", //you may specify lldb path by --lldb=/path/to/your/lldb-mi
    "MIMode": "lldb",
    "args": [],
    "cwd": "${workspaceFolder}"
}

Windows

{
    "name": "Nim",
    "type": "cppdbg",
    "request": "launch",
    "program": "${fileDirname}/${fileBasenameNoExtension}",
    "miDebuggerPath": "${userHome}/.nimble/bin/nim_debugger_mi.cmd",
    "miDebuggerArgs": "", //you may specify gdb path by --gdb=/path/to/your/gdb.exe
    "MIMode": "gdb",
    "args": [],
    "cwd": "${workspaceFolder}"
}

before starting debugging, you should build your binary with debuginfo:

nim c --debuginfo -d:debug --debugger:native ./src/main.nim

How It Works

The proxy sits between your IDE and GDB, transforming symbols bidirectionally:

Output (GDB → IDE):

• localVar_1 → localVar
• _ZN4test4mainE → test::main
• T5_ → [tmp5]

Input (IDE → GDB):

• localVar → localVar_1
• [tmp5] → T5_

Building from Source

git clone https://github.com/yesdrx/nim-debugger-mi
cd nim-debugger-mi
nimble build

Requirements

• Nim >= 1.6.0
• GDB or LLDB
• C compiler (for custom process management)

License

MIT License - see LICENSE file for details

Author

yesdrx