Proposal: Support Stepping Granularities

[auott]

Stepping Granularities

---

A stepping granularity allows specifying how far a specific step (Next, StepIn, StepOut, StepBack) should go.
An adapter can take this as a suggestion and does not need to support them as distinct granularities.
For example, some adapters may consider statement and line equivalent.

export interface Capabilities {
    // ...

    /** The debug adapter supports stepping granularities */
    supportsSteppingGranularity?: boolean;
}

type SteppingGranularity = 'statement' | 'line' | 'instruction';

export interface NextArguments {
    // ...

    /** Optional granularity to step. If no granularity is specified, a granularity of 'statement' is assumed. */
    granularity?: SteppingGranularity;
}

export interface StepInArguments {
    // ...

    /** Optional granularity to step If no granularity is specified, a granularity of 'statement' is assumed. */
    granularity?: SteppingGranularity;
}

export interface StepOutArguments {
    // ...

    /** Optional granularity to step If no granularity is specified, a granularity of 'statement' is assumed. */
    granularity?: SteppingGranularity;
}

export interface StepBackArguments {
    // ...

    /** Optional granularity to step If no granularity is specified, a granularity of 'statement' is assumed. */
    granularity?: SteppingGranularity;
}

CC: @andrewcrawley, @weinand

[weinand]

Some questions/comments:

• is the type StepGranularity exhaustive or could there be more?
• if a DA supports "Stepping Granularities", does it support the three granularities in addition to the existing unspecified (resulting in a total of four), or are there only three in total?
• I think I understand what "Stepping Granularities" mean for "Next" and "StepBack". But do they really make sense for "StepIn" and "StepOut"?
• naming inconsistency between "stepping" and step": supportsSteppingGranularity vs StepGranularity. I prefer "stepping".

[auott]

• is the type StepGranularity exhaustive or could there be more?

These three have historically been sufficient for our usage, however I don't see why a different DA couldn't have other granularities.

• if a DA supports "Stepping Granularities", does it support the three granularities in addition to the existing unspecified (resulting in a total of four), or are there only three in total?

In my mind there are only three granularities, but a DA that supports stepping granularities would still support steps that don't specify a granularity. For requests that are made without specifying a granularity the DA would have an implicit granularity that doesn't need to be communicated with the client.

• I think I understand what "Stepping Granularities" mean for "Next" and "StepBack". But do they really make sense for "StepIn" and "StepOut"?

StepIn and StepOut can have meaningful differences - most notably with Instruction granularity.
For C++ StepIn-Instruction on a "call" instruction would execute one instruction and would take you to the direct next instruction. Statement or Line would take you past the prolog of the function being called.
Similarly, StepOut-Instruction would go just to the instruction after the return, where Line/Statement would go past any cleanup associated with the line (i.e. destructors for temporaries, or extracting return values).

• naming inconsistency between "stepping" and step": supportsSteppingGranularity vs StepGranularity. I prefer "stepping".

Updated!

[chuckries]

I think it's worth noting that these are essentially "hints". If they are not provided, an adapter would do exactly what it does today when it receives a step. If they are provided, the adapter can be smarter about how "far" to step.

[weinand]

@auott thanks for your comments:

if we agree that there are three granularities, and the implicit (not specified) granularity is one of the three, then we should make the implicit granularity explicit, e.g. by saying something like "if no granularity is specified, a SteppingGranularity of 'line' is assumed. In this case we should make the value 'line' the first of the three. If we think that 'line' is not always the default, then I suggest that we introduce another granularity 'natural' or 'default' as the default (and make it the first for the four).

[gregg-miskelly]

The C# debugger uses 'statement' as the default today. That is also the default option value in Visual Studio. So if we want the first option to be the default, I think the proposal is already correct.

[auott]

Updated to explicitly indicate that statement is the default granularity.

[weinand]

@auott since you are using the proposed feature already I assume that you have an updated JSON schema for it. Could you please submit a PR for that?