Explore improving the single file debug experience

[weinand]

Today VS Code debugging has no generic way to know whether a debug extension implements "single file debugging". Without this knowledge it is not possible to provide a standardised UX experience for this case.

Because of this some debug extension have started to create their own UI. A good example is the Python extension which shows a play button in the editor:

[weinand]

How "single-file debugging" works today:

• precondition:
  • no launch.json exists in workspace
  • program is open in current editor
• based on language type of current editor all debug extensions are searched that are configured for that language (languages property in the debuggers contribution).
• if more than one is found, a Quickpick is used to let user pick one debug extension
• the extension is activated
• if the extension implements resolveDebugConfiguration, it is called with an empty in-memory launch config
• If the debug extension supports "single-file debugging without launch.json", it understands the empty in-memory launch config and "upgrades" it, so that it starts debugging on the file that is open in the editor.
• if no extension can be found or if an extension doesn't support the "single-file debugging without launch.json" nothing happens.

@isidorn is that a faithful description of the current behavior?

[isidorn]

@weinand yes this is faithful description of the current flow.
Just a nitpick: if no extension can be found we do not open launch.json. We will only open launch.json if an extension explicitly tells us to do that by returning null.

[weinand]

What are the problems/paint points that we try to address?

A first pair of problems is related to the fact that VS Code behaves differently if the workspace has a "launch.json" or not:

• Assuming that no "launch.json" exists in the workspace, VS Code does not know (upfront) whether a project (workspace) is debuggable, e.g. whether pressing a play button would successfully start a debug session. Corollary: VS Code does not know the reason why a project (workspace) is not in a debuggable state either. These problems makes it difficult to offer a robust "Run" button in the Welcome view. If the debug extension does not support "single-file debugging without launch.json", pressing "Run" does nothing (and we do not really know why and cannot help the user).
• If a launch.json exists, VS Code assumes that the user uses it exclusively (by selecting a launch config and executing it) and no smartness is employed. Even if a debug extension implements the "single-file debugging without launch.json" scenario, it is no longer available in the UI. That's the reason why the Python debug extension adds a "Play" button to the editor: with this button a user can quickly and easily override a currently selected launch config and start debugging on the file open in the editor.

Another problem comes from the fact that VS Code does not want to activate debug extensions eagerly. As a consequence VS Code can only rely on the declarative information available in the package.json but not on running extension code.

Today VS Code only knows the supported languages of a debugger. This information is used in the "single-file debugging without launch.json" scenario for activating a debug extension based on the language open in the current editor. But this mechanism does not work if a file with an unsupported language is open in the editor or if there is no file open at all. Running extension code could easily figure out that the project (workspace) is runnable/debuggable. E.g. it could determine the entry-point of the project by analysing the package.json. (Actually this code exists already in many debug extensions but it cannot be used without activating the debug extension).

"Run without debugging":
DAP defines protocol for "Run without debugging" and VS Code implements it, but not all debug extensions are implementing it.
Since there is no way to figure out whether a debug extension implements the "Run without debugging", VS Code always provides UI for "Run without debugging" even if the debugger doesn't support it. Typically this is not a big problem because a debug extension will fall back to "Debug" if "Run without debugging" is not implemented.

---

Some proposals (in no specific order):

• Introduce explicit extension API (e.g. provideWorkspaceDebugConfiguration) to have the debug extension communicate back to VS Code the following information:

  • whether debug extension supports a "Run/Debug" in the current situation (without relying on launch.json or relying on an active file in the editor)
  • if the debug extension cannot figure out what to run/debug, it should report back a message explaining why run/debug doesn't work and what to do.

  VS Code would use this API for the Welcome view and "F5" (if no launch.json exists and there is no active file). E.g. in the a Node.js this API could find the program's entry point in the package.json. Today the resolveDebugConfiguration is able to launch the program in that case but we are not able to show a Play button if the user has the package.json open in the editor.
  If "run/debug" is not possible the welcome view could show how to fix this.

• Introduce explicit API for running/debugging a file (or resource?), e.g. provideFileDebugConfiguration or provideResourceDebugConfiguration. VS Code would use this API for supporting a "Play" button in the editor.

• Introduce new API for determining whether the DA supports the "noDebug" mode (surfaced as "Run without debugging"). I'm not sure whether it is sufficient to add this to the DAP or whether this must be extension API or just a new attribute on the "debuggers" contribution (dependent on the location of the API the info would be available statically, dynamically on extension activation, or dynamically on debug session start).

• the problems resulting from the fact that VS Code tries to avoid activating debug extensions eagerly are more difficult to solve. Possible approaches:

  • activate at least one debug extension eagerly based on historic information from previous debug sessions. We have this information already as a "when" context.
  • try to match an active language extension automatically with the corresponding debugger extension. This is based on the assumption, that a beginning user starting a Python project most likely needs a Python debugger.

How to design the APIs?
Today some of the debug extension APIs revolve around "debug configurations" (provideDebugConfigurations, resolveDebugConfiguration, startDebugging).
To continue this "style", I propose that new APIs follow suit:
instead of introducing a new API for "start debugging a workspace/project" or "start debugging a file", we could introduce a new function provideDebugConfiguration(options) that based on the passed ´options´ returns a debug configuration (or an descriptive error if debugging isn't possible). The debug configuration can be passed to startDebugging to actually launch a debug session. Since provideDebugConfiguration(options) does not start the debug session itself, it can be used for probing whether debugging is possible.

[isidorn]

Good analysis of our current limitations. I can brainstorm on potential ideas on how to solve some of these, but you might be already writing this, so let me know once you are looking for feedback. Thanks!

[weinand]

@isidorn I'm done with my proposals. Please review and provide feedback. Thanks.

[weinand]

Discussion will be continued in April.

[isidorn]

Good writeup. Some feedback:

Play button

In order to know if VS Code should put a Play button in the editor title VS Code should ask all activated debug extensions if they support a Play button for that file. If any of them do, the Play action should be there. The extensino can not decide this based on VS Code api, but VS Code debug UX would have to pass the file / uri for who it is asking. Because there can be inactive editors opened side by side.
This could be done by your proposel of provideDebugConfiguration. VS Code would simply call this for any visible editor for all adapters, and if there is 'candidate' we would show the play button.

Extension activation

I do not see the issues of extensions not being activated. If the extension is not activated then 99% it can not handle the open file, since it would already activated on that file type.
To make this discussions more scoped and tue to the previous reason I suggest to handle the issue of extension activation seperatly.
If you think we should solve this with this issue what would be the example scenario where the extension is not activated? The only scenario I see is I just opened a workspace and I did not open a file, I just want to press F5 to run. However that seems unrelated to the single file discussion.

Run without debugging

This sounds best fitted for a static contribution point via package.json imho. However if a debug extension says no to this how would that change the VS Code debug ux experience. Just some actions would be disabled?

fyi @connor4312 @roblourens