runners.md

Component Runners

<<../../_v2_banner.md>>

Component runners extend the component framework through an environment to provide a runtime for launching new component instances.

Component manager launches components by sending a request containing ComponentStartInfo to the appropriate runner using the fuchsia.component.runner.ComponentRunner protocol. The ComponentStartInfo contains details about the component's executable and its namespace. The runner manages the component's execution within the supported runtime.

After starting the component, component manager uses the fuchsia.component.runner.ComponentController protocol provided in the Start request to send execution actions to the runner, such as stopping the component. The runner chooses how to interpret these commands as appropriate to the component runtime.

Providing runner capabilities {#provide}

To provide a runner capability, a component must declare a runner capability, whose path designates a FIDL protocol implementing fuchsia.component.runner.ComponentRunner served from the component's outgoing directory.

{
    capabilities: [
        {
            runner: "web",
            path: "/svc/fuchsia.component.runner.ComponentRunner",
        },
    ],
}

Component manager sends ComponentRunner/Start requests to this protocol. Each request includes a ComponentController channel which the runner should serve to handle lifecycle events for the component.

Routing runner capabilities {#route}

Components route runner capabilities by exposing them to their parent and offering them to their children.

For more details on how the framework routes component capabilities, see capability routing.

Exposing {#expose}

Exposing a runner capability gives the component's parent access to that capability:

{
    expose: [
        {
            runner: "web",
            from: "self",
        },
    ],
}

You may optionally specify:

• as

Offering {#offer}

Offering a runner capability gives a child component access to that capability:

{
    offer: [
        {
            runner: "web",
            from: "self",
            to: [ "#child-a" ],
        },
    ],
}

You may optionally specify:

• as

Registering a component runner {#register}

Component runners are made available to components through their environment. To register a new runner within an environment, add a new entry to the runners section of the environments declaration:

environments: [
    {
        name: "my-environ",
        extends: "realm",
        runners: [
            {
                runner: "web",
                from: "parent",
            },
        ],
    },
]

You may optionally specify:

• as

For more details on how to apply environments to components, see the environments documentation.

Selecting a runner

A component specifies the appropriate runner for execution using the program section of its manifest. The program section designates the runner as well as any runner-specific options. The runner must be registered in the component's environment.

For example, a component which runs as a web page might have a program like the following:

program: {
    runner: "web",
    mode: "incognito",
},

When the component manager attempts to launch this component, it will send a request to the provider of the web runner to start it.

Renaming runners {#renaming}

You may expose, offer, or register the runner capability under a different name using the as parameter:

{
    expose: [
        {
            runner: "web",
            from: "#chromium",
            as: "web-chromium",
        },
    ],
}

Framework runners {#framework}

Component framework provides the following built-in component runners:

• ELF runner: Runs binaries compiled to the ELF file format.

{
    program: {
        runner: "elf",
        binary: "bin/example",
    },
}