Yeah, tell me about it... Ironically, despite the frustrations in trying to shake down the various pages and documentation on this, furiously asking "What do you want from me?!?!
" the answer ended up being rather simple - but obfuscated because of much of the intended utility all of the debug adapter extension shenanigans.
So, first off, there is the (newly created)
site for outlining the debug protocol that msft put together. It still focuses a lot on "So you want to make a debug adapter extension or something, eh?" and doesn't discuss the raw mechanics. However, those raw mechanics just aren't that much:
and that's...pretty much it. With some additional notes:
For one, in this case, I'm only launching the process because it implements the debug protocol directly - there isn't an adapter that has to reinterpret things to talk to another existing debugger (see: gdb, pdb, etc) or run in a node.js env. This is defined in what is currently a very light extension, that basically only
Contributes a debugger that defines the path to bsnes to launch, and a couple configuration attributes that will be tacked onto the Launch request (e.g. "program" to define what ROM to load up, or "stopAtEntry" to have the game start in a frozen state) which the bsnes debugger has to acknowledge.
Two, the specification for requests, responses, and events, are available
here (this was also available historically as, at the very least,
this TypeScript definition file in the VSCode github repo). As mentioned, those are JSON objects in HTTP messages, so the format of everything will be, with cr/lf visible, along the lines of:
Code: Select all
Content-Length: 331\r\n
\r\n
{"command":"initialize", "arguments": {"clientID":"vscode", "clientName":"Visual Studio Code", "adapterID":"bsnes debug", "pathFormat":"path", "linesStartAt1":true, "columnsStartAt1":true, "supportsVariableType":true, "supportsVariablePaging":true, "supportsRunInTerminalRequest":true, "locale":"en-us"}, "type":"request", "seq":1}
And the responses back have to be the same way, including the Content-Length header,
and including the "\r\n\r\n", no more, no less (see "responses and events are sent back..." above). I only mention this part because I was tearing my hair out for a couple of hours trying to understand why my initial implementation wasn't working, and it turned out I had stdout in text mode, not binary, so my "\r\n\r\n" was turning into "\r\r\n\r\r\n" which was causing a silent failure.
Getting back to the original question, though,
this implementation of a debug protocol written in C to do debugging of lua is what you're probably looking for in terms of raw code that peels these covers back. Of course, you can get a tease of my current implementation of this stuff over
here, too. Not yet shippable, and there's some stuff that's going to change as I go, but this is kind of the skeleton of it so far (note that ExternDebugHandler::processRequests is called as part of the Application::run tick, if you're wondering about the re-entry point of it all)