From 40f6746c6f024f748caa671a47e2cc4128174dd2 Mon Sep 17 00:00:00 2001 From: Kenzie Schmoll Date: Thu, 4 Apr 2024 15:50:02 +0000 Subject: [PATCH] Improve documentation for DDS and DTD Change-Id: I51387b733af9e84509e28e1ba806a8be957232e9 Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/360903 Commit-Queue: Kenzie Davisson Reviewed-by: Ben Konyi --- pkg/dds/CHANGELOG.md | 1 + pkg/dds/CONTRIBUTING.md | 53 +++++++++++++++++++++++++++++++++++++++++ pkg/dds/README.md | 23 ------------------ pkg/dtd/CHANGELOG.md | 1 + pkg/dtd/CONTRIBUTING.md | 37 ++++++++++++++++++++++++++++ 5 files changed, 92 insertions(+), 23 deletions(-) create mode 100644 pkg/dds/CONTRIBUTING.md create mode 100644 pkg/dtd/CONTRIBUTING.md diff --git a/pkg/dds/CHANGELOG.md b/pkg/dds/CHANGELOG.md index 0c84715e9c4..c7cb39c690e 100644 --- a/pkg/dds/CHANGELOG.md +++ b/pkg/dds/CHANGELOG.md @@ -2,6 +2,7 @@ - Internal change: removed static method `DevToolsUtils.initializeAnalytics` and prepared DDS for using `unified_analytics` through the Dart Tooling Daemon. - Internal change: removed `analytics` parameter from the DevTools server `defaultHandler` method. +- Updated `README.md` and added contributing guide (`CONTRIBUTING.md`). # 4.0.0 - Updated DDS protocol to version 2.0. diff --git a/pkg/dds/CONTRIBUTING.md b/pkg/dds/CONTRIBUTING.md new file mode 100644 index 00000000000..ddad2147720 --- /dev/null +++ b/pkg/dds/CONTRIBUTING.md @@ -0,0 +1,53 @@ +# Development for `package:dds` + +One way to get stdout from files in DDS while debugging is to log messages to a file. You can add a method such as: + +```dart +void _fileLog(String message) { + final file = File('/tmp/dds.log'); + if (!file.existsSync()) { + file.createSync(); + } + file.writeAsStringSync( +''' +$message +''', + mode: FileMode.append, + flush: true, + ); +} +``` + +Then you can call `_fileLog('some print debugging message')`, and the log message will be written to a temp file. + +To get logging output in real time, run `tail -f /tmp/dds.log`. + +## Making changes to `package:dds` and `package:devtools_shared` + +**If you do not need to build the Dart SDK** to test your changes, you +can add a `dependency_overrides` for `devtools_shared` that points to your +local `devtools_shared` directory from path: + +```yaml +dependency_overrides: + devtools_shared: + path: ../../relative_path_to/devtools/packages/devtools_shared +``` + +**If you do need to build the Dart SDK** to test your changes, in addition +to adding the dependency override above, you will need to add a symbolic link +to your local `devtools_shared` directory: + +From the `sdk/` directory, run: +```shell +rm -rf third_party/devtools/devtools_shared; +ln -s /absolute_path_to/devtools/packages/devtools_shared third_party/devtools/devtools_shared +``` + +**WARNING**: do not run `gclient sync -D` while the symbolic link is present, +as this could cause issues with your local `devtools_shared` code. + +To delete the symbolic link after you are done with development, run: +```shell +rm -rf third_party/devtools/devtools_shared +``` diff --git a/pkg/dds/README.md b/pkg/dds/README.md index e06ceacca32..3bab225cba3 100644 --- a/pkg/dds/README.md +++ b/pkg/dds/README.md @@ -37,26 +37,3 @@ void main() { [dds-protocol]: dds_protocol.md [service-protocol]: https://github.com/dart-lang/sdk/blob/main/runtime/vm/service/service.md - -# Debugging DDS - -One way to get stdout from files in DDS while debugging is to log messages to a file. You can add a method such as: - -```dart -void _fileLog(String message) { - final file = File('/tmp/dds.log'); - if (!file.existsSync()) { - file.createSync(); - } - file.writeAsStringSync( -''' -$message -''', - mode: FileMode.append, - ); -} -``` - -Then you can call `_fileLog('some print debugging message')`, and the log message will be written to a temp file. - -To get logging output in real time, run `tail -f /tmp/dds.log`. diff --git a/pkg/dtd/CHANGELOG.md b/pkg/dtd/CHANGELOG.md index 609eedca78e..03b53316bd2 100644 --- a/pkg/dtd/CHANGELOG.md +++ b/pkg/dtd/CHANGELOG.md @@ -1,5 +1,6 @@ ## 2.2.0 - Added new response types `Success`, `StringResponse`, `BoolResponse`, and `StringListResponse`. +- Added contributing guide (`CONTRIBUTING.md`). ## 2.1.0 - Added `getProjectRoots` API. diff --git a/pkg/dtd/CONTRIBUTING.md b/pkg/dtd/CONTRIBUTING.md new file mode 100644 index 00000000000..38ac161434a --- /dev/null +++ b/pkg/dtd/CONTRIBUTING.md @@ -0,0 +1,37 @@ +# Contributing guide + +When making changes to `package:dtd` and `package:dtd_impl` at the same +time, you'll need to +[build the Dart SDK](https://github.com/dart-lang/sdk/wiki/Building#building) +to ensure that changes to +`package:dtd_impl` are picked up in the DTD snapshot. + +## Helpful aliases + +Consider adding these aliases to your `.zshrc` file for convenience. For +non-macOS platforms, replace "xcodebuild" with "out". +``` +# Builds the entire Dart SDK. Run from the sdk/ directory. +alias build-dart='./tools/build.py -mrelease create_sdk' + +# The create_platform_sdk target will work exactly the same as the +# `create_sdk` target but without building the web tooling. +alias build-dart-fast='./tools/build.py -mrelease create_platform_sdk' + +# The dart exe that was built by running 'build-dart' or 'build-dart-fast' +# will be located here. Create an alias for convenience of using the dart exe. +alias sdkdart='/absolute_path_to/sdk/xcodebuild/ReleaseX64/dart-sdk/bin/dart' + +# The runtime target will only build what the VM needs to run, but will output +# the compiled dart binary at `xcodebuild/ReleaseX64/dart` instead of +# `xcodebuild/ReleaseX64/dart-sdk/bin/dart`. Runtime is a bit faster than +# `create_platform_sdk`, but both are faster than `create_sdk`. +alias build-dart-runtime='./tools/build.py -mrelease runtime' + +# The dart exe that was built by running `build-dart-runtime`. +alias sdkruntime='/absolute_path_to/sdk/xcodebuild/ReleaseX64/dart' +``` + +After building the Dart SDK with your local changes, use the `dart` +executable that you just built to run commands that you want your +local changes applied to (e.g. `sdkdart run ...`, `sdkdart test ...`).