blob: 7cc08a9f07ce0b9ce23fdd17a9f7246cdb539061 [file] [log] [blame] [view]
# Debugging example components
There are two ways to attach a debugger to example components:
- [**From the command-line interface (CLI).**](#attaching-a-debugger-from-the-cli)
This is currently the most well-supported way.
- [**From VSCode.**](#attaching-a-debugger-from-vscode)
This works for attaching breakpoints and stepping
through the code but more advanced commands may not work (see
[known issues](https://bugs.fuchsia.dev/p/fuchsia/issues/list?q=component%3ADeveloperExperience%3EFuchsiaExtensionForVSCode%20zxdb&can=2)).
The Fuchsia debugger is called `zxdb`. Once attached, you can follow
[this reference](https://fuchsia.dev/fuchsia-src/development/debugger?hl=en)
for common `zxdb` workflows.
## Attaching a debugger from the CLI
1. Connect the debugger to your Fuchsia device, for example the emulator
started before
[running an example](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/README.md#run-an-example-app).
```sh
$FUCHSIA_EMBEDDER_DIR/tools/ffx debug connect
```
When successful, this should start a `[zxdb]` prompt.
2. From the `[zxdb]` prompt, attach to `embedder.cm` and add a
breakpoint to `main`:
```sh
[zxdb] attach embedder.cm
[zxdb] break main
```
3. In a separate terminal, run
[an example component](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/src/examples/README.md).
The debugger should detect the running component, attach to it and break on
the `main` function.
```sh
$FUCHSIA_EMBEDDER_DIR/scripts/build_and_run_example.sh hello_flutter
```
## Attaching a debugger from VSCode
### Requirements
1. Install the [Fuchsia VSCode extension](https://fuchsia.dev/fuchsia-src/reference/tools/editors/vscode/fuchsia-ext-install).
2. Set the "Ffx Path" setting for this extension to the output from
this command:
```sh
echo $FUCHSIA_EMBEDDER_DIR/tools/ffx
```
For example:
![ffx path configuration in vscode](images/ffx_path.png)
3. Make sure the target for the Fuchsia extension is set to
`fuchsia-emulator`.
![target set to fuchsia-emulator](images/sdk_connect_target.png)
### Running an example from VSCode
The examples can be run from VSCode's `Run and Debug` menu.
Breakpoints that are added to the code should be triggered.
![Running example from run and debug menu](images/run_example.png)
There are several options:
- *Example name*: Which of the [example components](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/src/examples) to run. Defaults to `hello_flutter`.
- *With Flutter Engine*: Builds using a custom Flutter Engine (requires setup from [_`making_engine_changes.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/making_engine_changes.md)). Default is off.
- *With Fuchsia*: Builds using a custom Fuchsia SDK and platform (requires setup from [_`testing_fuchsia_sdk_changes.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/testing_fuchsia_sdk_changes.md)). Default is off.
## Future improvements
- Document how to step into Fuchsia SDK code.
- Figure out how to step into Flutter Engine code.