Honoring Asian Pacific American Heritage Month. See how.

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 storage 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",
        },
    ],
}

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
factory-data Read-only factory partition data factory /factory
durable-data Persistent data that survives factory reset durable /durable
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",
            from: "parent",
            as: "dev-input-report",
            to: [ "#my_component" ],
            subdir: "class/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-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: