New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Debug protocol documentation #19

Closed
dibyendumajumdar opened this Issue Mar 24, 2016 · 21 comments

Comments

Projects
None yet
4 participants
@dibyendumajumdar

dibyendumajumdar commented Mar 24, 2016

Hi, I am looking for the protocol documentation so that I can implement a debug adapter in C.

@gregg-miskelly

This comment has been minimized.

Show comment
Hide comment
@dibyendumajumdar

This comment has been minimized.

Show comment
Hide comment
@dibyendumajumdar

dibyendumajumdar Mar 24, 2016

How am I supposed to implement this in C? This looks more like an API rather than a wire protocol.

dibyendumajumdar commented Mar 24, 2016

How am I supposed to implement this in C? This looks more like an API rather than a wire protocol.

@gregg-miskelly

This comment has been minimized.

Show comment
Hide comment
@gregg-miskelly

gregg-miskelly Mar 24, 2016

Contributor

To set expectations - I am not on the VS Code team, just trying to be helpful.

The lowest level wire protocol is really simple - just text with a 'Content-Length:' and a bit more around it. See https://github.com/Microsoft/vscode-mono-debug/blob/e033812929f9621645316737f90233e433050cc0/src/Protocol.cs#L154 for an example of parsing it in C#.

The real protocol is JSON on top of the text. The first link I sent you has the spec for the JSON.

Contributor

gregg-miskelly commented Mar 24, 2016

To set expectations - I am not on the VS Code team, just trying to be helpful.

The lowest level wire protocol is really simple - just text with a 'Content-Length:' and a bit more around it. See https://github.com/Microsoft/vscode-mono-debug/blob/e033812929f9621645316737f90233e433050cc0/src/Protocol.cs#L154 for an example of parsing it in C#.

The real protocol is JSON on top of the text. The first link I sent you has the spec for the JSON.

@dibyendumajumdar

This comment has been minimized.

Show comment
Hide comment
@dibyendumajumdar

dibyendumajumdar Mar 24, 2016

Thanks! It would be good to have some info on the wire protocol maybe as comments within the typescript spec.

dibyendumajumdar commented Mar 24, 2016

Thanks! It would be good to have some info on the wire protocol maybe as comments within the typescript spec.

@weinand weinand self-assigned this Mar 26, 2016

@weinand weinand added this to the backlog milestone Mar 26, 2016

@dibyendumajumdar

This comment has been minimized.

Show comment
Hide comment
@dibyendumajumdar

dibyendumajumdar Apr 4, 2016

Hi,
I am trying to implement a debugger but not having much success. Problem is that I cannot see whether VSCode is happy with the messages it is getting from the debugger server or not. Here is an example of the interaction (captured by my code, reformatted for readability) - please let me know if something is wrong with this interaction:

{"type":"request","seq":1,"command":"initialize","arguments":{"adapterID":"lua","pathFormat":"path","linesStartAt1":true,"columnsStartAt1":true}}

Content-Length: 46
{"type":"event","seq":1,"event":"initialized"}

Content-Length: 239
{"type":"response","seq":2,"command":"initialize","request_seq":1,"success":true,"body":{"supportsConfigurationDoneRequest":true,"supportsFunctionBreakpoints":false,"supportsConditionalBreakpoints":false,"supportsEvaluateForHovers":false}}

{"type":"request","seq":2,"command":"evaluate","arguments":{"expression":"help","context":"repl"}}

Content-Length: 110
{"type":"response","seq":3,"command":"evaluate","request_seq":2,"success":false,"error":"not yet implemented"}

{"type":"request","seq":4,"command":"disconnect","arguments":{"restart":false}}

Content-Length: 81
{"type":"response","seq":5,"command":"disconnect","request_seq":4,"success":true}

Thanks!

dibyendumajumdar commented Apr 4, 2016

Hi,
I am trying to implement a debugger but not having much success. Problem is that I cannot see whether VSCode is happy with the messages it is getting from the debugger server or not. Here is an example of the interaction (captured by my code, reformatted for readability) - please let me know if something is wrong with this interaction:

{"type":"request","seq":1,"command":"initialize","arguments":{"adapterID":"lua","pathFormat":"path","linesStartAt1":true,"columnsStartAt1":true}}

Content-Length: 46
{"type":"event","seq":1,"event":"initialized"}

Content-Length: 239
{"type":"response","seq":2,"command":"initialize","request_seq":1,"success":true,"body":{"supportsConfigurationDoneRequest":true,"supportsFunctionBreakpoints":false,"supportsConditionalBreakpoints":false,"supportsEvaluateForHovers":false}}

{"type":"request","seq":2,"command":"evaluate","arguments":{"expression":"help","context":"repl"}}

Content-Length: 110
{"type":"response","seq":3,"command":"evaluate","request_seq":2,"success":false,"error":"not yet implemented"}

{"type":"request","seq":4,"command":"disconnect","arguments":{"restart":false}}

Content-Length: 81
{"type":"response","seq":5,"command":"disconnect","request_seq":4,"success":true}

Thanks!

@weinand

This comment has been minimized.

Show comment
Hide comment
@weinand

weinand Apr 5, 2016

Member

@dibyendumajumdar your protocol trace looks good so far but I wonder what did you do in VS Code to get this interaction? Did you type "help" in the debug console?

A good indication that VS Code is happy, would be that VS Code keeps a debug session running (you see the 'step' and 'terminate' buttons). In your trace VS Code seems to shut you down early with the "disconnect" request.

I would print all requests that VS Code is sending to your debug adapter. Then you can easily see what VS Code calls and what you have to implement. I would expect that the first required requests are the "launch" and the "threads" requests.

The low level protocol is identical to the node v8 debugger protocol. Here are more details: https://github.com/buggerjs/bugger-v8-client/blob/master/PROTOCOL.md
Please note: only the first sections of the document are relevant for the VS Code debug protocol. Please ignore everything in that document starting with https://github.com/buggerjs/bugger-v8-client/blob/master/PROTOCOL.md#example-what-is-refs

Member

weinand commented Apr 5, 2016

@dibyendumajumdar your protocol trace looks good so far but I wonder what did you do in VS Code to get this interaction? Did you type "help" in the debug console?

A good indication that VS Code is happy, would be that VS Code keeps a debug session running (you see the 'step' and 'terminate' buttons). In your trace VS Code seems to shut you down early with the "disconnect" request.

I would print all requests that VS Code is sending to your debug adapter. Then you can easily see what VS Code calls and what you have to implement. I would expect that the first required requests are the "launch" and the "threads" requests.

The low level protocol is identical to the node v8 debugger protocol. Here are more details: https://github.com/buggerjs/bugger-v8-client/blob/master/PROTOCOL.md
Please note: only the first sections of the document are relevant for the VS Code debug protocol. Please ignore everything in that document starting with https://github.com/buggerjs/bugger-v8-client/blob/master/PROTOCOL.md#example-what-is-refs

@dibyendumajumdar

This comment has been minimized.

Show comment
Hide comment
@dibyendumajumdar

dibyendumajumdar Apr 5, 2016

Thanks for getting back to me. I did type help in console to see what would be passed to the debug server. I am not seeing anything like the terminate button at all, and yet the debugger is running. I am not seeing a launch request or a thread request ... The disconnect happens when I shutdown vscode.

I think you guys have really got a great thing going here but to be honest the docs are very poor, so any help you can give me is very much appreciated!

dibyendumajumdar commented Apr 5, 2016

Thanks for getting back to me. I did type help in console to see what would be passed to the debug server. I am not seeing anything like the terminate button at all, and yet the debugger is running. I am not seeing a launch request or a thread request ... The disconnect happens when I shutdown vscode.

I think you guys have really got a great thing going here but to be honest the docs are very poor, so any help you can give me is very much appreciated!

@weinand

This comment has been minimized.

Show comment
Hide comment
@weinand

weinand Apr 5, 2016

Member

@dibyendumajumdar the best way to write a debug adapter is by using mock-debug as an example. You can run mock-debug in server mode in the node debugger and step through in order to understand the interaction with VS Code.

Member

weinand commented Apr 5, 2016

@dibyendumajumdar the best way to write a debug adapter is by using mock-debug as an example. You can run mock-debug in server mode in the node debugger and step through in order to understand the interaction with VS Code.

@dibyendumajumdar

This comment has been minimized.

Show comment
Hide comment
@dibyendumajumdar

dibyendumajumdar Apr 5, 2016

I am looking at mock debug as well as mono debug to work out what I should be doing. But haven't stepped through mock debug, thanks for that suggestion.

Thanks also for the v8 docs. That's the kind of document I would expect VSCode to have, happy to help put something together if I can get my implementation working.

dibyendumajumdar commented Apr 5, 2016

I am looking at mock debug as well as mono debug to work out what I should be doing. But haven't stepped through mock debug, thanks for that suggestion.

Thanks also for the v8 docs. That's the kind of document I would expect VSCode to have, happy to help put something together if I can get my implementation working.

@dibyendumajumdar

This comment has been minimized.

Show comment
Hide comment
@dibyendumajumdar

dibyendumajumdar Apr 5, 2016

Hi - I found the issue, and it was something really stupid on my part. I forgot that in C, stdout is a text stream so the '\r' characters are lost in transit. So VSCode was not recognizing the responses. Since VSCode appears to silently discard input it doesn't recognize (?) it took me quite a while to figure out what was going wrong.

dibyendumajumdar commented Apr 5, 2016

Hi - I found the issue, and it was something really stupid on my part. I forgot that in C, stdout is a text stream so the '\r' characters are lost in transit. So VSCode was not recognizing the responses. Since VSCode appears to silently discard input it doesn't recognize (?) it took me quite a while to figure out what was going wrong.

@weinand

This comment has been minimized.

Show comment
Hide comment
@weinand

weinand Apr 5, 2016

Member

@dibyendumajumdar great to hear that you could make some progress.
In order to make debugging of your debug adapter easier, I suggest that you add server support too.
With that VS Code does not have to launch the adapter for each debug session, but you can just run the adapter as a server process in a C debugger, and VS Connect will connect to it for each session. In this case VS Code will not communicate with the adapter via stdin/stdout but through a socket connection (or named pipe) instead.

Member

weinand commented Apr 5, 2016

@dibyendumajumdar great to hear that you could make some progress.
In order to make debugging of your debug adapter easier, I suggest that you add server support too.
With that VS Code does not have to launch the adapter for each debug session, but you can just run the adapter as a server process in a C debugger, and VS Connect will connect to it for each session. In this case VS Code will not communicate with the adapter via stdin/stdout but through a socket connection (or named pipe) instead.

@dibyendumajumdar

This comment has been minimized.

Show comment
Hide comment
@dibyendumajumdar

dibyendumajumdar Apr 5, 2016

As I am coding this in C, stdin/stdout is really convenient! I will eventually do a socket based implementation.

dibyendumajumdar commented Apr 5, 2016

As I am coding this in C, stdin/stdout is really convenient! I will eventually do a socket based implementation.

@dibyendumajumdar

This comment has been minimized.

Show comment
Hide comment
@dibyendumajumdar

dibyendumajumdar Apr 25, 2016

@weinand I got some time to work on my debug adapter yesterday after a break. I have now got to the point where I receive 'variables' request and I respond with 'variables' response. But the client then fails with 'Unexpected Token' error - unfortunately I do not know how to see what the client is unhappy about. Could you point me to the code in VSCode that handles interactions with the debug server so that I can check?

I also found that while VSCode supplies program with back slashes in the path when sending launch request - I need to convert to front slashes when replying back as the front end doesn't like back slashes in the path.

dibyendumajumdar commented Apr 25, 2016

@weinand I got some time to work on my debug adapter yesterday after a break. I have now got to the point where I receive 'variables' request and I respond with 'variables' response. But the client then fails with 'Unexpected Token' error - unfortunately I do not know how to see what the client is unhappy about. Could you point me to the code in VSCode that handles interactions with the debug server so that I can check?

I also found that while VSCode supplies program with back slashes in the path when sending launch request - I need to convert to front slashes when replying back as the front end doesn't like back slashes in the path.

@weinand

This comment has been minimized.

Show comment
Hide comment
@weinand

weinand Apr 25, 2016

Member

@isidorn could you please help @dibyendumajumdar with these two issues since they are in your area anyway.

Member

weinand commented Apr 25, 2016

@isidorn could you please help @dibyendumajumdar with these two issues since they are in your area anyway.

@isidorn

This comment has been minimized.

Show comment
Hide comment
@isidorn

isidorn Apr 25, 2016

@dibyendumajumdar the VSCode client uses the rawDebugSession.ts to interact with the client, e.g the variables request can be found here.

Yes, it seems like we are not supporting when back slashes are sent from adapter to vscode. I believe we should support both backwards and forwards slashes since in the initialize request vscode sends 'path'. @weinand do you agree?
@dibyendumajumdar please file an issue in the https://github.com/microsoft/vscode repo for the back slash suport

isidorn commented Apr 25, 2016

@dibyendumajumdar the VSCode client uses the rawDebugSession.ts to interact with the client, e.g the variables request can be found here.

Yes, it seems like we are not supporting when back slashes are sent from adapter to vscode. I believe we should support both backwards and forwards slashes since in the initialize request vscode sends 'path'. @weinand do you agree?
@dibyendumajumdar please file an issue in the https://github.com/microsoft/vscode repo for the back slash suport

@dibyendumajumdar

This comment has been minimized.

Show comment
Hide comment
@dibyendumajumdar

dibyendumajumdar commented Apr 25, 2016

@isidorn Have raised issue as requested Microsoft/vscode#5778

@weinand

This comment has been minimized.

Show comment
Hide comment
@weinand

weinand Apr 25, 2016

Member

@dibyendumajumdar the 'Unexpected Token' error sounds like a json parsing error in VS Code. The parsing happens here.

Make sure that you do not send tracing/diagnostic output to stdout accidentally since this will result in parsing errors. Always use stderr for this.

Member

weinand commented Apr 25, 2016

@dibyendumajumdar the 'Unexpected Token' error sounds like a json parsing error in VS Code. The parsing happens here.

Make sure that you do not send tracing/diagnostic output to stdout accidentally since this will result in parsing errors. Always use stderr for this.

@dibyendumajumdar

This comment has been minimized.

Show comment
Hide comment
@dibyendumajumdar

dibyendumajumdar Apr 25, 2016

@weinand thanks - I am checking that I am not sending anything unwanted to stdout. The variables response I am creating looks fine to me (in fact the scopes and variables appear momentarily on screen before the debug session errors out).

Perhaps when JSON.parse(body) fails, the body should be included in the error so that one can see what the offending bit of input was.

dibyendumajumdar commented Apr 25, 2016

@weinand thanks - I am checking that I am not sending anything unwanted to stdout. The variables response I am creating looks fine to me (in fact the scopes and variables appear momentarily on screen before the debug session errors out).

Perhaps when JSON.parse(body) fails, the body should be included in the error so that one can see what the offending bit of input was.

@dibyendumajumdar

This comment has been minimized.

Show comment
Hide comment
@dibyendumajumdar

dibyendumajumdar Apr 26, 2016

@weinand I was able to sort out the issue using VSCode built from source (I changed the exception to include the body) - plus in the source version I see that VSCode churns out log messages in the background which also helped.

Thanks for the help

dibyendumajumdar commented Apr 26, 2016

@weinand I was able to sort out the issue using VSCode built from source (I changed the exception to include the body) - plus in the source version I see that VSCode churns out log messages in the background which also helped.

Thanks for the help

@dibyendumajumdar

This comment has been minimized.

Show comment
Hide comment
@dibyendumajumdar

dibyendumajumdar Apr 29, 2016

Hi, I have made some progress, and wanted to share. Thanks again for a great product!

https://github.com/dibyendumajumdar/ravi/tree/master/vscode-debugger

dibyendumajumdar commented Apr 29, 2016

Hi, I have made some progress, and wanted to share. Thanks again for a great product!

https://github.com/dibyendumajumdar/ravi/tree/master/vscode-debugger

@isidorn

This comment has been minimized.

Show comment
Hide comment
@isidorn

isidorn Apr 29, 2016

@dibyendumajumdar awesome! I'll share it with the team.

isidorn commented Apr 29, 2016

@dibyendumajumdar awesome! I'll share it with the team.

@weinand weinand closed this Sep 11, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment