From 8718086f1dfc4c49f35bce36deb2bc95783e9423 Mon Sep 17 00:00:00 2001 From: Connor Peet Date: Thu, 27 Jul 2023 15:32:20 -0700 Subject: [PATCH 1/8] fix typo in BreakpointLocationsArguments Fixes #415 --- changelog.md | 3 +++ debugAdapterProtocol.json | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/changelog.md b/changelog.md index 94be169..24ffbc8 100644 --- a/changelog.md +++ b/changelog.md @@ -6,6 +6,9 @@ sectionid: changelog #### All notable changes to the specification will be documented in this file. +* 1.63.x + * Fix a typo in the description of `BreakpointLocationsArguments` + * 1.62.x * Clarify lifetime of `DataBreakpoint.dataId` diff --git a/debugAdapterProtocol.json b/debugAdapterProtocol.json index 6dd2085..0519009 100644 --- a/debugAdapterProtocol.json +++ b/debugAdapterProtocol.json @@ -1202,7 +1202,7 @@ "properties": { "source": { "$ref": "#/definitions/Source", - "description": "The source location of the breakpoints; either `source.path` or `source.reference` must be specified." + "description": "The source location of the breakpoints; either `source.path` or `source.sourceReference` must be specified." }, "line": { "type": "integer", From f5ca8592b1bf1bc88fc0427c4d95dd21214c0326 Mon Sep 17 00:00:00 2001 From: Connor Peet Date: Thu, 27 Jul 2023 15:35:07 -0700 Subject: [PATCH 2/8] fix missing line break in CancelRequest Fixes #413 --- changelog.md | 1 + debugAdapterProtocol.json | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/changelog.md b/changelog.md index 24ffbc8..cd0ab73 100644 --- a/changelog.md +++ b/changelog.md @@ -8,6 +8,7 @@ sectionid: changelog * 1.63.x * Fix a typo in the description of `BreakpointLocationsArguments` + * Fix missing line break in `CancelRequest` * 1.62.x * Clarify lifetime of `DataBreakpoint.dataId` diff --git a/debugAdapterProtocol.json b/debugAdapterProtocol.json index 0519009..3d09231 100644 --- a/debugAdapterProtocol.json +++ b/debugAdapterProtocol.json @@ -130,7 +130,7 @@ "CancelRequest": { "allOf": [ { "$ref": "#/definitions/Request" }, { "type": "object", - "description": "The `cancel` request is used by the client in two situations:\n- to indicate that it is no longer interested in the result produced by a specific request issued earlier\n- to cancel a progress sequence. Clients should only call this request if the corresponding capability `supportsCancelRequest` is true.\nThis request has a hint characteristic: a debug adapter can only be expected to make a 'best effort' in honoring this request but there are no guarantees.\nThe `cancel` request may return an error if it could not cancel an operation but a client should refrain from presenting this error to end users.\nThe request that got cancelled still needs to send a response back. This can either be a normal result (`success` attribute true) or an error response (`success` attribute false and the `message` set to `cancelled`).\nReturning partial results from a cancelled request is possible but please note that a client has no generic way for detecting that a response is partial or not.\nThe progress that got cancelled still needs to send a `progressEnd` event back.\n A client should not assume that progress just got cancelled after sending the `cancel` request.", + "description": "The `cancel` request is used by the client in two situations:\n- to indicate that it is no longer interested in the result produced by a specific request issued earlier\n- to cancel a progress sequence.\nClients should only call this request if the corresponding capability `supportsCancelRequest` is true.\nThis request has a hint characteristic: a debug adapter can only be expected to make a 'best effort' in honoring this request but there are no guarantees.\nThe `cancel` request may return an error if it could not cancel an operation but a client should refrain from presenting this error to end users.\nThe request that got cancelled still needs to send a response back. This can either be a normal result (`success` attribute true) or an error response (`success` attribute false and the `message` set to `cancelled`).\nReturning partial results from a cancelled request is possible but please note that a client has no generic way for detecting that a response is partial or not.\nThe progress that got cancelled still needs to send a `progressEnd` event back.\n A client should not assume that progress just got cancelled after sending the `cancel` request.", "properties": { "command": { "type": "string", From 586d7b688d09bb067c8955fa0c9bff73a95a03bd Mon Sep 17 00:00:00 2001 From: Connor Peet Date: Thu, 27 Jul 2023 15:39:04 -0700 Subject: [PATCH 3/8] clarify state of object IDs in the VariablePresentationHint Fixes #412 --- changelog.md | 1 + debugAdapterProtocol.json | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/changelog.md b/changelog.md index cd0ab73..5b55423 100644 --- a/changelog.md +++ b/changelog.md @@ -9,6 +9,7 @@ sectionid: changelog * 1.63.x * Fix a typo in the description of `BreakpointLocationsArguments` * Fix missing line break in `CancelRequest` + * Clarify state of "object ID"s in `VariablePresentationHint` * 1.62.x * Clarify lifetime of `DataBreakpoint.dataId` diff --git a/debugAdapterProtocol.json b/debugAdapterProtocol.json index 3d09231..448d71c 100644 --- a/debugAdapterProtocol.json +++ b/debugAdapterProtocol.json @@ -3626,8 +3626,8 @@ "Indicates that the object is a constant.", "Indicates that the object is read only.", "Indicates that the object is a raw string.", - "Indicates that the object can have an Object ID created for it.", - "Indicates that the object has an Object ID associated with it.", + "Indicates that the object can have an Object ID created for it. This is a vestigial attribute that is used by some clients; 'Object ID's are not specified in the protocol.", + "Indicates that the object has an Object ID associated with it. This is a vestigial attribute that is used by some clients; 'Object ID's are not specified in the protocol.", "Indicates that the evaluation had side effects.", "Indicates that the object has its value tracked by a data breakpoint." ] From d815c0980bf75b0a3603aba932e459e815ed3bf8 Mon Sep 17 00:00:00 2001 From: Connor Peet Date: Thu, 27 Jul 2023 16:30:41 -0700 Subject: [PATCH 4/8] clarify memoryReference in the variable type For #414 --- changelog.md | 1 + debugAdapterProtocol.json | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/changelog.md b/changelog.md index 5b55423..d306e0f 100644 --- a/changelog.md +++ b/changelog.md @@ -9,6 +9,7 @@ sectionid: changelog * 1.63.x * Fix a typo in the description of `BreakpointLocationsArguments` * Fix missing line break in `CancelRequest` + * Clarify `memoryReference` in `Variable` type * Clarify state of "object ID"s in `VariablePresentationHint` * 1.62.x diff --git a/debugAdapterProtocol.json b/debugAdapterProtocol.json index 448d71c..c430b62 100644 --- a/debugAdapterProtocol.json +++ b/debugAdapterProtocol.json @@ -2545,7 +2545,7 @@ }, "memoryReference": { "type": "string", - "description": "A memory reference to a location appropriate for this result.\nFor pointer type eval results, this is generally a reference to the memory address contained in the pointer.\nThis attribute should be returned by a debug adapter if corresponding capability `supportsMemoryReferences` is true." + "description": "A memory reference to a location appropriate for this result.\nFor pointer type eval results, this is generally a reference to the memory address contained in the pointer.\nThis attribute may be returned by a debug adapter if corresponding capability `supportsMemoryReferences` is true." } }, "required": [ "result", "variablesReference" ] @@ -3587,7 +3587,7 @@ }, "memoryReference": { "type": "string", - "description": "The memory reference for the variable if the variable represents executable code, such as a function pointer.\nThis attribute is only required if the corresponding capability `supportsMemoryReferences` is true." + "description": "A memory reference associated with this variable.\nFor pointer type variables, this is generally a reference to the memory address contained in the pointer.\nFor executable data, this reference may later be used in a `disassemble` request.\nThis attribute may be returned by a debug adapter if corresponding capability `supportsMemoryReferences` is true." } }, "required": [ "name", "value", "variablesReference" ] From 8d850ac07fc7d81ed08f6ce902022c8ad69bfa6f Mon Sep 17 00:00:00 2001 From: Connor Peet Date: Sun, 30 Jul 2023 08:44:24 -0700 Subject: [PATCH 5/8] Add missing changelog entry Fixes #418 --- changelog.md | 1 + 1 file changed, 1 insertion(+) diff --git a/changelog.md b/changelog.md index 94be169..4bc3794 100644 --- a/changelog.md +++ b/changelog.md @@ -19,6 +19,7 @@ sectionid: changelog * 1.59.x: * Add an optional `frameId` to the `DataBreakpointInfoRequest` + * Add `notStopped` as a well-known reason in `Response` * Clarify the lifetime of `variablesReference`. * Clarify the default behavior when `kind` is omitted from the `RunInTerminalRequest`. * Clarify end of file behavior for `readMemory`. From 4ff72bd46040af5c116d99d03f1d36d03d742ad5 Mon Sep 17 00:00:00 2001 From: Connor Peet Date: Mon, 31 Jul 2023 10:12:20 -0700 Subject: [PATCH 6/8] add `memoryReference` support to the `SetVariable/ExpressionResponse` (#417) Fixes #414 --- changelog.md | 1 + debugAdapterProtocol.json | 8 ++++++++ 2 files changed, 9 insertions(+) diff --git a/changelog.md b/changelog.md index 942d2ab..b7b727d 100644 --- a/changelog.md +++ b/changelog.md @@ -7,6 +7,7 @@ sectionid: changelog #### All notable changes to the specification will be documented in this file. * 1.63.x + * Add `memoryReference` support to the `SetVariableResponse`/`SetExpressionResponse` * Fix a typo in the description of `BreakpointLocationsArguments` * Fix missing line break in `CancelRequest` * Clarify `memoryReference` in `Variable` type diff --git a/debugAdapterProtocol.json b/debugAdapterProtocol.json index c430b62..edf821b 100644 --- a/debugAdapterProtocol.json +++ b/debugAdapterProtocol.json @@ -2228,6 +2228,10 @@ "indexedVariables": { "type": "integer", "description": "The number of indexed child variables.\nThe client can use this information to present the variables in a paged UI and fetch them in chunks.\nThe value should be less than or equal to 2147483647 (2^31-1)." + }, + "memoryReference": { + "type": "string", + "description": "A memory reference to a location appropriate for this result.\nFor pointer type eval results, this is generally a reference to the memory address contained in the pointer.\nThis attribute may be returned by a debug adapter if corresponding capability `supportsMemoryReferences` is true." } }, "required": [ "value" ] @@ -2625,6 +2629,10 @@ "indexedVariables": { "type": "integer", "description": "The number of indexed child variables.\nThe client can use this information to present the variables in a paged UI and fetch them in chunks.\nThe value should be less than or equal to 2147483647 (2^31-1)." + }, + "memoryReference": { + "type": "string", + "description": "A memory reference to a location appropriate for this result.\nFor pointer type eval results, this is generally a reference to the memory address contained in the pointer.\nThis attribute may be returned by a debug adapter if corresponding capability `supportsMemoryReferences` is true." } }, "required": [ "value" ] From 8e0bf0e2aa3389e0b6651c151084772ddc724c8d Mon Sep 17 00:00:00 2001 From: Bruno Meneguele Date: Mon, 28 Aug 2023 12:14:07 -0300 Subject: [PATCH 7/8] Update Perl Debug adapter (#428) The Perl Debug project mentioned in the adapters table is currently archived and no longer maintained by the referrenced user. This commit updates the table pointing to the new Perl Debug project url, user and marketplace link. --- _implementors/adapters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_implementors/adapters.md b/_implementors/adapters.md index a2c989e..212f5da 100644 --- a/_implementors/adapters.md +++ b/_implementors/adapters.md @@ -62,7 +62,7 @@ Many adapters publish releases tailored for specific editors, such as VS Code, a [OCaml Earlybird](https://github.com/hackwaly/ocamlearlybird)|[@hackwaly](https://github.com/hackwaly)|[VS Code](https://marketplace.visualstudio.com/items?itemName=hackwaly.ocamlearlybird) [OneScript Debug](https://github.com/EvilBeaver/OneScript)|[@EvilBeaver](https://github.com/EvilBeaver)|[VS Code](https://marketplace.visualstudio.com/items?itemName=EvilBeaver.oscript-debug) [Papyrus](https://github.com/joelday/papyrus-debug-server)|[@joelday](https://github.com/joelday)|[VS Code](https://marketplace.visualstudio.com/items?itemName=joelday.papyrus-lang-vscode) -[Perl Debug](https://github.com/raix/vscode-perl-debug)|[@raix](https://github.com/raix)|[VS Code](https://marketplace.visualstudio.com/items?itemName=mortenhenriksen.perl-debug) +[Perl Debug](https://github.com/Nihilus118/vscode-perl-debug)|[@Nihilus118](https://github.com/Nihilus118)|[VS Code](https://marketplace.visualstudio.com/items?itemName=Nihilus118.perl-debugger) [Perl::LanguageServer](https://github.com/richterger/Perl-LanguageServer)|[@richterger](https://github.com/richterger)|[VS Code](https://marketplace.visualstudio.com/items?itemName=richterger.perl) [Php](https://github.com/xdebug/vscode-php-debug)|[@zobo](https://github.com/zobo)|[VS Code](https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug) [PowerShell](https://github.com/PowerShell/vscode-powershell)|[@daviwil](https://github.com/daviwil) [@rkeithhill](https://github.com/rkeithhill)|[VS Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode.PowerShell) From 1b4490ca849bf7b1c3652514a02a8e5763946481 Mon Sep 17 00:00:00 2001 From: Connor Peet Date: Thu, 31 Aug 2023 12:40:56 -0700 Subject: [PATCH 8/8] prep for 1.63 (#429) --- index.html | 2 +- specification.md | 43 ++++++++++++++++++++++++++++++++++--------- 2 files changed, 35 insertions(+), 10 deletions(-) diff --git a/index.html b/index.html index 255c4c4..9d90878 100644 --- a/index.html +++ b/index.html @@ -86,7 +86,7 @@

Specification

- The latest version of the protocol specification is version 1.62.0. + The latest version of the protocol specification is version 1.63.0.

Change History diff --git a/specification.md b/specification.md index 184cc47..59ac977 100644 --- a/specification.md +++ b/specification.md @@ -149,7 +149,9 @@ interface ErrorResponse extends Response { The `cancel` request is used by the client in two situations: - to indicate that it is no longer interested in the result produced by a specific request issued earlier -- to cancel a progress sequence. Clients should only call this request if the corresponding capability `supportsCancelRequest` is true. +- to cancel a progress sequence. + +Clients should only call this request if the corresponding capability `supportsCancelRequest` is true. This request has a hint characteristic: a debug adapter can only be expected to make a 'best effort' in honoring this request but there are no guarantees. @@ -1306,7 +1308,7 @@ Arguments for `breakpointLocations` request. interface BreakpointLocationsArguments { /** * The source location of the breakpoints; either `source.path` or - * `source.reference` must be specified. + * `source.sourceReference` must be specified. */ source: Source; @@ -2396,6 +2398,15 @@ interface SetVariableResponse extends Response { * The value should be less than or equal to 2147483647 (2^31-1). */ indexedVariables?: number; + + /** + * A memory reference to a location appropriate for this result. + * For pointer type eval results, this is generally a reference to the + * memory address contained in the pointer. + * This attribute may be returned by a debug adapter if corresponding + * capability `supportsMemoryReferences` is true. + */ + memoryReference?: string; }; } ``` @@ -2703,7 +2714,7 @@ interface EvaluateResponse extends Response { * A memory reference to a location appropriate for this result. * For pointer type eval results, this is generally a reference to the * memory address contained in the pointer. - * This attribute should be returned by a debug adapter if corresponding + * This attribute may be returned by a debug adapter if corresponding * capability `supportsMemoryReferences` is true. */ memoryReference?: string; @@ -2804,6 +2815,15 @@ interface SetExpressionResponse extends Response { * The value should be less than or equal to 2147483647 (2^31-1). */ indexedVariables?: number; + + /** + * A memory reference to a location appropriate for this result. + * For pointer type eval results, this is generally a reference to the + * memory address contained in the pointer. + * This attribute may be returned by a debug adapter if corresponding + * capability `supportsMemoryReferences` is true. + */ + memoryReference?: string; }; } ``` @@ -3978,10 +3998,13 @@ interface Variable { indexedVariables?: number; /** - * The memory reference for the variable if the variable represents executable - * code, such as a function pointer. - * This attribute is only required if the corresponding capability - * `supportsMemoryReferences` is true. + * A memory reference associated with this variable. + * For pointer type variables, this is generally a reference to the memory + * address contained in the pointer. + * For executable data, this reference may later be used in a `disassemble` + * request. + * This attribute may be returned by a debug adapter if corresponding + * capability `supportsMemoryReferences` is true. */ memoryReference?: string; } @@ -4027,9 +4050,11 @@ interface VariablePresentationHint { * 'readOnly': Indicates that the object is read only. * 'rawString': Indicates that the object is a raw string. * 'hasObjectId': Indicates that the object can have an Object ID created for - * it. + * it. This is a vestigial attribute that is used by some clients; 'Object + * ID's are not specified in the protocol. * 'canHaveObjectId': Indicates that the object has an Object ID associated - * with it. + * with it. This is a vestigial attribute that is used by some clients; + * 'Object ID's are not specified in the protocol. * 'hasSideEffects': Indicates that the evaluation had side effects. * 'hasDataBreakpoint': Indicates that the object has its value tracked by a * data breakpoint.