Merge pull request #498 from microsoft/main

DAP 1.68

_data/specification-toc.yml

@@ -85,6 +85,8 @@
       anchor: Requests_Launch
     - title: LoadedSources
       anchor: Requests_LoadedSources
+    - title: Locations
+      anchor: Requests_Locations
     - title: Modules
       anchor: Requests_Modules
     - title: Next

_implementors/adapters.md

@@ -19,6 +19,7 @@ Many adapters publish releases tailored for specific editors, such as VS Code, a
 [C/C++](https://github.com/Microsoft/vscode-cpptools)|[@WardenGnaw](https://github.com/WardenGnaw)|[VS Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools)
 [C/C++/Rust](https://github.com/Marus/cortex-debug)|[@Marus](https://github.com/Marus)|[VS Code](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug)
 [C#](https://github.com/OmniSharp/omnisharp-vscode)|[@gregg-miskelly](https://github.com/gregg-miskelly)|[VS Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode.csharp)
+[Cobol](https://github.com/RechInformatica/rech-cobol-debugger)|[@RechInformatica](https://github.com/RechInformatica)|[VS Code](https://marketplace.visualstudio.com/items?itemName=rechinformatica.rech-cobol-debugger)
 [Cordova Tools](https://github.com/Microsoft/vscode-cordova)|[@MSLaguana](https://github.com/MSLaguana)|[VS Code](https://marketplace.visualstudio.com/items?itemName=vsmobile.cordova-tools)
 [Dart](https://github.com/dart-lang/sdk)|[@DanTup](https://github.com/DanTup) [@devoncarew](https://github.com/devoncarew)|[DAP Server](https://github.com/dart-lang/sdk/blob/master/pkg/dds/tool/dap/README.md), [VS Code](https://marketplace.visualstudio.com/items?itemName=Dart-Code.dart-code)
 [Debug](https://github.com/WebFreak001/code-debug)|[@WebFreak001](https://github.com/WebFreak001)|[VS Code](https://marketplace.visualstudio.com/items?itemName=webfreak.debug)
@@ -82,6 +83,7 @@ Many adapters publish releases tailored for specific editors, such as VS Code, a
 [TLA+](https://github.com/tlaplus/vscode-tlaplus)|[@lemmy](https://github.com/lemmy)|[VS Code](https://marketplace.visualstudio.com/items?itemName=alygin.vscode-tlaplus-nightly)
 [VDM-SL, VDM++, VDM-RT](https://github.com/nickbattle/vdmj/tree/master/lsp)|[@nickbattle](https://github.com/nickbattle)|[VS Code](https://marketplace.visualstudio.com/items?itemName=jonaskrask.vdm-vscode)
 [VSCode rdbg Ruby Debugger](https://github.com/ruby/vscode-rdbg)|[@ko1](https://github.com/ko1)|[VS Code](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg)
+[Wolfram Language](https://github.com/kenkangxgwe/lsp-wl?tab=readme-ov-file#debug-adapter-features)|[@kenkangxgwe](https://github.com/kenkangxgwe/lsp-wl)|[VS Code](https://marketplace.visualstudio.com/items?itemName=lsp-wl.lsp-wl-client)
 {: .table .table-bordered .table-responsive}
 
 *If you are missing a debug adapter implementation please create a pull request in GitHub against this markdown [document](https://github.com/Microsoft/debug-adapter-protocol/blob/main/_implementors/adapters.md)*

changelog.md

@@ -6,6 +6,12 @@ sectionid: changelog
 
 #### All notable changes to the specification will be documented in this file.
 
+* 1.68.x
+  * Add `locationReference`s to Variable-related data types to allow navigation to declarations, and a corresponding `locations` request.
+  * Clarify the meaning of "system process"
+  * Clarify the lifetime of `variableReference`s after a `setVariable` call
+  * Fix typographic errors in `StackFrame.canRestart`
+
 * 1.67.x
   * Add `line`, `column`, and `source` location attributions to `EvaluateArguments`
   * Add `returnValue` as a well-known `Scope.presentationHint`

debugAdapterProtocol.json

@@ -392,6 +392,10 @@
 							"data": {
 								"type": [ "array", "boolean", "integer", "null", "number" , "object", "string" ],
 								"description": "Additional data to report. For the `telemetry` category the data is sent to telemetry, for the other categories the data is shown in JSON format."
+							},
+							"locationReference": {
+								"type": "integer",
+								"description": "A reference that allows the client to request the location where the new value is declared. For example, if the logged value is function pointer, the adapter may be able to look up the function's location. This should be present only if the adapter is likely to be able to resolve the location.\n\nThis reference shares the same lifetime as the `variablesReference`. See 'Lifetime of Object References' in the Overview section for details."
 							}
 						},
 						"required": ["output"]
@@ -508,7 +512,7 @@
 								},
 								"systemProcessId": {
 									"type": "integer",
-									"description": "The system process id of the debugged process. This property is missing for non-system processes."
+									"description": "The process ID of the debugged process, as assigned by the operating system. This property should be omitted for logical processes that do not map to operating system processes on the machine."
 								},
 								"isLocalProcess": {
 									"type": "boolean",
@@ -2231,7 +2235,7 @@
 							},
 							"variablesReference": {
 								"type": "integer",
-								"description": "If `variablesReference` is > 0, the new value is structured and its children can be retrieved by passing `variablesReference` to the `variables` request as long as execution remains suspended. See 'Lifetime of Object References' in the Overview section for details."
+								"description": "If `variablesReference` is > 0, the new value is structured and its children can be retrieved by passing `variablesReference` to the `variables` request as long as execution remains suspended. See 'Lifetime of Object References' in the Overview section for details.\n\nIf this property is included in the response, any `variablesReference` previously associated with the updated variable, and those of its children, are no longer valid."
 							},
 							"namedVariables": {
 								"type": "integer",
@@ -2244,6 +2248,10 @@
 							"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."
+							},
+							"valueLocationReference": {
+								"type": "integer",
+								"description": "A reference that allows the client to request the location where the new value is declared. For example, if the new value is function pointer, the adapter may be able to look up the function's location. This should be present only if the adapter is likely to be able to resolve the location.\n\nThis reference shares the same lifetime as the `variablesReference`. See 'Lifetime of Object References' in the Overview section for details."
 							}
 						},
 						"required": [ "value" ]
@@ -2483,7 +2491,7 @@
 		"EvaluateRequest": {
 			"allOf": [ { "$ref": "#/definitions/Request" }, {
 				"type": "object",
-				"description": "Evaluates the given expression in the context of the topmost stack frame.\nThe expression has access to any variables and arguments that are in scope.",
+				"description": "Evaluates the given expression in the context of a stack frame.\nThe expression has access to any variables and arguments that are in scope.",
 				"properties": {
 					"command": {
 						"type": "string",
@@ -2574,6 +2582,10 @@
 							"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."
+							},
+							"valueLocationReference": {
+								"type": "integer",
+								"description": "A reference that allows the client to request the location where the returned value is declared. For example, if a function pointer is returned, the adapter may be able to look up the function's location. This should be present only if the adapter is likely to be able to resolve the location.\n\nThis reference shares the same lifetime as the `variablesReference`. See 'Lifetime of Object References' in the Overview section for details."
 							}
 						},
 						"required": [ "result", "variablesReference" ]
@@ -2657,6 +2669,10 @@
 							"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."
+							},
+							"valueLocationReference": {
+								"type": "integer",
+								"description": "A reference that allows the client to request the location where the new value is declared. For example, if the new value is function pointer, the adapter may be able to look up the function's location. This should be present only if the adapter is likely to be able to resolve the location.\n\nThis reference shares the same lifetime as the `variablesReference`. See 'Lifetime of Object References' in the Overview section for details."
 							}
 						},
 						"required": [ "value" ]
@@ -3083,6 +3099,68 @@
 			}]
 		},
 
+		"LocationsRequest": {
+			"allOf": [ { "$ref": "#/definitions/Request" }, {
+				"type": "object",
+				"description": "Looks up information about a location reference previously returned by the debug adapter.",
+				"properties": {
+					"command": {
+						"type": "string",
+						"enum": [ "locations" ]
+					},
+					"arguments": {
+						"$ref": "#/definitions/LocationsArguments"
+					}
+				},
+				"required": [ "command", "arguments" ]
+			}]
+		},
+		"LocationsArguments": {
+			"type": "object",
+			"description": "Arguments for `locations` request.",
+			"properties": {
+				"locationReference": {
+					"type": "integer",
+					"description": "Location reference to resolve."
+				}
+			},
+			"required": [ "locationReference" ]
+		},
+		"LocationsResponse": {
+			"allOf": [ { "$ref": "#/definitions/Response" }, {
+				"type": "object",
+				"description": "Response to `locations` request.",
+				"properties": {
+					"body": {
+						"type": "object",
+						"properties": {
+							"source": {
+								"$ref": "#/definitions/Source",
+								"description": "The source containing the location; either `source.path` or `source.sourceReference` must be specified."
+							},
+							"line": {
+								"type": "integer",
+								"description": "The line number of the location. The client capability `linesStartAt1` determines whether it is 0- or 1-based."
+							},
+							"column": {
+								"type": "integer",
+								"description": "Position of the location within the `line`. It is measured in UTF-16 code units and the client capability `columnsStartAt1` determines whether it is 0- or 1-based. If no column is given, the first position in the start line is assumed."
+							},
+							"endLine": {
+								"type": "integer",
+								"description": "End line of the location, present if the location refers to a range.  The client capability `linesStartAt1` determines whether it is 0- or 1-based."
+							},
+							"endColumn": {
+								"type": "integer",
+								"description": "End position of the location within `endLine`, present if the location refers to a range. It is measured in UTF-16 code units and the client capability `columnsStartAt1` determines whether it is 0- or 1-based."
+							}
+						},
+						"required": [ "source", "line" ]
+					}
+				}
+			}]
+		},
+
 		"Capabilities": {
 			"type": "object",
 			"title": "Types",
@@ -3515,7 +3593,7 @@
 				},
 				"canRestart": {
 					"type": "boolean",
-					"description": "Indicates whether this frame can be restarted with the `restart` request. Clients should only use this if the debug adapter supports the `restart` request and the corresponding capability `supportsRestartRequest` is true. If a debug adapter has this capability, then `canRestart` defaults to `true` if the property is absent."
+					"description": "Indicates whether this frame can be restarted with the `restartFrame` request. Clients should only use this if the debug adapter supports the `restart` request and the corresponding capability `supportsRestartFrame` is true. If a debug adapter has this capability, then `canRestart` defaults to `true` if the property is absent."
 				},
 				"instructionPointerReference": {
 					"type": "string",
@@ -3632,6 +3710,14 @@
 				"memoryReference": {
 					"type": "string",
 					"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."
+				},
+				"declarationLocationReference": {
+					"type": "integer",
+					"description": "A reference that allows the client to request the location where the variable is declared. This should be present only if the adapter is likely to be able to resolve the location.\n\nThis reference shares the same lifetime as the `variablesReference`. See 'Lifetime of Object References' in the Overview section for details."
+				},
+				"valueLocationReference": {
+					"type": "integer",
+					"description": "A reference that allows the client to request the location where the variable's value is declared. For example, if the variable contains a function pointer, the adapter may be able to look up the function's location. This should be present only if the adapter is likely to be able to resolve the location.\n\nThis reference shares the same lifetime as the `variablesReference`. See 'Lifetime of Object References' in the Overview section for details."
 				}
 			},
 			"required": [ "name", "value", "variablesReference" ]

overview.md

@@ -224,4 +224,4 @@ This diagram summarizes the sequence of request and events for a hypothetical de
 
 To simplify the implementation of debug adapters, there are libraries or SDKs:
 
-- *Debug Adapter SDKs* for the different implementation languages there is an SDK to implement a debug adapter in a particular language. For example, to implement a debug adapter using Node.js there is the [debug adapter npm module](https://www.npmjs.com/package/vscode-debugadapter).
+- *Debug Adapter SDKs* for the different implementation languages there is an SDK to implement a debug adapter in a particular language. For example, to implement a debug adapter using Node.js there is the [debug adapter npm module](https://www.npmjs.com/package/@vscode/debugadapter).