# zxdb: The Fuchsia debugger

Zxdb is a console-mode debugger for native code running on Fuchsia.

It primarily supports C, C++ and Rust code, but any language that compiles
natively and exports DWARF symbols should work to some extent.

Interpreted code such as Dart and JavaScript is not supported.

## Run zxdb

There are several ways to attach `zxdb` to a component through
`ffx component debug`:

> [!NOTE]
> **Note:** If you have any issues with launching `zxdb`, see [Troubleshooting](https://fuchsia.dev/docs/development/debugger/troubleshooting).

    ffx component debug component-identifier

For example, this command attaches to the component called `cobalt.cm`:

    ffx component debug cobalt.cm

This shows an output like:

    Waiting for process matching "job 20905".
    Type "filter" to see the current filters.
    👉 To get started, try "status" or "help".
    Attached Process 1 state=Running koid=21057 name=cobalt.cm component=cobalt.cm
    Loading 15 modules for cobalt.cm ...Done.
    [zxdb]

> [!NOTE]
> **Note:** For more information about component identifiers, see [component identifiers](https://fuchsia.dev/docs/concepts/components/v2/identifiers).

You can also use other types of component identifiers such as a component
moniker.

For example, this example attaches to the `core/cobalt` component moniker:

> [!NOTE]
> **Note:** For more information about component monikers, see [monikers](https://fuchsia.dev/docs/concepts/components/v2/identifiers#monikers).

    ffx component debug core/cobalt

Additionally, you can also use shorter component identifiers, such
as `cobalt`:

    ffx component debug cobalt

However, if `zxdb` can't figure out which component you are referring
to, you may see an output like:

    The query "cobalt" matches more than one component instance:
    core/cobalt
    core/cobalt_system_metrics

    To avoid ambiguity, use one of the above monikers instead.

In this case make sure to be specific as to which component you want `zxdb` to
attach to.

### Using a Fuchsia package URL

You can also use the full Fuchsia package URL:

> [!NOTE]
> **Note:** For more information about Fuchsia package URLs, see [component URLs](https://fuchsia.dev/docs/reference/components/url).

    ffx component debug fuchsia-pkg://fuchsia.com/cobalt#meta/cobalt.cm

This shows an output like:

    Waiting for process matching "job 20905".
    Type "filter" to see the current filters.
    👉 To get started, try "status" or "help".
    Attached Process 1 state=Running koid=21057 name=cobalt.cm component=cobalt.cm
    Loading 15 modules for cobalt.cm ...Done.
    [zxdb]

### See available components

You can see a full list of available components:

    ffx component list

You should see an output like:

    ...
    bootstrap
    bootstrap/archivist
    bootstrap/archivist/archivist-pipelines
    ...
    core/brightness_manager
    core/build-info
    core/cobalt
    ...

## Working with zxdb

Once you have successfully connected to the `zxdb` debugger, you may want to:

- [Get started with zxdb](https://fuchsia.dev/docs/development/debugger/commands)
- [Use breakpoints](https://fuchsia.dev/docs/development/debugger/breakpoints)
- [Debug tests using zxdb](https://fuchsia.dev/docs/development/debugger/tests)
- [Control thread execution](https://fuchsia.dev/docs/development/debugger/execution) (pausing, stepping, and resuming)
- [Evaluate expressions](https://fuchsia.dev/docs/development/debugger/expressions)
- [Inspect memory](https://fuchsia.dev/docs/development/debugger/memory)
- [List handles and kernel objects](https://fuchsia.dev/docs/development/debugger/kernel_objects)
- [Work with assembly language](https://fuchsia.dev/docs/development/debugger/assembly)
- [Look at handles](https://fuchsia.dev/docs/development/debugger/kernel_objects)
- [Understand how symbols are loaded](https://fuchsia.dev/docs/development/debugger/symbols)
- [Work with exceptions](https://fuchsia.dev/docs/development/debugger/exceptions)
- [See advanced zxdb topics](https://fuchsia.dev/docs/development/debugger/advanced)

You can also follow the zxdb tutorials:

- [Tutorial: Debug tests using zxdb](https://fuchsia.dev/docs/development/debugger/tutorial-tests)
- [Tutorial: Debug with minidumps using zxdb](https://fuchsia.dev/docs/development/debugger/tutorial-minidumps)

Additionally, if you are interested in contributing to zxdb:

- [Developing and debugging zxdb](https://fuchsia.dev/docs/development/debugger/developing)

[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/development/debugger/README.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/development/debugger/README.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/development/debugger/README.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/development/debugger/README.md "Edit the source code of this page")