Align the documentation of how to do debugging with official docs, help beginners to get started with debugging

[bjornregnell]

I'm trying to help my beginner programming students to grok how to use the debugger in vs code and one problem is that this page https://code.visualstudio.com/docs/editor/debugging does not mention Scala and this page https://scalameta.org/metals/docs/editors/vscode/#running-and-debugging-your-code does not really show how to do debugging in vs code and it is not really aligned with the official doc on the debugger and how to set it up.

Expected behavior

Align the info and make it easier for a beginner programmer to get started with debugging with Metals. Would it even be possible for the official MS doc on vs code to point also to the Scala extension and for the Metals VS code page to align or link to the setup as in the official guide to reduce confusion?

[bjornregnell]

Example of misalignemnt: On the official docs it says to press the "Launch program" button but in Scala Metals it is "Run and Debug" but then it starts the "run config"-dance that is much more difficult to a beginner than just pressing "run | debug" above your @main. But that does not appear if you don't have a build.sbt, which is not obvious from the official debugging docs of vs code.

[bjornregnell]

If you follow the offical docs you risk ending up with

[tgodzik]

Thanks @bjornregnell ! We should for sure update the docs to be more beginner friendly. I will take a look next week at that.

[bjornregnell]

I guess Metals need to automatically create a valid launch config in order for the official docs to work. If we cannot impact the official docs then we need to adapt so they work. Searching internet for "vs code debug" will land most beginners on the official docs...

[tgodzik]

Related https://github.com/scalameta/metals-vscode/pull/767 <- however I don't think it will cause Metals to pop up on the main page, but should be more discoverable.

[bjornregnell]

How about providing a launch config out-of-the-box so the standard "Launch Program" button "just works"? Is this related to the label? Or what does it take to provide such a config to avoid the 'JSON with Comments' popup...

[tgodzik]

How about providing a launch config out-of-the-box so the standard "Launch Program" button "just works"? Is this related to the label? Or what does it take to provide such a config to avoid the 'JSON with Comments' popup...

I am thinking we could try and run the existing command that will try to discover a main method in the current file instead of creating the config with the pop ups, which I never really found too useful.

We could also link to the official docs from the Metals page as it's much more complete when it comes to the debugging explanations, what do you think?

[bjornregnell]

Well, as long as the button that is given if you just click the Bug-tab on the left and the launch button just works then its fine (I thought that there perhaps had to exist a JSON launch config in order for the button to work, but if it's not needed then its fine)

[tgodzik]

Well, as long as the button that is given if you just click the Bug-tab on the left and the launch button just works then its fine (I thought that there perhaps had to exist a JSON launch config in order for the button to work, but if it's not needed then its fine)

I think it should be possible to not need it, but I ahven't managed yet to figure it out https://github.com/microsoft/vscode/issues/54212

[tgodzik]

Ok, so I did some research and I think currently the best approach would be to prefill the launch.json configuration for the user instead of making the users fill everything by themselves. This will require some discover endpoint on the Metals side, but it can be done on top of https://github.com/scalameta/metals/pull/3277

We can also use the dynamic configuration, which shows up when users run Select and start debugging command, which will not create the launch.json config, but users will still be able to choose it in the Run and debug tab.

I am also thinking of adding another dynamic configuration option for running things in the current file, which could be resolved dynamically based on the current open file. It would be cool to have that instead available as the default F5 behaviour, but I think that's not possible and the best thing we can do is prefill the json (will need to confirm that still.)

[bjornregnell]

That sounds promising! :heart_decoration:

[tgodzik]

This should now work properly when just clicking run in any file. Do let us know @bjornregnell if there is anything else you feel we can improve (aside from obvious Metals stability)

[bjornregnell]

Works like a charm! :heart: