Should document required compiler options

[incansvl]

As a new user of both Nim and gdb-style debugging in vscode, I followed the installation instructions for this vscode extension but I was not getting proper debugger integration. Breakpoints were ignored, as were variable watches etc.

The Nim documentation says that by default the compiler operates in debug mode, however I found that the version of Nim I was using (installed via the choosenim tool) was defaulting to release mode-

$ nim -v
Nim Compiler Version 2.2.6 [Linux: amd64]
Compiled at 2025-10-31
Copyright (c) 2006-2025 by Andreas Rumpf

git hash: ab00c56904e3126ad826bb520d243513a139436a
active boot switches: -d:release

I needed to add a "Debug build" option to the vscode tasks.json file to enable debug output from the compiler to get the extension working-

tasks.json

{
    "version": "2.0.0",
    "tasks": [
        {
            "taskName": "Build for debug module.nim",
            "command": "nim",
            "args": ["c", "--verbosity:1" "--debuginfo:on", "--debugger:native", "--outdir:.", "src/${fileBasename}"],
            "options": {
                "cwd": "${workspaceRoot}"
            },
            "type": "shell",
            "group": {
                "kind": "build"
            }
        }, 
        ...
}

This might be obvious to experienced developers, but for the "rest of us" it would be helpful to highlight in the documentation that some compiler options may need to be changed to support debugger integration.

Software
Operating System: EndeavourOS
Kernel Version: 6.18.7-arch1-1 (64-bit)
Graphics Platform: Wayland
Nim: 2.2.6
gdb: 17.1
VSCodium: 1.108.10359

• Nim: 0.1.26
• Nim debugger: 0.3.1
• Native debug: 0.27.0

launch.json

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