Struct cml::Document

source ·
pub struct Document {
    pub include: Option<Vec<String>>,
    pub disable: Option<Disable>,
    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>>,
}
Expand description

§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]{#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:

§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.

§disable: Option<Disable>

The disable section disables certain features in a particular CML that are otherwise enforced by cmc.

§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: [fidl-environment-decl]: /reference/fidl/fuchsia.component.decl#Environment [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§

source§

impl Document

source

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

source

pub fn canonicalize(&mut self)

source

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

source

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

source

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

source

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

source

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

source

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

source

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

source

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

source

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

source

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

source

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

source

pub fn all_dictionaries_with_sources<'a>( &'a self ) -> HashMap<&'a Name, Option<&'a DictionaryRef>>

source

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

source

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

Trait Implementations§

source§

impl Debug for Document

source§

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

Formats the value using the given formatter. Read more
source§

impl Default for Document

source§

fn default() -> Document

Returns the “default value” for a type. Read more
source§

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

source§

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>
where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer. Read more
source§

impl MarkdownReferenceDocGenerator for Document

source§

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.
source§

impl PartialEq for Document

source§

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

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl Serialize for Document

source§

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

Serialize this value into the given Serde serializer. Read more
source§

impl StructuralPartialEq for Document

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> Encode<Ambiguous1> for T

source§

unsafe fn encode( self, _encoder: &mut Encoder<'_>, _offset: usize, _depth: Depth ) -> Result<(), Error>

Encodes the object into the encoder’s buffers. Any handles stored in the object are swapped for Handle::INVALID. Read more
source§

impl<T> Encode<Ambiguous2> for T

source§

unsafe fn encode( self, _encoder: &mut Encoder<'_>, _offset: usize, _depth: Depth ) -> Result<(), Error>

Encodes the object into the encoder’s buffers. Any handles stored in the object are swapped for Handle::INVALID. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Pointable for T

source§

const ALIGN: usize = _

The alignment of pointer.
§

type Init = T

The type for initializers.
source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
source§

impl<T> Same for T

§

type Output = T

Should always be Self
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

impl<T> DeserializeOwned for T
where T: for<'de> Deserialize<'de>,