Component sandbox features

This section provides guidance on migrating additional CMX sandbox features.

Storage features

If your component uses any of the following features, follow the instructions in this section to migrate storage access:

Feature	Description	Storage Capability	Path
`isolated-persistent-storage`	Isolated persistent storage directory	`data`	`/data`
`isolated-cache-storage`	Managed persistent storage directory	`cache`	`/cache`
`isolated-temp`	Managed in-memory storage directory	`tmp`	`/tmp`

These features are supported in v2 components using storage capabilities.

Declare the required storage capabilities

When migrating your component manifest, add the following to your CML file:

// my_component.cml
{
    use: [
        ...
        {
            storage: "data",
            path: "/data",
        },
    ],
}

Route storage from the parent realm

When adding your component, you'll need to offer the appropriate storage path to your component from its parent realm.

// core.cml / component.core_shard.cml
{
    children: [
        ...
        {
            name: "my_component",
            url: "fuchsia-pkg://fuchsia.com/my-package#meta/my_component.cm",
        },
    ],
    offer: [
        ...
        {
            storage: "data",
            from: "self",
            to: [ "#my_component" ],
        },
    ]
}

Update component ID index

Components that use storage use a component ID index to preserve access to persistent storage contents across the migration, such as core_component_id_index.json5. You must update the component index to map the new component moniker to the same instance within the component that provides the storage capability.

Find any instances of your current v1 component in component index files:

// core_component_id_index.json5
{
    instances: [
        ...
        {
            instance_id: "...",
            appmgr_moniker: {
                url: "fuchsia-pkg://fuchsia.com/my-package#meta/my_component.cmx",
                realm_path: [ ... ]
            },
        },
    ],
}

Replace the appmgr_moniker for your component instance with the new moniker in the migrated v2 realm, keeping the same instance_id:

// core_component_id_index.json5
{
    instances: [
        ...
        {
            instance_id: "...",
            moniker: "/core/my_component",
        },
    ],
}

(Optional) Enable `persistent_storage` for collection descendants using storage

If the component or any of its ancestors, such as the session component, is part of a collection, and the component requires storage contents to exist after a component instance has been destroyed, add the persistent_storage setting to the collection decl:

{
  collections: [
    {
      name: "my_collection",
      durability: "durability",
      persistent_storage: true,
    }
  ],
}

This setting allows collection descendants using the component ID index to preserve storage content across dynamic component instances.

Storage capabilities in tests

When migrating tests, you will need to route storage access to your test component if any of the components in the test realm access a storage path.

Following the example in Test uses injected services, add the following to route storage access to your test component:

// my_component_test.cml (test component)
}
    use: [
        ...
        {
            storage: "data",
            path: "/data",
        },
    ],
}

Directory features

If your component uses any of the following features, follow the instructions in this section to migrate directory access:

Feature	Description	Directory Capability	Path
`shell-commands`	Executable directory of shell binaries	`bin`	`/bin`
`root-ssl-certificates`	Read-only root certificate data	`root-ssl-certificates`	`/config/ssl`

These features are supported in v2 components using directory capabilities.

Declare the required directory capabilities

When migrating your component manifest, add the following to your CML file:

// my_component.cml
{
    use: [
        ...
        {
            directory: "root-ssl-certificates",
            rights: [ "r*" ],
            path: "/config/ssl",
        },
    ],
}

Route directory from the parent realm

When adding your component, you'll need to offer the directory capabilities to your component.

// core.cml / component.core_shard.cml
{
    children: [
        ...
        {
            name: "my_component",
            url: "fuchsia-pkg://fuchsia.com/my-package#meta/my_component.cm",
        },
    ],
    offer: [
        ...
        {
            directory: "root-ssl-certificates",
            from: "parent",
            to: [ "#my_component" ],
        },
    ],
}

Directory paths in tests

When migrating tests, you need to route the directory capabilities to your test component if any of the components in the test realm require directory access.

Test Runner Framework only allows the following directory capabilities to be used by non-hermetic tests:

Capability	Description	Path
`root-ssl-certificates`	Read-only root certificate data	`/config/ssl`

Following the example in Test uses injected services, add the following to route directory access to your test component:

// my_component_test.cml (test component)
{
    use: [
        ...
        {
            directory: "root-ssl-certificates",
            rights: [ "r*" ],
            path: "/config/ssl",
        },
    ],
}

Configuration data

If your component uses any of the following features, follow the instructions in this section to migrate directory access:

Feature	Description	Directory Capability	Path
`config-data`	Read-only configuration data	`config-data`	`/config/data`

These features are supported in v2 components using directory capabilities.

For more details using data files, see product-specific configuration with config_data().

Consider packaging your data files hermetically with resource() if your component doesn't need to accept data files from arbitrary parts of the source tree. Using resource() is simpler and more efficient.

Declare the required directory capabilities

When migrating your component manifest, add the following to your CML file:

// my_component.cml
{
    use: [
        ...
        {
            directory: "config-data",
            rights: [ "r*" ],
            path: "/config/data",
        },
    ],
}

Route directory from the parent realm

When adding your component, you'll need to offer the directory capability with the appropriate subdirectory to your component.

// core.cml / component.core_shard.cml
{
    children: [
        ...
        {
            name: "my_component",
            url: "fuchsia-pkg://fuchsia.com/my-package#meta/my_component.cm",
        },
    ],
    offer: [
        ...
        {
            directory: "config-data",
            from: "parent",
            to: [ "#my_component" ],
            subdir: "my-package",
        },
    ],
}

Configuration data in tests

When migrating tests, you need to route the directory capability with the appropriate subdirectory to your test component if any of the components in the test realm require directory access. The name of the subdirectory should match the name of the package that contains the component.

Following the example in Test uses injected services, add the following to route directory access to your test component:

// my_component_test.cml (test component)
{
    use: [
        ...
        {
            directory: "config-data",
            rights: [ "r*" ],
            path: "/config/data",
            subdir: "my-package",
        },
    ],
}

Device directories

If your component uses any of the following features, follow the instructions in this section to migrate device access:

Feature	Description	Path
`dev`	Entries in `devfs`	`/dev/*`
`dev`	Legacy device entries	`/dev/null`, `/dev/zero`

Device filesystem access is supported in Components v2 using directory capabilities.

Consider the following example using Components v1 to access /dev/class/input-report:

// my_component.cmx
{
    "program": { ... },
    "sandbox": {
        "dev": [
            "class/input-report"
        ]
    }
}

Declare the required device capabilities

When migrating your component manifest, add the device path as a directory capability to your CML file:

// my_component.cml
{
    use: [
        ...
        {
            directory: "dev-input-report",
            rights: [ "r*" ],
            path: "/dev/class/input-report",
        },
    ],
}

Route device subdirectory from the parent realm

When adding your component, you'll need to offer the appropriate device path to your component from its parent realm.

// core.cml / component.core_shard.cml
{
    children: [
        ...
        {
            name: "my_component",
            url: "fuchsia-pkg://fuchsia.com/my-package#meta/my_component.cm",
        },
    ],
    offer: [
        ...
        {
            directory: "dev-dev",
            from: "parent",
            as: "dev-input-report",
            to: [ "#my_component" ],
            subdir: "input-report",
        },
    ],
}

Legacy device entries

Components v2 does not route the following pseudo-device entries to components:

/dev/zero: Create an equivalent (pseudo-)file in your code if necessary. For example, see the Chromium ScopedDevZero implementation.
/dev/null: Use fdio_fd_null_create to get a file descriptor to a file that acts like /dev/null.

Device directories in tests

When migrating tests, you need to route the directory capabilities to your test component if any of the components in the test realm require directory access.

Test Runner Framework only allows the following device directories to be used by non-hermetic tests:

Capability	Description
`dev-input`	Input
`dev-input-report`	Input method events
`dev-display-controller`	Graphical display controller
`dev-goldfish-address-space`	Goldfish address space device
`dev-goldfish-control`	Goldfish control device
`dev-goldfish-pipe`	Goldfish pipe device
`dev-gpu`	GPU device
`dev-gpu-performance-counters`	GPU performance counters device

Following the example in Test uses injected services, add the following to route directory access to your test component:

// my_component_test.cml (test component)
{
    use: [
        ...
        {
            directory: "dev-input-report",
            rights: [ "r*" ],
            path: "/dev/class/input-report",
        },
    ],
}

Event capabilities

If your component uses any of the following features, follow the instructions in this section:

Feature	Description	Path
`hub`	Observing component path changes	`/hub/c/*`
`hub`	Observing realm path changes	`/hub/r/*`

These features are supported in v2 components using event capabilities.

Event sources in tests

When migrating tests, you'll need to inject any components you wish to observe into the test realm and route the appropriate lifecycle events for those components to your test component.

Following the example in Test uses injected services, route the fuchsia.sys2.EventSource capability and the appropriate events to your test component:

// my_component_test.cml (test component)
{
    children: [
        {
            name: "my_component",
            url: "fuchsia-pkg://fuchsia.com/my-package#meta/my_component.cm",
        },
    ],
    use: [
        {
            protocol: [ "fuchsia.sys2.EventSource" ],
        },
        {
            event: [ "started" ],
            from: "framework",
            modes: [ "async" ],
        },
    ],
}

Build Info

When migrating the build-info feature, instead use the fuchsia.buildinfo.Provider protocol. This protocol is the only supported method of retrieving build information moving forward. To use this protocol, add it while declaring required services.

Vulkan

When migrating the vulkan feature or code that uses a //src/lib/vulkan/*.shard.cmx shard, instead use the vulkan/client.shard.cml shard as described in the Vulkan documentation.

What's next

Explore the following sections for additional migration guidance on specific features your components may support:

Component sandbox features

Storage features

Declare the required storage capabilities

Route storage from the parent realm

Update component ID index

(Optional) Enable persistent_storage for collection descendants using storage

Storage capabilities in tests

Directory features

Declare the required directory capabilities

Route directory from the parent realm

Directory paths in tests

Configuration data

Declare the required directory capabilities

Route directory from the parent realm

Configuration data in tests

Device directories

Declare the required device capabilities

Route device subdirectory from the parent realm

Legacy device entries

Device directories in tests

Event capabilities

Event sources in tests

Build Info

Vulkan

What's next

(Optional) Enable `persistent_storage` for collection descendants using storage