run.md

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][glossary.component-framework] for specific use cases. If you are building components using one of the following frameworks, refer to the corresponding guides instead:

• Session components: Building and running a session
• Test components: Run Fuchsia tests

Note: For more details on the commands described in this guide, see the ffx component reference.

Concepts {#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 {#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 {{ '<var label="component">COMPONENT_NAME</var>' }}

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
               {{ '<strong>' }}Moniker: /core/pkg-resolver{{ '</strong>' }}
                   {{ '<strong>' }}URL: fuchsia-pkg://fuchsia.com/pkg-resolver#meta/pkg-resolver.cm{{ '</strong>' }}
                  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 {{ '<var label="moniker">TARGET_MONIKER</var>' }} {{ '<var label="url">COMPONENT_URL</var>' }}

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 {{ '<var label="moniker">TARGET_MONIKER</var>' }}

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 {#execute}

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

Start the instance

Use ffx component start to explicitly start a component instance:

ffx component start {{ '<var label="moniker">TARGET_MONIKER</var>' }}

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

$ ffx component start /core/ffx-laboratory:hello-world
Moniker: /core/ffx-laboratory:hello-world
Starting component instance...

Stop the instance

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

ffx component stop {{ '<var label="moniker">TARGET_MONIKER</var>' }}

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...

Note: You can add the --recursive flag to stop all child components. For more details, see the ffx component reference.

Run a component {#run}

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

ffx component run {{ '<var label="url">COMPONENT_URL</var>' }}

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...
Starting 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. Start 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 start /core/ffx-laboratory:hello-world-rust

ffx-laboratory {#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:

• Protocol capabilities
  • fuchsia.logger.LogSink: Record log messages
  • fuchsia.process.Launcher: Create new processes
• Storage capabilities
  • tmp: Temporary storage (non-persistent)
  • data: Emulated persistent storage backed by /tmp
  • cache: Emulated cache storage backed by /tmp
• Directory capabilities
  • /dev: Device driver devfs provided by Driver Manager
  • /boot: Read-only bootfs provided by Component Manager

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 start 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...
Starting 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:

• The component URL is formatted correctly.
• You have a package server running.
• Your package server is registered with the target.
• Your component is published to the package server.

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...
Starting 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...
Starting component instance...