Using the Fuchsia extension for VS Code

This extension adds support for working with Fuchsia targets and source code, including:

• Connecting to a device.
• Debugging C++ and Rust code (supported by zxdb).
• Analyzing logs from Fuchsia devices.

Compatibility

The Fuchsia extension is compatible with ffx 9.20220803.3.1 and forward.

Edit code

By default, VS code provides syntax highlighting, errors and warnings, jumping to a definition, and lists references for C++.

VS Code actively analyzes your code in the background and can show you various warnings or errors. For more information, see Errors and warnings.

The Fuchsia extension also provides syntax highlighting for FIDL and CML.

Configure and build Fuchsia

Set your Fuchsia build configuration through the command palette and select Fuchsia: fx set.

You can select products and boards available from a dropdown list. The extension displays a message when fx set finishes running.

To build Fuchsia through the command palette, select Fuchsia: fx build. The extension displays a progress bar while the build is in progress.

Connect to a Fuchsia device

The Fuchsia extension allows you to connect to a Fuchsia target which can be a physical device or an emulator. The extension supports multiple target devices and allows you to easily switch between various Fuchsia devices. You can only connect to a single device at any given time.

If your emulator is properly configured and started, you should see a computer and the name of your Fuchsia device in the status bar of VS Code. If you are using the emulator and not seeing a Fuchsia device, see Start the Fuchsia emulator.

Options for a Fuchsia device

You can click the computer and the name of your Fuchsia device in the status bar of VS Code to see the various options that you have for your Fuchsia devices. These options display in the VS Code command palette. In most cases, you have the following options:

• Default target: <device-name>: This option shows which Fuchsia device is currently configured as your default target. If you have additional Fuchsia devices, click the Set <device-name> as default to connect to that specific device. This is equivalent to running ffx target default get.
• Set <device-name> as default: This options lets you connect to the selected Fuchsia device. This is equivalent to running ffx target default set <device-name>.
• Show log for <device-name>: This option opens the Fuchsia logs tab of the Fuchsia extension. For more information, see View Fuchsia logs. This is equivalent to running ffx log.
• Reboot <device-name>: This options restarts your Fuchsia device. This is equivalent to running ffx target reboot.
• Power off <device-name>: This option powers off your Fuchsia device. This is equivalent to running ffx target off. If you power off a Fuchsia emulator, you need to use ffx emu start <product-bundle> to start the emulator again. For more information, see Start the Fuchsia emulator.

View Fuchsia logs

The Fuchsia extension allows you to view the symbolized logs (human-readable stack traces) for your connected Fuchsia device. This is equivalent to running ffx log. For more information on ffx log, see Monitor device logs.

Select Fuchsia logs from the drop-down in the Output tab to see the following:

Clearing the Fuchsia logs

Once the Fuchsia extension has streamed the Fuchsia logs, you can clear the listed Fuchsia logs to see the incoming logging events for your Fuchsia device.

To clear the Fuchsia logs, click the playlist_remove in the top right corner of the Fuchsia logs tab.

Auto-scrolling Fuchsia logs

To toggle auto-scroll for Fuchsia logs, click the lock in the top right corner of the Fuchsia logs tab.

Debug code

The Fuchsia extension allows you to run the Fuchsia debugger, zxdb. This integrates the zxdb debugger into the VS Code IDE to let you set break points and other debugger settings as you are working with source code.

Configure a profile

Before you start using the debug console, you need to create a debugging profile. You can create several debugging profiles and then easily toggle between each profile.

To create a debugging profile:

1. In VS Code, open Run and Debug (this option is in the left side-bar and has a play and bug icon).

   

2. From the Run and Debug: Run panel, click Show all automatic debug configurations. Then, from the command palette, select Add Config (fuchsia). The editor will open a launch.json file.

3. The editor should display a list of prepopulated debugging profiles, select any of the profiles that start with zxdb.

   Modify the key/values as needed for your debugging profile. Before you edit the profile, consider the following:

   • name: Specify a meaningful identifier for the profile.
   • type: Specify zxdb. This is the only Fuchsia debugger.
   • request: Specify launch. This is the only valid option.
   • launchcommand: Specify the alias or path to the ffx binary and append any options and parameters. In most cases, this will be a ffx component run ..... For more information, see Run components.
   • process: Specify the name of the component that you are debugging.

4. Once you have added the values for your profile, launch.json should look similar to the following:

      {
        "configurations": [
        {
         # Specify a meaningful identifier.
         "name": "Debug examples",
         # This is a fixed required value.
         "type": "zxdb",
         # This is a fixed required value.
         "request": "launch",
         # Specify the desired launchcommand.
         "launchCommand": "tools/ffx component run /core/ffx-laboratory:hello_world fuchsia-pkg://fuchsiasamples.com/hello_world#meta/hello_world.cm --recreate",
         # Specify the process that you want to debug.
         "process": "hello_world"
       }
       ]
     }
     ```
   

5. Save the changes that you made to the launch.json file.

You have successfully created a debugging profile. You can repeat the instructions to add additional profiles.

Run and debug

Once you have created a debugging profile, you can use your profile to run and debug a component that you are working on.

To start the debugger:

1. In VS Code, open Run and Debug (this option is in the left side-bar and has a play and bug icon).

2. From the Run and Debug: Run panel, use the drop-down list to select your debugging profile. Then, click the green play_arrow to the left of the drop-down list to start the debugging session.

   

Once you have started the debugger:

• You can use the Debug console tab to run zxdb commands. For more information on zxdb console commands, see Zxdb console commands and interaction model.
• You can use the VS Code debugger features to perform debugging actions, add breakpoints, logpoints, etc... For more information, see Debug actions.

Fuchsia component explorer

The Fuchsia extension provides a tree view of components on your Fuchsia device. This is the equivalent of running ffx component list.

To view the Fuchsia component list, open Run and Debug (this option is in the left side-bar and has a play and bug icon) and expand the Fuchsia Components section.

Component details

Hover over a component in the Fuchsia component list, that displays a pop-up with the lifecycle information for that component.

To view details of a component, click the component name in the Fuchsia component list. This opens a new window with details of the component and is the equivalent of running ffx component show <component-name>.

Debug a component

To debug a component, click the bug_report to the right of the component name.

Fuchsia task explorer

The Fuchsia extension provides a tree view of all jobs, processes, and threads running in the Fuchsia system. To view the Fuchsia task explorer, open Run and Debug (this option is in the left side-bar and has a play and bug icon) and expand the Fuchsia Jobs, Processes, and Threads section.

To attach a debugger to a task, click the bug_report to the right of the process.