Struct Document

pub struct Document {
    pub include: Option<Vec<String>>,
    pub program: Option<Program>,
    pub children: Option<Vec<Child>>,
    pub collections: Option<Vec<Collection>>,
    pub environments: Option<Vec<Environment>>,
    pub capabilities: Option<Vec<Capability>>,
    pub use: Option<Vec<Use>>,
    pub expose: Option<Vec<Expose>>,
    pub offer: Option<Vec<Offer>>,
    pub facets: Option<IndexMap<String, Value>>,
    pub config: Option<BTreeMap<ConfigKey, ConfigValueType>>,
}

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.

The .cml file is compiled into a FIDL wire format (.cm) file.

String types

Names {#names}

Both capabilities and a component’s children are named. A name string may consist of one or more of the following characters: A-Z, a-z, 0-9, _, ., -. It must not exceed 255 characters in length and may not start with . or -.

Paths {#paths}

Paths are sequences of names delimited by the / character. A path must not exceed 4095 characters in length. Throughout the document,

• Relative paths cannot start with the / character.
• Namespace and outgoing directory paths must start with the / character.

References {#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 {#document}

Fields

include: Option<Vec<String>>

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

include: [ "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.

Include paths prepended with // are relative to the source root of the Fuchsia checkout. However, include paths not prepended with //, as in the example above, are resolved from Fuchsia SDK libraries (//sdk/lib) that export component manifest shards.

For reference, inside the Fuchsia checkout these two include paths are equivalent:

• syslog/client.shard.cml
• //sdk/lib/syslog/client.shard.cml

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

Note: The fx command below is for developers working in a Fuchsia source checkout environment.

fx cmc include {{ "<var>" }}cml_file{{ "</var>" }} --includeroot $FUCHSIA_DIR --includepath $FUCHSIA_DIR/sdk/lib

Includes can cope with duplicate use, offer, expose, or capabilities declarations referencing the same capability, as long as the properties are the same. For example:

// my_component.cml
include: [ "syslog.client.shard.cml" ]
use: [
    {
        protocol: [
            "fuchsia.logger.LogSink",
            "fuchsia.posix.socket.Provider",
        ],
    },
],

// syslog.client.shard.cml
use: [
    { protocol: "fuchsia.logger.LogSink" },
],

In this example, the contents of the merged file will be the same as my_component.cml – fuchsia.logger.LogSink is deduped.

However, this would fail to compile:

// my_component.cml
include: [ "syslog.client.shard.cml" ]
use: [
    {
        protocol: "fuchsia.logger.LogSink",
        // properties for fuchsia.logger.LogSink don't match
        from: "#archivist",
    },
],

// syslog.client.shard.cml
use: [
    { protocol: "fuchsia.logger.LogSink" },
],

An exception to this constraint is the availability property. If two routing declarations are identical, and one availability is stronger than the other, the availability will be “promoted” to the stronger value (if availability is missing, it defaults to required). For example:

// my_component.cml
include: [ "syslog.client.shard.cml" ]
use: [
    {
        protocol: [
            "fuchsia.logger.LogSink",
            "fuchsia.posix.socket.Provider",
        ],
        availability: "optional",
    },
],

// syslog.client.shard.cml
use: [
    {
        protocol: "fuchsia.logger.LogSink"
        availability: "required",  // This is the default
    },
],

Becomes:

use: [
    {
        protocol: "fuchsia.posix.socket.Provider",
        availability: "optional",
    },
    {
        protocol: "fuchsia.logger.LogSink",
        availability: "required",
    },
],

Includes are transitive, meaning that shards can have their own includes.

Include paths can have diamond dependencies. For instance this is valid: A includes B, A includes C, B includes D, C includes D. In this case A will transitively include B, C, D.

Include paths cannot have cycles. For instance this is invalid: A includes B, B includes A. A cycle such as the above will result in a compile-time error.

program: Option<Program>

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 {#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 {#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: Option<Vec<Child>>

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

collections: Option<Vec<Collection>>

The collections section declares collections as described in [Component collections][doc-collections].

environments: Option<Vec<Environment>>

The environments section declares environments as described in Environments.

capabilities: Option<Vec<Capability>>

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

Capability fields

This supports the following capability keys. Exactly one of these must be set:

• protocol: (optional string or array of strings)
• service: (optional string or array of strings)
• directory: (optional string)
• storage: (optional string)
• runner: (optional string)
• resolver: (optional string)
• event_stream: (optional string or array of strings)
• dictionary: (optional string)
• config: (optional string)

Additional fields

This supports the following additional fields: [glossary.outgoing directory]: /docs/glossary/README.md#outgoing-directory

use: Option<Vec<Use>>

For executable components, declares capabilities that this component requires in its [namespace][glossary.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.

Capability fields

This supports the following capability keys. Exactly one of these must be set:

• service: (optional string or array of strings)
• directory: (optional string)
• protocol: (optional string or array of strings)
• dictionary: (optional string)
• storage: (optional string)
• event_stream: (optional string or array of strings)
• runner: (optional string)
• config: (optional string)

Additional fields

This supports the following additional fields: [glossary.namespace]: /docs/glossary/README.md#namespace

expose: Option<Vec<Expose>>

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.

Capability fields

This supports the following capability keys. Exactly one of these must be set:

• service: (optional string or array of strings)
• protocol: (optional string or array of strings)
• directory: (optional string)
• runner: (optional string)
• resolver: (optional string)
• dictionary: (optional string)
• config: (optional string)

Additional fields

This supports the following additional fields:

offer: Option<Vec<Offer>>

Declares the capabilities that are made available to a [child component][doc-children] instance or a [child collection][doc-collections].

Capability fields

This supports the following capability keys. Exactly one of these must be set:

• protocol: (optional string or array of strings)
• service: (optional string or array of strings)
• directory: (optional string)
• storage: (optional string)
• runner: (optional string)
• resolver: (optional string)
• event_stream: (optional string or array of strings)
• dictionary: (optional string)
• config: (optional string)

Additional fields

This supports the following additional fields:

facets: Option<IndexMap<String, Value>>

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: Option<BTreeMap<ConfigKey, ConfigValueType>>

The configuration schema as defined by a component. Each key represents a single field in the schema.

Configuration fields are JSON objects and must define a type which can be one of the following strings: bool, uint8, int8, uint16, int16, uint32, int32, uint64, int64, string, vector

Example:

config: {
    debug_mode: {
        type: "bool"
    },
}

Fields are resolved from a component’s package by default. To be able to change the values at runtime a mutability specifier is required.

Example:

config: {
    verbose: {
        type: "bool",
        mutability: [ "parent" ],
    },
},

Currently "parent" is the only mutability specifier supported.

Strings must define the max_size property as a non-zero integer.

Example:

config: {
    verbosity: {
        type: "string",
        max_size: 20,
    }
}

Vectors must set the max_count property as a non-zero integer. Vectors must also set the element property as a JSON object which describes the element being contained in the vector. Vectors can contain booleans, integers, and strings but cannot contain other vectors.

Example:

config: {
    tags: {
        type: "vector",
        max_count: 20,
        element: {
            type: "string",
            max_size: 50,
        }
    }
}

Implementations

impl Document

pub fn merge_from( &mut self, other: &mut Document, include_path: &Path, ) -> Result<(), Error>

pub fn canonicalize(&mut self)

pub fn includes(&self) -> Vec<String>

pub fn all_children_names(&self) -> Vec<&Name>

pub fn all_collection_names(&self) -> Vec<&Name>

pub fn all_storage_names(&self) -> Vec<&Name>

pub fn all_storage_with_sources<'a>( &'a self, ) -> HashMap<&'a Name, &'a CapabilityFromRef>

pub fn all_service_names(&self) -> Vec<&Name>

pub fn all_protocol_names(&self) -> Vec<&Name>

pub fn all_directory_names(&self) -> Vec<&Name>

pub fn all_runner_names(&self) -> Vec<&Name>

pub fn all_resolver_names(&self) -> Vec<&Name>

pub fn all_dictionary_names(&self) -> Vec<&Name>

pub fn all_dictionaries<'a>(&'a self) -> HashMap<&'a Name, &'a Capability>

pub fn all_config_names(&self) -> Vec<&Name>

pub fn all_environment_names(&self) -> Vec<&Name>

pub fn all_capability_names(&self) -> HashSet<&Name>

Trait Implementations

impl Debug for Document

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Document

fn default() -> Document

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Document

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl MarkdownReferenceDocGenerator for Document

fn get_reference_doc_markdown() -> String

Returns a Markdown representation of the reference docs for the struct that is derived from ReferenceDoc. The returned Markdown indents any # Markdown headers in individual field doc comments to ensure a well structured final Markdown document.

fn get_reference_doc_markdown_with_options( indent_headers_by: usize, indent_with_spaces: usize, ) -> String

This method is called internally by the reference doc generator when recursing to generate documentation for field types.

impl PartialEq for Document

fn eq(&self, other: &Document) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Document

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Document