Skip to content

Explore improving the single file debug experience #92269

Closed

Description

@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:

2020-03-20_10-00-43

Activity

  1. added
    feature-requestRequest for new features or functionality
    debugDebug viewlet, configurations, breakpoints, adapter issues
    on Mar 9, 2020
  2. weinand commented on Mar 20, 2020

    @weinand
    ContributorAuthor

    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.

    Isidor Nikolic (@isidorn) is that a faithful description of the current behavior?

  3. isidorn commented on Mar 20, 2020

    @isidorn

    Andre Weinand (@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.

  4. changed the title [-]Explore improving the debug experience when a single file is open without a launch config[/-] [+]Explore improving the single file debug experience[/+] on Mar 24, 2020
  5. weinand commented on Mar 25, 2020

    @weinand
    ContributorAuthor

    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.

  6. isidorn commented on Mar 25, 2020

    @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!

  7. weinand commented on Mar 25, 2020

    @weinand
    ContributorAuthor

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

  8. weinand commented on Mar 26, 2020

    @weinand
    ContributorAuthor

    Discussion will be continued in April.

  9. isidorn commented on Mar 26, 2020

    @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 Connor Peet (@connor4312) roblourens

  10. weinand commented on Mar 30, 2020

    @weinand
    ContributorAuthor

    Isidor Nikolic (@isidorn) thanks for the feedback.

    Play Button:
    "should ask all activated debug extensions": yes, but the "activated" is already a problem: if a user has created a new Python file, the debugger is not activated and no Play button will be shown. This can be solved by either adding some static contribution point attribute ("supportsFileDebug") or by activating the debug extension together with the language extension and using the proposed provideFileDebugConfiguration.

    Extension Activation:
    "what would be the example scenario where the extension is not activated": see above.
    You said: "If the extension is not activated then 99% it can not handle the open file, since it would already activated on that file type." With "extension" you mean language extension, right? But language extension and debugger extension do not yet have a dependency. So activating the language extension does not activate the debugger extension.

    Run without Debugging:
    Yes, with a contribution point attribute we could more precisely show/hide the actions: e.g. no "Run without Debugging" if the extension does not support it. If the contribution point attribute
    is missing we would fall back to the current imprecise behavior.

  11. 39 remaining items

  12. isidorn commented on Jun 25, 2020

    @isidorn

    I have introduced the run group to the Editor Title area as we agreed upon, the run group is left of the navigation group.
    I have also adopted this in Mock Debug via this commit. I have used the order 10 and 20 to give the group more flexibility if other extensions want to introduce actions between these.

    I will update the docs here https://code.visualstudio.com/api/references/contribution-points#Sorting-of-groups
    The open question is should the group be called 0_run which is a bit ugly. Will check with Ben.

    I have created this follow up item for @misolori #101026

    Andre Weinand (@weinand) and me can work on finalising on what is the exact recommnedation for extensions and post it here and in the release notes.

  13. isidorn commented on Jun 26, 2020

    @isidorn

    After discussion we decided to go with the group name 1_run to be better aligned with the current group names.
    I have updated our docs to reflect the new group name.


    To recap Andre Weinand (@weinand) and me came up with the following recommendations for debug extensions (we will also cover this in our release notes):

    1. Use the $(play) icon for Run, $(debug-alt-small) for debug
    2. Put actions in the 1_run group, use order 10 and 20.
    3. Use title "Run File" and "Debug File" or "Run Python File" and "Debug Python File"
    4. Put either one or two actions based on your use case
    5. Try to not to put other debug actions, if those are needed please let us know so we think about having a consistent experience

    Mock debug example can be found here


    fyi Connor Peet (@connor4312) since we could also do this in js-debug

    To verify: clone the mock debug repo from here, run the extension and make sure the commands are properly contributed for every markdown file in the editor title area.

  14. weinand commented on Jul 1, 2020

    @weinand
    ContributorAuthor

    Verified that the proposal works and looks fine.
    The icons are not yet aligned, but I commented here: #101026 (comment)

  15. akaroml commented on Jul 6, 2020

    @akaroml
    Member

    After discussion we decided to go with the group name 1_run to be better aligned with the current group names.
    I have updated our docs to reflect the new group name.

    To recap Andre Weinand (@weinand) and me came up with the following recommendations for debug extensions (we will also cover this in our release notes):

    1. Use the $(play) icon for Run, $(debug-alt-small) for debug
    2. Put actions in the 1_run group, use order 10 and 20.
    3. Use title "Run File" and "Debug File" or "Run Python File" and "Debug Python File"
    4. Put either one or two actions based on your use case
    5. Try to not to put other debug actions, if those are needed please let us know so we think about having a consistent experience

    Mock debug example can be found here

    fyi Connor Peet (@connor4312) since we could also do this in js-debug

    To verify: clone the mock debug repo from here, run the extension and make sure the commands are properly contributed for every markdown file in the editor title area.

    Jinbo Wang (@testforstephen) please take a look at the recommendations and see how Java debugger can benefit.

  16. testforstephen commented on Jul 6, 2020

    @testforstephen
  17. DanTup commented on Jul 28, 2020

    @DanTup
    Contributor

    Isidor Nikolic (@isidorn)

    As for the $(play) and $(debug-alt) we simply need to resize them so they are the same size and aligned. Looking at them the problem is the debug-alt which is not designed to be used in a horisontal action bar. We should resize it, and if that is not possible (activity bar might get broken) then we simply need to introduce a new codicon. @misolori is it possible that you look into this?

    Is this being tracked anywhere? It definitely looks a bit weird right now with different sizes.

  18. isidorn commented on Jul 28, 2020

    @isidorn
  19. DanTup commented on Jul 28, 2020

    @DanTup
    Contributor

    Isidor Nikolic (@isidorn) aha, perfect - already shipped! :) I copied the original name (from #92269 (comment)) so if that's the main source for this info, might be worth editing in there (I did check the release notes, but it didn't seem to include the specifics).

    Thanks!

  20. isidorn commented on Jul 28, 2020

    @isidorn

    Makes sense, I have updated my comments from above. Thanks for pointing this out.

  21. locked and limited conversation to collaborators on Aug 11, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

debugDebug viewlet, configurations, breakpoints, adapter issuesfeature-requestRequest for new features or functionalityverification-neededVerification of issue is requestedverifiedVerification succeeded

Type

No type

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions

    ⌂ 换网址