Google is committed to advancing racial equity for Black communities. See how.

Run components

This document demonstrates how to add components directly to the component instance tree during development and interact with them at runtime.

Fuchsia provides a few abstractions on top of component framework for specific use cases. If you are building components using one of the following frameworks, refer to the corresponding guides instead:

Concepts

You should understand the following concepts before running a component:

  • At runtime, the component instance tree connects individual component instances together in a hierarchy of parent and child relationships.
  • Component instances progress through four major lifecycle states: create, start, stop, and destroy.
  • A component moniker identifies component instances within the tree using their topological path.
  • Component instances are declared statically as a child of another component in their component manifest or created dynamically at runtime in a component collection. Each instance consists of a component name and url.
  • A component URL identifies a component. Component URLs are resolved by the component framework, often to a resource inside a package.

For more details on component execution, see Component lifecycle.

Component instances

The first step to running a component is adding a new component instance to the tree. The position of the component instance within the tree determines its available capabilities .

Discover static components

Static components are declared as children of another component instance in the tree. You can use ffx component show to determine the moniker and component URL of a static component instance:

ffx component show COMPONENT_NAME

Replace COMPONENT_NAME with the name of a component. The following example shows the command output for the pkg-resolver component:

$ ffx component show pkg-resolver
Moniker: /core/pkg-resolver
URL: fuchsia-pkg://fuchsia.com/pkg-resolver#meta/pkg-resolver.cm
Type: CML static component
Component State: Resolved
Execution State: Running
...

Static component instances cannot be created or destroyed at runtime.

Manage dynamic components

Dynamic components are created at runtime inside of a collection. You can use ffx component create to create a new component instance, providing a target moniker within an existing collection and a component URL for resolving the component:

ffx component create TARGET_MONIKER COMPONENT_URL

Replace TARGET_MONIKER with the destination moniker of the new component inside an existing collection and COMPONENT_URL with the location where the component is being served. For example, the following command creates a new component instance inside the ffx-laboratory collection named hello-world:

$ ffx component create /core/ffx-laboratory:hello-world fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world-rust.cm
URL: fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world-rust.cm
Moniker: /core/ffx-laboratory:hello-world
Creating component instance...

Similarly, use ffx component destroy to destroy a dynamic component instance by providing its moniker:

ffx component destroy TARGET_MONIKER

Replace TARGET_MONIKER with the moniker of the component to destroy. The following example destroys the hello-world component created above:

$ ffx component destroy /core/ffx-laboratory:hello-world
Moniker: /core/ffx-laboratory:hello-world
Destroying component instance...

Component execution

Once a component instance exists in the tree, you can start and stop the target instance using ffx component.

Bind to the instance

Use ffx component bind to explicitly bind to a component instance. This causes the instance to start if it is not already running:

ffx component bind TARGET_MONIKER

Replace TARGET_MONIKER with the moniker of the component to start. The following example binds to the hello-world component created previously:

$ ffx component bind /core/ffx-laboratory:hello-world
Moniker: /core/ffx-laboratory:hello-world
Binding to component instance...

Stop the instance

Use ffx component stop to terminate execution of a running component instance using its moniker:

ffx component stop TARGET_MONIKER

Replace TARGET_MONIKER with the moniker of the component to stop. The following example stops to the hello-world component started above:

$ ffx component stop /core/ffx-laboratory:hello-world
Moniker: /core/ffx-laboratory:hello-world
Stopping component instance...

Run a component

The ffx component run command provides a quickstart to run basic components during development:

ffx component run COMPONENT_URL

Replace COMPONENT_URL with the location where the component is being served. The following example creates a component instance using the hello-world-rust component:

$ ffx component run fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world-rust.cm
URL: fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world-rust.cm
Moniker: /core/ffx-laboratory:hello-world-rust
Creating component instance...
Binding to component instance...

The ffx component run command automates the following steps:

  1. Create a new component instance in the ffx-laboratory collection, using the component name as the target moniker.
  2. Bind to the new instance to begin execution.

The example above is equivalent to running the following individual ffx commands:

$ ffx component create /core/ffx-laboratory:hello-world-rust fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world-rust.cm
$ ffx component bind /core/ffx-laboratory:hello-world-rust

ffx-laboratory

The ffx-laboratory is a component collection that provides a restricted set of capabilities for development. The following capabilities are offered to components in this collection:

The ffx-laboratory is a transient collection. Component instances in this collection will persist even after they stop. To destroy a component instance in this collection, use the ffx component destroy command.

Troubleshooting

This section contains common issues you may encounter while running your components during development.

Unable to resolve the component

When using ffx component create or ffx component run you may encounter the following error if component framework cannot resolve the component instance:

$ ffx component run fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world.cm
URL: fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world.cm
Moniker: /core/ffx-laboratory:hello-world
Creating component instance...
Binding to component instance...
Lifecycle protocol could not bind to component instance: InstanceCannotResolve

This occurs when the component URL does not resolve to a valid component manifest.

To address this issue, verify the following:

Component instance already exists

When using ffx component create or ffx component run you may encounter the following error if the component instance already exists:

$ ffx component run fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world.cm
URL: fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world.cm
Moniker: /core/ffx-laboratory:hello-world
Creating component instance...
Component instance already exists. Use --recreate to destroy and recreate a new instance, or --name to create a new instance with a different name.

This occurs when the target moniker is already in use by another component instance.

To address this issue, manually destroy the instance using the ffx component destroy command:

$ ffx component destroy /core/ffx-laboratory:hello-world
Moniker: /core/ffx-laboratory:hello-world
Destroying component instance...

If you are using ffx component run, add the --recreate flag to destroy the instance and recreate it:

$ ffx component run fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world.cm --recreate
URL: fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world.cm
Moniker: /core/ffx-laboratory:hello-world
Creating component instance...
Component instance already exists. Destroying...
Recreating component instance...
Binding to component instance...

Alternatively, add the --name flag to create a new instance with a different name:

$ ffx component run fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world.cm --name hello-world-2
URL: fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world.cm
Moniker: /core/ffx-laboratory:hello-world-2
Creating component instance...
Binding to component instance...