Skip to content

Commit e0925a8

Browse files
srawlinssrawlins
authored
Fork all debugging docs out of CONTRIBUTING.md into their own doc (#9278)
1 parent 8b4b80a commit e0925a8

2 files changed

Lines changed: 173 additions & 134 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 2 additions & 134 deletions
Original file line numberDiff line numberDiff line change
@@ -33,18 +33,6 @@ You can do this online, and it only takes a minute.
3333

3434
2. Review the [DevTools style guide](STYLE.md), which uses a combination of Dart and Flutter best practices.
3535

36-
## Table of contents
37-
1. [Developing for DevTools](#developing-for-devtools)
38-
- [Set up your DevTools environment](#set-up-your-devtools-environment)
39-
- [Workflow for making changes](#workflow-for-making-changes)
40-
- [Keeping your fork in sync](#keeping-your-fork-in-sync)
41-
2. [Running and debugging DevTools](#running-and-debugging-devtools)
42-
- [Frontend only (most common)](#frontend-only-most-common)
43-
- [Frontend + DevTools server](#frontend--devtools-server)
44-
- [DevTools + VS Code integration](#ide-embedded-devtools-experience)
45-
3. [Testing for DevTools](#testing-for-devtools)
46-
4. [Appendix](#appendix)
47-
4836
## Developing for DevTools
4937

5038
### Set up your DevTools environment
@@ -164,134 +152,14 @@ not want to merge `upstream/master` or update your Flutter SDK version, instead
164152

165153
## Running and debugging DevTools
166154

167-
There are a few different environments that you may need to run DevTools in. After running DevTools
168-
in one of the environments below, connect to a test application to debug DevTools runtime tooling
169-
(the majority of DevTools tools). See the
170-
[Connect DevTools to a test application](#connect-devtools-to-a-test-application) section below.
171-
172-
### Frontend only (most common)
173-
174-
Most of the time, you will not need to run DevTools with the DevTools server to test your changes.
175-
You can run DevTools in debug mode as either a Flutter web or Flutter desktop app.
176-
177-
> Note: though DevTools is shipped as a Flutter Web app, we recommend developing as a Flutter
178-
Desktop app whenever possible for a more efficient development workflow. Please see the
179-
[running on Flutter desktop](#running-devtools-on-flutter-desktop) section below for instructions.
180-
181-
- To run DevTools as a Flutter web app **from VS Code**, run with the **devtools** configuration and the "Chrome" device
182-
- To run with experiments enabled, run from VS Code with the **devtools + experiments** configuration
183-
- To run DevTools as a Flutter web app **from the command line**, run `flutter run -d chrome`
184-
- To run with experiments enabled, add the flag `--dart-define=enable_experiments=true`
185-
186-
### Frontend + DevTools server
187-
188-
To develop with a workflow that exercises the DevTools server <==> DevTools client connection,
189-
you will need to perform the following set up steps (first time only).
190-
191-
1. Clone the [Dart SDK](https://github.com/dart-lang/sdk) fron GitHub.
192-
2. The `LOCAL_DART_SDK` environment variable needs to point to this path: `export LOCAL_DART_SDK=/path/to/dart/sdk`
193-
194-
If you are also developing server side code (e.g. the `devtools_shared` package), you will need to modify
195-
the `devtools_shared` dependency override in `sdk/pubspec.yaml` to point to your local `devtools_shared`
196-
package:
197-
198-
```yaml
199-
dependency_overrides:
200-
devtools_shared:
201-
path: /path/to/devtools/packages/devtools_shared
202-
```
203-
204-
Then you can run DevTools with the server by running the following from anywhere under the `devtools/` directory:
205-
1. To run the DevTools web app in release mode, served with the DevTools server (this emulates the production environment):
206-
```
207-
dt serve
208-
```
209-
2. To run the DevTools web app in debug mode, with full debugging support, and with a connection to a live DevTools server:
210-
```sh
211-
dt run
212-
```
213-
214-
Option 2 is useful for a quicker development cycle. The DevTools build time will be faster, and you will be
215-
able to connect the DevTools web app to an IDE or another DevTools instance for debugging purposes.
216-
217-
To see the full list of arguments available for either command, please pass the `-h` flag.
218-
219-
### IDE-embedded DevTools experience
220-
221-
#### DevTools + VS Code integration
222-
223-
To test the integration with VS Code, you can set up the Dart VS Code extension to run DevTools
224-
and the server from your local source code. Follow the
225-
[Frontend + DevTools server](#frontend--devtools-server) setup instructions above, and make sure
226-
you have version v3.47 or newer of the Dart extension for VS Code.
227-
228-
Open your VS Code settings (Run the **Preferences: Open User Settings (JSON)** command from the
229-
command palette (`F1`)) and add the following to your settings:
230-
231-
```js
232-
"dart.customDevTools": {
233-
"path": "/absolute/path/to/devtools/repo",
234-
"env": {
235-
"LOCAL_DART_SDK": "/absolute/path/to/sdk",
236-
// Path to the Flutter SDK that will be used to build DevTools. This may
237-
// be the path to the included Flutter SDK under the tool/ directory or
238-
// the path to your local Flutter SDK git checkout.
239-
"FLUTTER_ROOT": "/absolute/path/to/devtools/tool/flutter-sdk"
240-
},
241-
"args": [
242-
// Arguments that will be passed along to the `dt serve` command.
243-
],
244-
},
245-
```
246-
247-
This instructs VS Code to run the `dt serve` command instead of running `dart devtools`.
248-
You must set the `LOCAL_DART_SDK` and `FLUTTER_ROOT` env variables correctly for the script to work.
249-
250-
Next, restart VS Code (or run the **Developer: Reload Window** command from the command palette (`F1`))
251-
and DevTools will be run from your local source code. After making any code changes to DevTools or the
252-
server, you will need to re-run the **Developer: Reload Window** command to rebuild and restart the server.
253-
254-
#### DevTools + IntelliJ integration
255-
256-
Follow instructions in the Flutter-IntelliJ repo's `CONTRIBUTING` guide: [#developing-with-local-devtools](https://github.com/flutter/flutter-intellij/blob/master/CONTRIBUTING.md#developing-with-local-devtools)
155+
Please see [DEBUGGING.md][] for guidance on running and debugging DevTools.
257156

258157
## Testing for DevTools
259158

260-
Please see [TESTING.md](TESTING.md) for guidance on running and writing tests.
159+
Please see [TESTING.md][] for guidance on running and writing tests.
261160

262161
## Appendix
263162

264-
### Connect DevTools to a test application
265-
266-
For working on most DevTools tools, a connection to a running Dart or Flutter app is required. Run any Dart or Flutter app of your choice to
267-
connect it to DevTools. Consider running [veggieseasons](https://github.com/flutter/samples/tree/main/veggieseasons) or another Flutter sample since those apps have plenty of interesting
268-
code to debug.
269-
1. Run your Dart or Flutter app.
270-
> Note: some DevTools features may be unavailable depending on the test app platform (Flutter native, Flutter web, Dart CLI, etc.) or run mode
271-
(debug, profile) you choose.
272-
2. Copy the URI printed to the command line (you will use this URI to connect to DevTools).
273-
274-
```
275-
"A Dart VM Service on iPhone 14 Pro Max is available at: <copy-this-uri>"
276-
```
277-
3. Paste this URI into the connect dialog in DevTools and click "Connect".
278-
279-
![Connect dialog example](_markdown_images/connect_dialog_example.png)
280-
281-
### Running DevTools on Flutter Desktop
282-
283-
For a faster development cycle with hot reload, you can run DevTools on Flutter desktop. Some DevTools
284-
features only work on the web, like the embedded Perfetto trace viewer, DevTools extensions, or WASM support,
285-
but the limitations on the desktop app are few.
286-
287-
To run DevTools with the desktop embedder, you can run `flutter run -d macos` from `devtools/packages/devtools_app`,
288-
or you can run DevTools from your IDE with the `macOS` device selected.
289-
290-
If this fails, you may need to run `flutter create .` from `devtools/packages/devtools_app` to generate
291-
the updated files for your platform. If you want to run DevTools on Flutter desktop for Windows or Linux,
292-
you will need to generate the files for this platform using the `flutter create .` command, and then run using
293-
`flutter run -d <windows or linux>`.
294-
295163
### Enable and activate DCM (Dart Code Metrics)
296164

297165
Enabling and activating DCM is optional. When you open a PR, the CI bots will show you any DCM warnings introduced

‎DEBUGGING.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
<!--
2+
Copyright 2025 The Flutter Authors
3+
Use of this source code is governed by a BSD-style license that can be
4+
found in the LICENSE file or at https://developers.google.com/open-source/licenses/bsd.
5+
-->
6+
7+
# Running and debugging DevTools
8+
9+
There are a few different environments that you may need to run DevTools in.
10+
After running DevTools in one of the environments below, connect to a test
11+
application to debug DevTools runtime tooling (the majority of DevTools tools).
12+
See the [Connect DevTools to a test
13+
application](#connect-devtools-to-a-test-application) section below.
14+
15+
## Frontend only (most common)
16+
17+
Most of the time, you will not need to run DevTools with the DevTools server to
18+
test your changes. You can run DevTools in debug mode as either a Flutter web
19+
or Flutter desktop app.
20+
21+
> Note: though DevTools is shipped as a Flutter Web app, we recommend
22+
> developing as a Flutter Desktop app whenever possible for a more efficient
23+
> development workflow. Please see the [running on Flutter
24+
> desktop](#running-devtools-on-flutter-desktop) section below for
25+
> instructions.
26+
27+
- To run DevTools as a Flutter web app **from VS Code**, run with the
28+
**devtools** configuration and the "Chrome" device.
29+
- To run with experiments enabled, run from VS Code with the
30+
**devtools + experiments** configuration.
31+
- To run DevTools as a Flutter web app **from the command line**, run
32+
`flutter run -d chrome`.
33+
- To run with experiments enabled, add the flag
34+
`--dart-define=enable_experiments=true`.
35+
36+
## Frontend + DevTools server
37+
38+
To develop with a workflow that exercises the DevTools server <==> DevTools
39+
client connection, you will need to perform the following set up steps (first
40+
time only).
41+
42+
1. Clone the [Dart SDK](https://github.com/dart-lang/sdk) fron GitHub.
43+
2. The `LOCAL_DART_SDK` environment variable needs to point to this path:
44+
`export LOCAL_DART_SDK=/path/to/dart/sdk`
45+
46+
If you are also developing server side code (e.g. the `devtools_shared`
47+
package), you will need to modify the `devtools_shared` dependency override in
48+
`sdk/pubspec.yaml` to point to your local `devtools_shared` package:
49+
50+
```yaml
51+
dependency_overrides:
52+
devtools_shared:
53+
path: /path/to/devtools/packages/devtools_shared
54+
```
55+
56+
Then you can run DevTools with the server by running the following from
57+
anywhere under the `devtools/` directory:
58+
59+
1. To run the DevTools web app in release mode, served with the DevTools server
60+
(this emulates the production environment):
61+
62+
```
63+
dt serve
64+
```
65+
66+
2. To run the DevTools web app in debug mode, with full debugging support, and
67+
with a connection to a live DevTools server:
68+
69+
```sh
70+
dt run
71+
```
72+
73+
Option 2 is useful for a quicker development cycle. The DevTools build time
74+
will be faster, and you will be able to connect the DevTools web app to an IDE
75+
or another DevTools instance for debugging purposes.
76+
77+
To see the full list of arguments available for either command, please pass the
78+
`-h` flag.
79+
80+
## IDE-embedded DevTools experience
81+
82+
### DevTools + VS Code integration
83+
84+
To test the integration with VS Code, you can set up the Dart VS Code extension
85+
to run DevTools and the server from your local source code. Follow the
86+
[Frontend + DevTools server](#frontend--devtools-server) setup instructions
87+
above.
88+
89+
Open your VS Code settings (Run the
90+
**Preferences: Open User Settings (JSON)** command from the command palette
91+
(`F1`)) and add the following to your settings:
92+
93+
```js
94+
"dart.customDevTools": {
95+
"path": "/absolute/path/to/devtools/repo",
96+
"env": {
97+
"LOCAL_DART_SDK": "/absolute/path/to/sdk",
98+
// Path to the Flutter SDK that will be used to build DevTools. This may
99+
// be the path to the included Flutter SDK under the tool/ directory or
100+
// the path to your local Flutter SDK git checkout.
101+
"FLUTTER_ROOT": "/absolute/path/to/devtools/tool/flutter-sdk"
102+
},
103+
"args": [
104+
// Arguments that will be passed along to the `dt serve` command.
105+
],
106+
},
107+
```
108+
109+
This instructs VS Code to run the `dt serve` command instead of running `dart
110+
devtools`. You must set the `LOCAL_DART_SDK` and `FLUTTER_ROOT` env variables
111+
correctly for the script to work.
112+
113+
Next, restart VS Code (or run the **Developer: Reload Window** command from the
114+
command palette (`F1`)) and DevTools will be run from your local source code.
115+
116+
> Note: After making any code changes to DevTools or the server, you will need
117+
> to re-run the **Developer: Reload Window** command to rebuild and restart the
118+
> server.
119+
120+
### Print-debugging
121+
122+
In order to use and see `print()` calls, open VS Code's own Developer Tools via
123+
the **Developer: Toggle Developer Tools** command from the command palette
124+
(`F1`). `print()` calls are outputted to this Developer Tools panel, in the
125+
**Console** screen.
126+
127+
### DevTools + IntelliJ integration
128+
129+
Follow instructions in the Flutter-IntelliJ repo's `CONTRIBUTING` guide:
130+
[#developing-with-local-devtools](https://github.com/flutter/flutter-intellij/blob/master/CONTRIBUTING.md#developing-with-local-devtools)
131+
132+
## Connect DevTools to a test application
133+
134+
For working on most DevTools tools, a connection to a running Dart or Flutter
135+
app is required. Run any Dart or Flutter app of your choice to connect it to
136+
DevTools. Consider running
137+
[veggieseasons](https://github.com/flutter/samples/tree/main/veggieseasons) or
138+
another Flutter sample since those apps have plenty of interesting code to
139+
debug.
140+
141+
1. Run your Dart or Flutter app.
142+
> Note: some DevTools features may be unavailable depending on the test app
143+
> platform (Flutter native, Flutter web, Dart CLI, etc.) or run mode (debug,
144+
> profile) you choose.
145+
2. Copy the URI printed to the command line (you will use this URI to connect to
146+
DevTools).
147+
148+
```
149+
"A Dart VM Service on iPhone 14 Pro Max is available at: <copy-this-uri>"
150+
```
151+
3. Paste this URI into the connect dialog in DevTools and click "Connect".
152+
153+
![Connect dialog example](_markdown_images/connect_dialog_example.png)
154+
155+
## Running DevTools on Flutter Desktop
156+
157+
For a faster development cycle with hot reload, you can run DevTools on Flutter
158+
desktop. Some DevTools features only work on the web, like the embedded
159+
Perfetto trace viewer, DevTools extensions, or WASM support, but the
160+
limitations on the desktop app are few.
161+
162+
To run DevTools with the desktop embedder on MacOS, you can run `flutter run -d
163+
macos` from `devtools/packages/devtools_app`, or you can run DevTools from your
164+
IDE with the `macOS` device selected.
165+
166+
If this fails, you may need to run `flutter create .` from
167+
`devtools/packages/devtools_app` to generate the updated files for your
168+
platform. If you want to run DevTools on Flutter desktop for Windows or Linux,
169+
you will need to generate the files for this platform using the
170+
`flutter create .` command, and then run using
171+
`flutter run -d <windows or linux>`.

0 commit comments

Comments
 (0)