Version 2.15.0-189.0.dev
Merge commit '1951cce55a9c1f8526e935da28811d92a7f2684f' into 'dev'
diff --git a/pkg/dds/CHANGELOG.md b/pkg/dds/CHANGELOG.md
index 15f499b..cccc7a8 100644
--- a/pkg/dds/CHANGELOG.md
+++ b/pkg/dds/CHANGELOG.md
@@ -1,3 +1,9 @@
+# 2.1.4
+- A new library `package:dds/dap.dart` exposes classes required to build a custom DAP
+ debug-adapter on top of the base Dart DAP functionality in DDS.
+ For more details on DAP support in Dart see
+ [this README](https://github.com/dart-lang/sdk/blob/main/pkg/dds/tool/dap/README.md).
+
# 2.1.3
- Ensure cancelling multiple historical streams with the same name doesn't cause an
asynchronous `StateError` to be thrown.
diff --git a/pkg/dds/lib/src/dap/adapters/dart.dart b/pkg/dds/lib/src/dap/adapters/dart.dart
index cc0e49a..b585cd5 100644
--- a/pkg/dds/lib/src/dap/adapters/dart.dart
+++ b/pkg/dds/lib/src/dap/adapters/dart.dart
@@ -1729,10 +1729,6 @@
/// Clients may not know about all debug options, so anything not included
/// in the map will not be updated by this method.
Future<void> _updateDebugOptions(Map<String, Object?> args) async {
- // TODO(dantup): Document this - it's a public API we expect to be used
- // by editors that can support it (although it will require custom
- // code as it's there's no DAP standard for this, or the settings it
- // toggles).
if (args.containsKey('debugSdkLibraries')) {
_isolateManager.debugSdkLibraries = args['debugSdkLibraries'] as bool;
}
diff --git a/pkg/dds/pubspec.yaml b/pkg/dds/pubspec.yaml
index a477fca..bafc2dc 100644
--- a/pkg/dds/pubspec.yaml
+++ b/pkg/dds/pubspec.yaml
@@ -3,7 +3,7 @@
A library used to spawn the Dart Developer Service, used to communicate with
a Dart VM Service instance.
-version: 2.1.3
+version: 2.1.4
homepage: https://github.com/dart-lang/sdk/tree/master/pkg/dds
diff --git a/pkg/dds/tool/dap/README.md b/pkg/dds/tool/dap/README.md
new file mode 100644
index 0000000..6ba9e91
--- /dev/null
+++ b/pkg/dds/tool/dap/README.md
@@ -0,0 +1,170 @@
+# Debug Adapter Protocol
+
+Dart includes support for debugging using [the Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) as an alternative to using the [VM Service](https://github.com/dart-lang/sdk/blob/master/runtime/vm/service/service.md) directly, simplying the integration for new editors.
+
+The debug adapters are started with the `dart debug_adapter` command and are intended to be consumed by DAP-compliant tools such as Dart-specific extensions for editors, or configured by users whose editors include generic configurable DAP clients.
+
+Two adapters are available:
+
+- `dart debug_adapter`
+- `dart debug_adapter --test`
+
+The standard adapter will run scripts using `dart` while the `--test` adapter will cause scripts to be run using `dart test` and will emit custom `dart.testNotification` events (described below).
+
+Because in the DAP protocol the client speaks first, running this command from the terminal will result in no output (nor will the process terminate). This is expected behaviour.
+
+For details on the standard DAP functionality, see [the Debug Adapter Protocol Overview](https://microsoft.github.io/debug-adapter-protocol/) and [the Debug Adapter Protocol Specification](https://microsoft.github.io/debug-adapter-protocol/specification). Custom extensions are detailed below.
+
+**Flutter**: To run Flutter apps, the equivalent command should be run through the `flutter` tool. This is unavailable at the time of writing, but details will be linked here once available.
+
+## Launch/Attach Arguments
+
+Arguments common to both `launchRequest` and `attachRequest` are:
+
+- `bool? debugExternalPackageLibraries` - whether to enable debugging for packages that are not inside the current workspace
+- `bool? debugSdkLibraries` - whether to enable debugging for SDK libraries
+- `bool? evaluateGettersInDebugViews` - whether to evaluate getters in expression evaluation requests (inc. hovers/watch windows)
+- `bool? evaluateToStringInDebugViews` - whether to invoke `toString()` in expression evaluation requests (inc. hovers/watch windows)
+- `bool? sendLogsToClient` - used to proxy all VM Service traffic back to the client in custom `dart.log` events (has performance implications, intended for troubleshooting)
+- `int? vmServicePort` - the port to bind the VM Service too
+- `List<String>? additionalProjectPaths` - paths of any projects (outside of `cwd`) that are open in the users workspace
+- `String? cwd` - the working directory for the Dart process to be spawned in
+
+Arguments specific to `launchRequest` are:
+
+- `bool? noDebug` - whether to run in debug or noDebug mode (if not supplied, defaults to debug)
+- `String program` - the path of the Dart program to run
+- `List<String>? args` - arguments to be passed to the Dart program
+- `List<String>? toolArgs` - arguments for the Dart VM
+- `String? console` - if set to `"terminal"` or `"externalTerminal"` will be run using the `runInTerminal` reverse-request; otherwise the debug adapter spawns the Dart process
+- `bool? enableAsserts` - whether to enable asserts (if not supplied, defaults to enabled)
+
+Arguments specific to `attachRequest` are:
+
+- `String vmServiceInfoFile` - the file to read the VM Service info from \*
+- `String vmServiceInfoFile` - the VM Service URI to attach to \*
+
+\* Exactly one of `vmServiceInfoFile` or `vmServiceInfoFile` should be supplied.
+
+## Custom Requests
+
+Some custom requests are available for clients to call.
+
+### `updateDebugOptions`
+
+`updateDebugOptions` allows updating some debug options usually provided at launch/attach while the session is running. Any keys included in the request will overwrite the previously set values. To update only some values, include only those in the parameters.
+
+```
+{
+ "debugSdkLibraries": true
+ "debugExternalPackageLibraries": false
+}
+```
+
+### `callService`
+
+`callService` allows calling arbitrary services (for example service extensions that have been registered). The service RPC/method should be sent in the `method` field and `params` will depend on the service being called.
+
+```
+{
+ "method": "myFooService",
+ "params": {
+ // ...
+ }
+}
+```
+
+## Custom Events
+
+The debug adapter may emit several custom events that are useful to clients.
+
+### `dart.debuggerUris`
+
+When running in debug mode, a `dart.debuggerUris` event will be emitted containing the URI of the VM Service.
+
+```
+{
+ "type": "event",
+ "event": "dart.debuggerUris",
+ "body": {
+ "vmServiceUri": "ws://127.0.0.1:123/abdef123="
+ }
+}
+```
+
+### `dart.log`
+
+When `sendLogsToClient` in the launch/attach arguments is `true`, debug logging and all traffic to the VM Service will be proxied back to the client in `dart.log` events to aid troubleshooting.
+
+```
+{
+ "type": "event",
+ "event": "dart.log",
+ "body": "<log message or json string>"
+}
+```
+
+### `dart.serviceRegistered`
+
+Emitted when a VM Service is registered.
+
+```
+{
+ "type": "event",
+ "event": "dart.serviceRegistered",
+ "body": {
+ "service": "ServiceName",
+ "method": "methodName"
+ }
+}
+```
+
+### `dart.serviceUnregistered`
+
+Emitted when a VM Service is unregistered.
+
+```
+{
+ "type": "event",
+ "event": "dart.serviceUnregistered",
+ "body": {
+ "service": "ServiceName",
+ "method": "methodName"
+ }
+}
+```
+
+### `dart.serviceExtensionAdded`
+
+Emitted when a VM Service Extension is added.
+
+```
+{
+ "type": "event",
+ "event": "dart.serviceExtensionAdded",
+ "body": {
+ "extensionRPC": "<extensionRPC to call>",
+ "isolateId": "<isolateId>"
+ }
+}
+```
+
+### `dart.testNotification`
+
+When running the `--test` debug adapter, `package:test` JSON messages will be passed back to the client in a `dart.testNotification` event. For details on this protocol, see the [package:test documentation](https://github.com/dart-lang/test/blob/master/pkgs/test/doc/json_reporter.md).
+
+```
+{
+ "type": "event",
+ "event": "dart.testNotification",
+ "body": {
+ "type": "testStart",
+ "test": {
+ "id": 1,
+ "name": "my test name",
+ // ...
+ }
+ }
+}
+```
+
diff --git a/sdk/lib/async/zone.dart b/sdk/lib/async/zone.dart
index 8d4bdf9..e206152 100644
--- a/sdk/lib/async/zone.dart
+++ b/sdk/lib/async/zone.dart
@@ -817,7 +817,7 @@
/// Equivalent to:
/// ```dart
/// ZoneCallback registered = this.registerUnaryCallback(callback);
- /// return (arg) => thin.runUnary(registered, arg);
+ /// return (arg) => this.runUnary(registered, arg);
/// ```
ZoneUnaryCallback<R, T> bindUnaryCallback<R, T>(R callback(T argument));
@@ -827,7 +827,7 @@
/// Equivalent to:
/// ```dart
/// ZoneCallback registered = registerBinaryCallback(callback);
- /// return (arg1, arg2) => thin.runBinary(registered, arg1, arg2);
+ /// return (arg1, arg2) => this.runBinary(registered, arg1, arg2);
/// ```
ZoneBinaryCallback<R, T1, T2> bindBinaryCallback<R, T1, T2>(
R callback(T1 argument1, T2 argument2));
diff --git a/tools/VERSION b/tools/VERSION
index 47a58ca..1568b43 100644
--- a/tools/VERSION
+++ b/tools/VERSION
@@ -27,5 +27,5 @@
MAJOR 2
MINOR 15
PATCH 0
-PRERELEASE 188
+PRERELEASE 189
PRERELEASE_PATCH 0
\ No newline at end of file
