docs/development/tools/ffx/workflows/start-a-component-during-development.md

# Start a component during development

For testing and debugging purposes, the
[`ffx component`][ffx-component] commands can quickly
start a [dynamic component instance][dynamic-children] on a device.

## Concepts

Component instances on a device are usually declared using
[component manifests][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][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`][ffx-laboratory] is one of those predefined
collections.

## Start a component {:#start-a-component}

To create a new dynamic component instance, you first need to run
[`ffx component create`][ffx-component-create] to add a new component
to the component instance tree on a device. Once added,
you can run [`ffx component start`][ffx-component-start] to start the component
on the device.

To start a new dynamic component instance on a device, do the following:

1. Create a new component instance:

   ```posix-terminal
   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`:

   ```none {:.devsite-disable-click-to-copy}
   $ 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](#destroy-a-component).

2. Start the component instance:

   ```posixe-terminal
   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`:

   ```none {:.devsite-disable-click-to-copy}
   $ 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](#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](#start-a-component)). However,
the [`ffx component run`][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:

```posix-terminal
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:

```none {:.devsite-disable-click-to-copy}
$ 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:

1. Run `ffx component create` to create a new component instance under the
   `ffx-laboratory` collection using the component name as the target moniker.
2. 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:

```none {:.devsite-disable-click-to-copy}
$ 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 {:#stop-a-component}

To stop a running component instance on a device, run the following command:

```posix-terminal
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`:

```none {:.devsite-disable-click-to-copy}
$ ffx component stop /core/ffx-laboratory:hello-world
Moniker: /core/ffx-laboratory:hello-world
Stopping component instance...
```

## Destroy a component {:#destroy-a-component}

To remove a dynamic component instance from the component instance tree
on a device, run the following command:

```posix-terminal
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`:

```none {:.devsite-disable-click-to-copy}
$ ffx component destroy /core/ffx-laboratory:hello-world
Moniker: /core/ffx-laboratory:hello-world
Destroying component instance...
```


<!-- Reference links -->

[dynamic-children]: /docs/concepts/components/v2/realms.md#dynamic-children
[component-manifests]: /docs/concepts/components/v2/component_manifests.md
[component-collection]: /docs/concepts/components/v2/realms.md#collections
[ffx-component-run]: https://fuchsia.dev/reference/tools/sdk/ffx#run
[ffx-laboratory]: /docs/development/components/run.md#ffx-laboratory
[ffx-component]: https://fuchsia.dev/reference/tools/sdk/ffx#component
[component-lifecycle]: /docs/concepts/components/v2/lifecycle.md
[ffx-component-create]: https://fuchsia.dev/reference/tools/sdk/ffx#create_2
[ffx-component-start]: https://fuchsia.dev/reference/tools/sdk/ffx#start