For testing and debugging purposes, the
ffx component
commands can quickly
start a dynamic component instance on a device.
Concepts
Component instances on a device are usually declared using
component manifests, which statically define the topology
and capabilities of the components on the device. However, statically declaring
a component isn't the only way to create a component instance
on a device. You can also use the ffx component
commands to create a dynamic
component instance on the device at runtime.
One important difference is that Fuchsia restricts all dynamic component instances to run under a component collection. A collection serves as a container for dynamic component instances. Consequently, the capabilities of component instances under a collection are limited by the capabilities that the collection is able to expose and offer.
While a new component collection can be declared using a component manifest
(similar to declaring a static component instance), Fuchsia
provides a number of predefined collections for general usage.
For instance, ffx-laboratory
is one of those predefined
collections.
Start a component
To create a new dynamic component instance, you first need to run
ffx component create
to add a new component
to the component instance tree on a device. Once added,
you can run ffx component start
to start the component
on the device.
To start a new dynamic component instance on a device, do the following:
Create a new component instance:
ffx component create <TARGET_MONIKER> <COMPONENT_URL>
Replace the following:
TARGET_MONIKER
: The destination moniker of a new component instance. The moniker must include a component collection on the path.COMPONENT_URL
: The resource location of a component.
The example below creates a new component instance for the
hello-world-cpp.cm
component and assigns its moniker to be/core/ffx-laboratory:hello-world
:$ ffx component create /core/ffx-laboratory:hello-world fuchsia-pkg://fuchsia.com/hello-world-cpp#meta/hello-world-cpp.cm URL: fuchsia-pkg://fuchsia.com/hello-world-cpp#meta/hello-world-cpp.cm Moniker: /core/ffx-laboratory:hello-world Creating component instance...
Start the component instance:
ffx component start <TARGET_MONIKER>
Replace
TARGET_MONIKER
with the moniker used in Step 1.The example below starts the component instance at
/core/ffx-laboratory:hello-world
:$ ffx component start /core/ffx-laboratory:hello-world Moniker: /core/ffx-laboratory:hello-world Starting component instance...
Start a component under ffx-laboratory
Starting a dynamic component instance would normally require running a
sequence of the ffx component create
and ffx component start
commands
(see Start a component). However,
the ffx component run
command can start a dynamic
component instance in a single command line.
To quick start a component under the ffx-laboratory
collection,
run the following command:
ffx component run /core/ffx-laboratory:<NAME> <COMPONENT_URL>
Replace COMPONENT_URL
with the resource location of a component, and replace
NAME
with the name for the component instance within the ffx-laboratory
collection.
The example below starts the hello-world-cpp.cm
component on the device:
$ ffx component run /core/ffx-laboratory:hello-world-cpp fuchsia-pkg://fuchsia.com/hello-world-cpp#meta/hello-world-cpp.cm
URL: fuchsia-pkg://fuchsia.com/hello-world-cpp#meta/hello-world-cpp.cm
Moniker: /core/ffx-laboratory:hello-world-cpp
Creating component instance...
Starting component instance...
In essence, the ffx component run
command performs the following steps:
- Run
ffx component create
to create a new component instance under theffx-laboratory
collection using the component name as the target moniker. - Run
ffx component start
to start the component instance on the device.
For instance, running ffx component run /core/ffx-laboratory:hello-world-cpp fuchsia-pkg://fuchsia.com/hello-world-cpp#meta/hello-world-cpp.cm
in the example above is equivalent to running the following commands:
$ ffx component create /core/ffx-laboratory:hello-world-cpp fuchsia-pkg://fuchsia.com/hello-world-cpp#meta/hello-world-cpp.cm
$ ffx component start /core/ffx-laboratory:hello-world-cpp
Stop a component
To stop a running component instance on a device, run the following command:
ffx component stop <TARGET_MONIKER>
Replace TARGET_MONIKER
with the moniker of a component instance.
The example below stops the component instance at
/core/ffx-laboratory:hello-world
:
$ ffx component stop /core/ffx-laboratory:hello-world
Moniker: /core/ffx-laboratory:hello-world
Stopping component instance...
Destroy a component
To remove a dynamic component instance from the component instance tree on a device, run the following command:
ffx component destroy <TARGET_MONIKER>
Replace TARGET_MONIKER
with the moniker of a component instance.
The example below removes the component instance at
/core/ffx-laboratory:hello-world
:
$ ffx component destroy /core/ffx-laboratory:hello-world
Moniker: /core/ffx-laboratory:hello-world
Destroying component instance...