Support for executing debugger commands upon hitting a breakpoint

[ivanhernandez13]

The DAP currently has support for three types of additions to breakpoints including conditions, hit count, and log messages.

interface SourceBreakpoint {
  line: number;
  column?: number;
  condition?: string;
  hitCondition?: string;
  logMessage?: string;
}

It would be nice if a user could attach commands to be automatically executed when a breakpoint is hit. This would be useful for some debuggers that have an extensive list of debugger commands that are more powerful than simply evaluating an expression such as GDB or LLDB.

The addition to SourceBreakpoint could be:

 /**
   * An optional list of commands that the backend will execute and log the output
   * (if any).
   */
  commands?: string[];

I know of at least 2 IDEs (IntelliJ and Xcode) that have support for executing any arbitrary debugger command(s) when a breakpoint is hit.

[weinand]

As long as the DAP spec doesn't contain a definition for "debugger command", it is not really helpful to have a commands attribute on a SourceBreakpoint.

How should VS Code (for example) implement this?

IMO the "commands" attribute for now is just a private addition within the context of a specific client (= IDE): the IDE provides UI to add commands to a source breakpoint and it knows how to interpret the commands for execution.

If we find agreement about those "commands" across many clients, we can consider to promote the private DAP addition to become official.

[ivanhernandez13]

@weinand sorry for the delayed response.

On second thought, the proposed addition should be command: string; to match the existing condition, hitCondition, and logMessage capabilities. If multiple commands are needed then it would require multiple breakpoints.

With that in mind, This feature would work in the same way log points work now. Right clicking the gutter would give the user the option to add Add Debugger Command... and accept a string. When the breakpoint is hit, the debugger would interpret the command however it sees fit and send back any output in the response packet.

How should VS Code (for example) implement this?

The clients (IDEs) would not be involved except for of course providing a UI of some sort to set a breakpoint with a debugger command and also displaying the output returned by the debugger. If a client can support a log point then it would also be able to support a "debugger command". The backing debugger that implements the DAP would handle how to parse and execute the given values.

A "debugger command" being any arbitrary command which could include (but not limited to) the common commands such as "Step Over", "Continue", evaluate variable or expression, etc. It is up to the backing debugger to enable this capability since some debuggers may not have debugger commands beyond the common commands which are accessible through the GUI.

One contrived example of a use case with this feature could be the image list LLDB command which prints the current loaded executable and all dependent shared library images. A user might be interested in knowing what libraries their executable is pulling in and could set a breakpoint at an entry point in their program to execute this command at the start of every debug session.

[ivanhernandez13]

Hey @weinand any comment/update on this or anything else I can provide or do?

[puremourning]

and also displaying the output returned by the debugger.

How/where would this output be communicated ?

A user might be interested in knowing what libraries their executable is pulling in and could set a breakpoint at an entry point in their program to execute this command at the start of every debug session.

Many adapters do this using launch configuration, e.g. customSetupCommands and such, particularly LLDB and/or gdb-based ones that I've seen.

I sort of agree with @weinand here - the client could implement this without any server support in the same way that we can implement "run to cursor" - client-side support for additional breakpoint properties that then get executed via the evaluate request when receiving an equivalent 'stopped' event. This is actually more consistent for the user because it won't vary based on the debug adapter capabilities.

FWIW Personally, I've never seen or used this sort of "run command on breakpoint" feature in any debugger, and probably wouldn't implement support for it in vimspector whether custom or server-supported. Seems quite niche to me :)

[ivanhernandez13]

How/where would this output be communicated ?

The debug console I would imagine, similar to a log point. Difference being that a debugger command is not scoped to the frame at which the breakpoint is set or even to the process being debugged, it can be any arbitrary command.

Many adapters do this using launch configuration, e.g. customSetupCommands and such, particularly LLDB and/or gdb-based ones that I've seen.

It's true that launch configuration would be sufficient for the example I provided. The launch configuration approach is limited however to executing commands at certain predefined points and they need to be set before the start of the debug session. Commands on breakpoints could be set at any time and be set to trigger at any point during the process execution.

FWIW Personally, I've never seen or used this sort of "run command on breakpoint" feature in any debugger, and probably wouldn't implement support for it in vimspector whether custom or server-supported. Seems quite niche to me :)

That's fair, I cannot speak to how popular such a feature is aside from it being supported in both LLDB and gdb. Coming from Xcode this was a noticeable omission for me and this FR was filed to be able to provide feature parity with a debug adapter i'm working on to Xcode's debugging experience.

[mgupta0421]

@weinand
Hi, A very curious doubt how the debug adapter knows about the client capabilities(like, it supports breakpoint, variable capabilities) as in 'InitializeRequestArguments', it is nowhere we set them when we send the 'initialize' request to the Debug Adapter

[weinand]

@mgupta0421 the client can only set capabilities for optional client features. Since most features are mandatory, there are no client capabilities for them.

[mgupta0421]

@weinand the point says that all the features like,(setbreakpoints, stepin, variables, etc) are mandatory for almost every client. Is there any feature that is optional for the client and are set in the InitializeRequestArguments?

[weinand]

@mgupta0421 yes, all InitializeRequestArguments-properties starting with "supports..." are for optional client features.

[mgupta0421]

@weinand Thank you, that solves my doubt.

[mgupta0421]

@weinand, I am looking for the code of file nodeDebug 'https://github.com/microsoft/vscode-node-debug/blob/a46d77a7b4262ef09986c8cc885190b7568a5dea/src/node/nodeDebug.ts', this adapter does not support the below capability as stated false value.
'response.body.supportsEvaluateForHovers = false;'
but when I am trying to debug my node application with this adapter in VS code its shows me the variable value while hovering! This makes me in confusion.

[weinand]

@mgupta0421 excellent observation!

• if supportsEvaluateForHovers is false, VS Code uses the following fallback strategy: it tries to find the variable name under the mouse in the VARIABLEs view. If found, the value is taken from there. This approach does not involve any additional communication with the debug adapter because the variables and their values have already been fetched for population the VARIABLEs view.
• the extension vscode-node-debug is legacy and only used to debug node.js versions < 8.0. For all other versions vscode-js-debug is used.

[mgupta0421]

@weinand Superb!
is it not the support for the feature 'supportsEvaluateForHovers' is redundant because anyhow it evaluates the variable when the value of 'supportsEvaluateForHovers' is false also.