| # 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: |
| |
|  |
| |
| 3. Make sure the target for the Fuchsia extension is set to |
| `fuchsia-emulator`. |
| |
|  |
| |
| ### 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. |
| |
|  |
| |
| 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. |