Component manifest (.cml) reference

A .cml file contains a single json5 object literal with the keys below.

Where string values are expected, a list of valid values is generally documented. The following string value types are reused and must follow specific rules.

String types

Names

Both capabilities and a component's children are named. A name string must consist of one or more of the following characters: a-z, 0-9, _, ., -.

References

A reference string takes the form of #<name>, where <name> refers to the name of a child:

A static child instance whose name is <name>, or
A collection whose name is <name>.

Top-level keys

`include`

array of strings (optional)

The optional include property describes zero or more other component manifest files to be merged into this component manifest. For example:

include: [ "//src/lib/syslog/client.shard.cml" ]

In the example given above, the component manifest is including contents from a manifest shard provided by the syslog library, thus ensuring that the component functions correctly at runtime if it attempts to write to syslog. By convention such files are called "manifest shards" and end with .shard.cml.

If working in fuchsia.git, include paths are relative to the source root of the Fuchsia tree.

You can review the outcome of merging any and all includes into a component manifest file by invoking the following command:

fx cmc include cmx_file --includeroot $FUCHSIA_DIR --includepath $FUCHSIA_DIR/sdk/lib

Includes can be recursive, meaning that shards can have their own includes.

`program`

object (optional)

Components that are executable include a program section. The program section must set the runner property to select a runner to run the component. The format of the rest of the program section is determined by that particular runner.

ELF runners

If the component uses the ELF runner, program must include the following properties, at a minimum:

runner: must be set to "elf"
binary: Package-relative path to the executable binary
args (optional): List of arguments

Example:

program: {
    runner: "elf",
    binary: "bin/hippo",
    args: [ "Hello", "hippos!" ],
},

For a complete list of properties, see: ELF Runner

Other runners

If a component uses a custom runner, values inside the program stanza other than runner are specific to the runner. The runner receives the arguments as a dictionary of key and value pairs. Refer to the specific runner being used to determine what keys it expects to receive, and how it interprets them.

`children`

array of objects (optional)

The children section declares child component instances as described in Child component instances.

Keys:

name: The name of the child component instance, which is a string of one or more of the following characters: a-z, 0-9, _, ., -. The name identifies this component when used in a reference.
url: The component URL for the child component instance.
startup (optional): The component instance's startup mode.
- lazy (default): Start the component instance only if another component instance binds to it.
- eager: Start the component instance as soon as its parent starts.
environment (optional): If present, the name of the environment to be assigned to the child component instance, one of environments. If omitted, the child will inherit the same environment assigned to this component.
on_terminate (optional): Determines the fault recovery policy to apply if this component terminates.
- none (default): Do nothing.
- reboot: Gracefully reboot the system if the component terminates for any reason. This is a special feature for use only by a narrow set of components; see Termination policies for more information.

Example:

children: [
    {
        name: "logger",
        url: "fuchsia-pkg://fuchsia.com/logger#logger.cm",
    },
    {
        name: "pkg_cache",
        url: "fuchsia-pkg://fuchsia.com/pkg_cache#meta/pkg_cache.cm",
        startup: "eager",
    },
    {
        name: "child",
        url: "#meta/child.cm",
    }
],

`collections`

array of objects (optional)

The collections section declares collections as described in Component collections.

Keys:

name: The name of the component collection, which is a string of one or more of the following characters: a-z, 0-9, _, ., -. The name identifies this collection when used in a reference.
durability: The duration of child component instances in the collection.
- transient: The instance exists until its parent is stopped or it is explicitly destroyed.
- single_run: The instance is started when it is created, and destroyed when it is stopped.
environment (optional): If present, the environment that will be assigned to instances in this collection, one of environments. If omitted, instances in this collection will inherit the same environment assigned to this component.

Example:

collections: [
    {
        name: "tests",
        durability: "transient",
    },
],

`environments`

array of objects (optional)

The environments section declares environments as described in Environments.

Keys:

name: The name of the environment, which is a string of one or more of the following characters: a-z, 0-9, _, ., -. The name identifies this environment when used in a reference.
extend: How the environment should extend this realm's environment.
- realm: Inherit all properties from this compenent's environment.
- none: Start with an empty environment, do not inherit anything.
runners: The runners registered in the environment. An array of objects with the following properties:
- runner: The name of a runner capability, whose source is specified in from.
- from: The source of the runner capability, one of:
  - parent: The component's parent.
  - self: This component.
  - #<child-name>: A reference to a child component instance.
- as (option): An explicit name for the runner as it will be known in this environment. If omitted, defaults to runner.
resolvers: The resolvers registered in the environment. An array of objects with the following properties:
- resolver: The name of a resolver capability, whose source is specified in from.
- from: The source of the resolver capability, one of:
  - parent: The component's parent.
  - self: This component.
  - #<child-name>: A reference to a child component instance.
- scheme: The URL scheme for which the resolver should handle resolution.

Example:

environments: [
    {
        name: "test-env",
        extend: "realm",
        runners: [
            {
                runner: "gtest-runner",
                from: "#gtest",
            },
        ],
        resolvers: [
            {
                resolver: "universe-resolver",
                from: "parent",
                scheme: "fuchsia-pkg",
            },
        ],
    },
],

`capabilities`

array of objects (optional)

The capabilities section defines capabilities that are provided by this component. Capabilities that are offered or exposed from self must be declared here.

These capabilities often map to a node in the outgoing directory.

Each entry in capabilities must conform to one of the following schemas:

protocol
directory
storage
runner
resolver

protocol

A definition of a protocol capability.

protocol: The name for this protocol capability, or an array of names to define multiple protocols.
path (optional): The path in the component's outgoing directory from which this protocol is served. Only supported when protocol is a single name. Defaults to /svc/${protocol}.

storage

A definition of a storage capability.

storage: The name for this storage capability.
from: The source of the existing directory capability backing this storage capability, one of:
- parent: The component's parent.
- self: This component.
- #<child-name>: A reference to a child component instance.
backing_dir: The name of the directory backing the storage.
subdir: The subdirectory within backing_dir where per-component isolated storage directories are created.
storage_id: The identifier used to isolated storage for a component, one of:
- static_instance_id: The instance ID in the component ID index is used as the key for a component's storage. Components which are not listed in the component ID index will not be able to use this storage capability.
- static_instance_id_or_moniker: If the component is listed in the component ID index, the instance ID is used as the key for a component's storage. Otherwise, the component's relative moniker from the storage capability is used.

runner

A definition of a runner capability.

runner: The name for this runner capability.
path: The path in the component's outgoing directory from which the fuchsia.component.runner.ComponentRunner protocol is served.

resolver

A definition of a resolver capability.

resolver: The name for this resolver capability.
path: The path in the component's outgoing directory from which the fuchsia.sys2.ComponentResolver protocol is served.

`use`

array of objects (optional)

For executable components, declares capabilities that this component requires in its namespace at runtime. Capabilities are routed from the parent unless otherwise specified, and each capability must have a valid route through all components between this component and the capability's source.

Keys:

A capability declaration, one of:
- protocol: The name of a protocol capability, or an array of names of protocol capabilities.
- directory: The name of a directory capability.
- storage: The name of a storage capability.
from (optional): The source of the capability. Defaults to parent. One of:
- parent: The component's parent.
- debug: One of debug_capabilities in the environment assigned to this component.
- framework: The Component Framework runtime.
- #<capability-name>: The name of another capability from which the requested capability is derived.
- #<child-name>: A reference to a child component instance.
path (optional): The path at which to install the capability in the component's namespace. For protocols, defaults to /svc/${protocol}. Required for directory and storage. This property is disallowed for declarations with capability arrays.

Example:

use: [
    {
        protocol: [
            "fuchsia.ui.scenic.Scenic",
            "fuchsia.accessibility.Manager",
        ]
    },
    {
        directory: "themes",
        path: "/data/themes",
        rights: [ "r*" ],
    },
    {
        storage: "persistent",
        path: "/data",
    },
],

`expose`

array of objects (optional)

Declares the capabilities that are made available to the parent component or to the framework. It is valid to expose from self or from a child component.

Keys:

A capability name or array of names, keyed to one of the following typenames:
- protocol
- directory
- runner
- resolver
from: The source of the capability, one of:
- self: This component. Requires a corresponding capability declaration.
- framework: The Component Framework runtime.
- #<child-name>: A reference to a child component instance.
to (optional): The capability target. Either parent or framework. Defaults to parent.
as (optional): The name for the capability as it will be known by the target. If omitted, defaults to the original name. This property cannot be used when protocol is an array of multiple items. as cannot be used when an array of multiple names is provided.

Example:

expose: [
    {
        directory: "themes",
        from: "self",
    },
    {
        protocol: "pkg.Cache",
        from: "#pkg_cache",
        as: "fuchsia.pkg.PackageCache",
    },
    {
        protocol: [
            "fuchsia.ui.app.ViewProvider",
            "fuchsia.fonts.Provider",
        ],
        from: "self",
    },
    {
        runner: "web-chromium",
        from: "#web_runner",
        as: "web",
    },
    {
        resolver: "universe-resolver",
        from: "#universe_resolver",
    },
],

`offer`

array of objects (optional)

Declares the capabilities that are made available to a child component instance or a child collection.

Keys:

A capability name or array of names, keyed to one of the following typenames:
- protocol
- directory
- storage
- runner
- resolver
from: The source of the capability, one of:
- parent: The component's parent. This source can be used for all capability types.
- self: This component. Requires a corresponding capability declaration.
- framework: The Component Framework runtime.
- #<child-name>: A reference to a child component instance. This source can only be used when offering protocol, directory, or runner capabilities.
to: A capability target or array of targets, each of which is a reference to the child or collection to which the capability is being offered, of the form #<target-name>.
as (optional): An explicit name for the capability as it will be known by the target. If omitted, defaults to the original name. as cannot be used when an array of multiple names is provided.
dependency (optional): The type of dependency between the source and targets, one of:
- strong: a strong dependency, which is used to determine shutdown ordering. Component manager is guaranteed to stop the target before the source. This is the default.
- weak_for_migration: a weak dependency, which is ignored during shutdown. When component manager stops the parent realm, the source may stop before the clients. Clients of weak dependencies must be able to handle these dependencies becoming unavailable. This type exists to keep track of weak dependencies that resulted from migrations into v2 components.

Example:

offer: [
    {
        protocol: "fuchsia.logger.LogSink",
        from: "#logger",
        to: [ "#fshost", "#pkg_cache" ],
        dependency: "weak_for_migration",
    },
    {
        protocol: [
            "fuchsia.ui.app.ViewProvider",
            "fuchsia.fonts.Provider",
        ],
        from: "#session",
        to: [ "#ui_shell" ],
        dependency: "strong",
    },
    {
        directory: "blobfs",
        from: "self",
        to: [ "#pkg_cache" ],
    },
    {
        directory: "fshost-config",
        from: "parent",
        to: [ "#fshost" ],
        as: "config",
    },
    {
        storage: "cache",
        from: "parent",
        to: [ "#logger" ],
    },
    {
        runner: "web",
        from: "parent",
        to: [ "#user-shell" ],
    },
    {
        resolver: "universe-resolver",
        from: "parent",
        to: [ "#user-shell" ],
    },
],

`facets`

object (optional)

Contains metadata that components may interpret for their own purposes. The component framework enforces no schema for this section, but third parties may expect their facets to adhere to a particular schema.

`config`

object (optional)

A JSON object containing all configuration fields for this component. Each field must have a key and a value type.

Example:

config: {
    debug_mode: {
        type: "bool"
    },
    tags: {
        type: "vector",
        max_count: 10,
        element: {
            type: "string",
            max_size: 20
        }
    }
}

TODO(87560): Write detailed syntax for the config section