a first attempt at an interactive lua debugger

[ab9rf]

implemented as a DAP listener on port 43030

enable with enable luadebugger. see devtools directory for related utilties

[SilasD]

What I tested with:
OS: Windows_NT x64 10.0.19045
Python 3.14.0
VSCode: Version: 1.141.2 (user setup)

Dwarf Fortress: v0.53.16 win64 ITCH
DFHack:
53.16-r2
53.16-r2-23-g882be94f
882be94

Where I'm at:

• the plugin successfully compiles and executes.
• the plugin gives sane output on the DFHack console:

[DFHack]# luadebugger start
luadebugger: listening for debug clients on 127.0.0.1:43030
[DFHack]# luadebugger status
luadebugger: listening on 127.0.0.1:43030
luadebugger: client not connected
[DFHack]# luadebugger stop
(no output)
[DFHack]# luadebugger status
luadebugger: not listening
luadebugger: client not connected

so far so good. next, problems.

[SilasD]

TL;DR: I couldn't get the python client to work.

The python script loads without syntax errors. if the plugin is not listening, the script aborts with a stacktrace.

ADMIN C:\Games\Dwarf Fortress\DFHack\devtools]python luadebug-cli.py
[... stacktrace removed ...]
ConnectionRefusedError: [WinError 10061] No connection could be made because the target machine actively refused it

If the plugin is listening, the python script prints one line: connected to 127.0.0.1:43030 ,
then hangs; it does not produce output and does not accept input.

The script aborts when I input a Ctrl-Break, and aborts with a stacktrace when I input a Ctrl-C:
KeyboardInterrupt

After a Ctrl-C, but not a Ctrl-Break, any input I tried to feed to the script is fed to the shell instead.
(Of course if I start the script using start python luadebug-cli.py or by double-clicking it,
it runs in a separate window and all queued input just vanishes.)

While the python script is running, the plugin reports that it is connected:

[DFHack]# luadebugger status
luadebugger: listening on 127.0.0.1:43030
luadebugger: client connected

Dwarf Fortress runs fairly normally; DFHack Lua execution is, as I expected, slow.
Keyboard input is particularly slow, and it often drops characters.

If I try to stop the plugin while the python script is hung, the plugin hangs.
Both DF and the DFHack console window are frozen.
The plugin shuts down cleanly when I Ctrl-C or Ctrl-Break the python script.

ADMIN C:\Games\Dwarf Fortress\DFHack\devtools]python luadebug-cli.py
connected to 127.0.0.1:43030
[... process is hung ...]

[DFHack]# luadebugger stop
[... hangs indefinitely ...]

[... input Ctrl-C to python script console window ...]
[... stacktrace removed ...]
KeyboardInterrupt

[... DFHack console resumes ...]
[DFHack]#

kinda stuck there; not enough diagnostics to continue exploring.

[SilasD]

TL;DR: I am unable to connect the VSCode debug interface to the Lua debugger.

Configuration:
vscode-dfhack-lua and its contents were copied via drag-and-drop into C:\Users\Silas\.vscode\extensions.
In under a second, VSCode took note of the change and updated extensions.json,
appending this info to its one long line of JSON.
{"identifier":{"id":"dfhack.dfhack-lua-debug"},"version":"0.1.0","location":{"$mid":1,
"fsPath":"c:\\Users\\Silas\\.vscode\\extensions\\vscode-dfhack-lua","_sep":1,
"external":"file:///c%3A/Users/Silas/.vscode/extensions/vscode-dfhack-lua",
"path":"/c:/Users/Silas/.vscode/extensions/vscode-dfhack-lua","scheme":"file"},
"relativeLocation":"vscode-dfhack-lua"}]

"launch" section of DFHack.code-workspace:

		// Global debug launch configuration. Should be used as an alternative to 'launch.json' that is shared across workspaces.
		"launch": {
		
			"version": "0.2.0",
			"inputs": [],
			"configurations": [
				{
					"type": "dfhack-lua",
					"request": "attach",
					"name": "Attach to DFHack",
					"host": "127.0.0.1",
					"port": 43030,
					"stopOnEntry": false
				},
				{
					"name": "Dwarf Fortress (Launch)",
					"type": "cppvsdbg",
					"request": "launch",
					//// Resolved by CMake Tools:
					//"program": "${cmake.testProgram}",
					//"args": [ "${cmake.testArgs}"],
					//"environment": "${cmake.testEnvironment}",
					"cwd": "${workspaceFolder}\\build\\win64\\DF",
					"program": "${workspaceFolder}\\build\\win64\\DF\\Dwarf Fortress.exe",
					"args": [],
					"environment": [],
					"stopAtEntry": false,
					"console": "integratedTerminal"
				},
				{
					"name": "Dwarf Fortress (Attach)",
					"type": "cppvsdbg",
					"request": "attach",
					"program": "${workspaceFolder}\\build\\win64\\DF\\Dwarf Fortress.exe",
				},
				{
					"name": "Dwarf Fortress Attach z5315",
					"type": "cppvsdbg",
					"request": "attach",
					"program": "C:\\Games\\Dwarf Fortress\\z5315\\Dwarf Fortress.exe",
				},
			],
			"compounds": []
		},
		"cmake.debugConfig": {
		
		}

launch.json:

{
    // 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",

    // https://github.com/microsoft/vscode-cmake-tools/blob/main/docs/debug-launch.md
    "configurations": [
    
        {
            "type": "dfhack-lua",
            "request": "attach",
            "name": "Attach to DFHack",
            "host": "127.0.0.1",
            "port": 43030,
            "stopOnEntry": false
        }
    ]
}

[SilasD]

I can activate and deactivate the extension without issues. While the extension is disabled, the "dfhack-lua"
sections of both the DFHack.code-workspace launch key and the launch.json file show yellow squiggles
for the "type": "dfhack-lua", key/value, as well asn the "host" and "stopOnEntry" keys.

The Run-and-Debug sidebar sees both launch.json and the launch section of the code-workspace:

---

When I actually attempt to Debug, I get this error, whether or not the plugin is listening:

and I'm stuck there.