mirror of
https://github.com/dart-lang/sdk
synced 2024-09-15 23:49:47 +00:00
[analysis_server] Add some initial docs about running/debugging server from source in VS Code
Change-Id: I1218b3b583bc61d45a9568016ca825460717c12c Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/258360 Reviewed-by: Brian Wilkerson <brianwilkerson@google.com> Commit-Queue: Brian Wilkerson <brianwilkerson@google.com>
This commit is contained in:
Danny Tuppeny
Commit Bot
parent
cac7058892
commit
292ba46112
|
|
@ -8,4 +8,5 @@ processes documented in the `analyzer` package.
|
|||
|
||||
The documentation covers the following topics:
|
||||
|
||||
- [Implementing a new language feature](new_language_feature.md)
|
||||
- [Implementing a new language feature](new_language_feature.md)
|
||||
- [Running/Debugging analysis_server from source in VS Code](running_in_vs_code.md)
|
||||
|
|
|
|||
166
pkg/analysis_server/doc/process/running_in_vs_code.md
Normal file
166
pkg/analysis_server/doc/process/running_in_vs_code.md
Normal file
|
|
@ -0,0 +1,166 @@
|
|||
# Running/Debugging the Analysis Server from Source in VS Code
|
||||
|
||||
When working in the `analysis_server` package it's often useful to have VS Code
|
||||
run the server from your source instead of using a compiled snapshot from the
|
||||
SDK (which would require a potentially lengthy SDK build).
|
||||
|
||||
Server startup will be slower when running from source so it's recommended to
|
||||
enable this just for specific projects while testing and not generally run the
|
||||
server from source.
|
||||
|
||||
## VS Code Configuration
|
||||
|
||||
- Press `F1` to open the VS Code command palette
|
||||
- Run the **Preferences: Open Workspace Settings (JSON)** command
|
||||
- Add a `dart.analyzerPath` setting, pointing to the analysis servers's entry
|
||||
script:
|
||||
```
|
||||
"dart.analyzerPath": "/Users/developer/dart-sdk/sdk/pkg/analysis_server/bin/server.dart"
|
||||
```
|
||||
- Add `dart.sdkPath` pointing to an SDK that is compatible with the version of
|
||||
the source code being run (such as a recent [bleeding edge build][1]):
|
||||
```
|
||||
"dart.sdkPath": "/Users/developer/Dart SDKs/bleeding_edge"
|
||||
```
|
||||
- Press **Save**
|
||||
|
||||
Modifying the `dart.analyzerPath` or `dart.sdkPath` settings will automatically
|
||||
restart the analysis server. The server may take a little longer than usual to
|
||||
start up when running from source, but all interactions with the server will now
|
||||
be your local version.
|
||||
|
||||
## Capturing Protocol Traffic
|
||||
|
||||
There are a number of ways you can capture the traffic between VS Code and the
|
||||
Dart analysis server. The simplest way if you just need to capture some ad-hoc
|
||||
traffic is with the **Dart: Capture Analysis Server Logs** command.
|
||||
|
||||
- Press `F1` to open the VS Code command palette
|
||||
- Run the **Dart: Capture Analysis Server Logs** command
|
||||
- While the logging notification is visible, use the editor to trigger
|
||||
communication with the server.
|
||||
- If you accidentally hide the logging notification with `<escape>` you can get
|
||||
it back by clicking the bell icon in the status bar.
|
||||
- To stop logging and open the log file, click the **Cancel** button on the
|
||||
logging notification.
|
||||
|
||||
If you want to have traffic always written to files, you can use some workspace
|
||||
settings:
|
||||
|
||||
- Press `F1` to open the VS Code command palette
|
||||
- Run the **Preferences: Open Workspace Settings (JSON)** command
|
||||
- Add a `dart.analyzerLogFile` and/or `dart.analyzerInstrumentationLogFile`
|
||||
setting with an absolute or relative path for a log file:
|
||||
```
|
||||
"dart.analyzerLogFile": "logs/analyzer.txt",
|
||||
"dart.analyzerInstrumentationLogFile": "logs/analyzer.instrum.txt",
|
||||
```
|
||||
- Press **Save**
|
||||
|
||||
The `analyzerLogFile` is captured by the VS Code extension (client-side). This
|
||||
records all traffic between VS Code and the server as well as some header and
|
||||
startup information (such as how the server is being spawned) and any output to
|
||||
stderr. Lines in this log are truncated by default based on the
|
||||
`dart.maxLogLineLength` setting (you may wish to increase this if
|
||||
troubleshooting large requests).
|
||||
|
||||
The `analyzerInstrumentationLogFile` is written by the server. It also includes
|
||||
all protocol traffic but also some additional info (such as file watcher events)
|
||||
that the client does not have visibility of.
|
||||
|
||||
Which log file is most useful may depend on your needs.
|
||||
|
||||
At the time of writing, modifying the `dart.analyzerInstrumentationLogFile`
|
||||
setting will automatically restart the analysis server but
|
||||
`dart.analyzerLogFile` will not. You can force the server to restart using the
|
||||
**Dart: Restart Analysis Server** command in the VS Code command palette (`F1`)
|
||||
or restart the whole extension host with the **Developer: Reload Window**
|
||||
command.
|
||||
|
||||
## Attaching a Debugger
|
||||
|
||||
If the protocol traffic is not enough, you can attach a debugger to a running
|
||||
analysis server as long as its VM Service is enabled.
|
||||
|
||||
- Open two VS Code windows, one with the `analysis_server` code open and the
|
||||
other with a test project that will be running the server from source
|
||||
- In the test project, follow the instructions above in
|
||||
[VS Code Configuration][2] but additionally set the
|
||||
`dart.analyzerVmServicePort` setting to an available port number.
|
||||
> **NOTE:** This setting will enable the VM Service with authentication codes
|
||||
> disabled. Be sure to unset this setting once you are done debugging.
|
||||
```
|
||||
"dart.analyzerVmServicePort": 8222
|
||||
```
|
||||
- Click **Save** (the analysis server will be automatically restarted when
|
||||
`dart.analyzerVmServicePort` is modified)
|
||||
- Switch to the other VS Code instance that has the `analysis_server` source
|
||||
loaded
|
||||
- Press `F1` to open the VS Code command palette
|
||||
- Run the **Debug: Attach to Dart Process** command
|
||||
- Type the port number used in the `dart.analyzerVmServicePort` setting above
|
||||
and press `<enter>`
|
||||
|
||||
This should connect the debugger to the server running in the other VS Code
|
||||
window. If everything has worked you can add breakpoints in the server code and
|
||||
trigger them by interacting with the server in the test project. To test this is
|
||||
working, add a breakpoint to the top of `TextDocumentChangeHandler._changeFile`
|
||||
in `lib/src/lsp/handlers/handler_text_document_changes.dart` and modify a file
|
||||
in the test project to ensure the breakpoint is hit and you can evaluate
|
||||
values using the Debug Console, watch window or hovering over a variable.
|
||||
|
||||
## Other Useful Notes
|
||||
|
||||
### Multi-Root Workspaces
|
||||
|
||||
If you need to work on multiple projects (such as `analysis_server`, `analyzer`,
|
||||
`analyzer_plugin`) you can open this without everything else in the `pkg` folder
|
||||
by ctrl+clicking folders in the Open dialog, or by using **File -> Add Folder to
|
||||
Workspace** to add additional folders.
|
||||
|
||||
You can then save this workspace with **File -> Save Workspace** which creates
|
||||
a `.code-workspace` file that can be re-opened for the same folders later.
|
||||
|
||||
When using a `.code-workspace` like this, workspace-level settings (found via
|
||||
**Preferences: Open Workspace Settings (JSON)** command) will be stored in this
|
||||
file (since there isn't a single `.vscode/settings.json` file to store them in
|
||||
for a multi-root workspace). Similarly, launch configurations can be added to
|
||||
this file that apply to the whole workspace.
|
||||
|
||||
### Sorting and Organizing On-Save
|
||||
|
||||
In the `analysis_server` package, files should have directives and members
|
||||
sorted. You can configure this to happen on-save by adding the following to the
|
||||
workspace settings for the analyzer project:
|
||||
|
||||
```js
|
||||
"editor.codeActionsOnSave": {
|
||||
"source.organizeImports": true,
|
||||
"source.sortMembers": true
|
||||
},
|
||||
```
|
||||
|
||||
### Rulers
|
||||
|
||||
Code and comments are usually wrapped at 80 characters. You can enable a ruler
|
||||
at this point in Dart files with the following setting (either at workspace or
|
||||
user level):
|
||||
|
||||
```js
|
||||
"[dart]": {
|
||||
"editor.rulers": [80],
|
||||
}
|
||||
```
|
||||
|
||||
See [here][3] for some other useful/recommended settings.
|
||||
|
||||
### Analyzer Diagnostics Pages
|
||||
|
||||
Running the **Dart: Open Analyzer Diagnostics** command will start and open a
|
||||
small web app that provides some additional insight into the running server,
|
||||
including some timings and exceptions.
|
||||
|
||||
|
||||
[1]: https://gsdview.appspot.com/dart-archive/channels/be/raw/latest/sdk/
|
||||
[2]: #vs-code-configuration
|
||||
[3]: https://dartcode.org/docs/recommended-settings/
|
||||
Loading…
Reference in a new issue