Start a component during development

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...
```
Note: To remove this component instance from the tree, see Destroy a component.
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...
```
Note: To stop this component instance, see Stop a component.

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