Struct RealmBuilder

pub struct RealmBuilder { /* private fields */ }

The RealmBuilder struct can be used to assemble and create a component realm at runtime. For more information on what can be done with this struct, please see the documentation on fuchsia.dev

Implementations

impl RealmBuilder

pub async fn new() -> Result<Self, Error>

Creates a new, empty Realm Builder.

pub async fn with_params(params: RealmBuilderParams) -> Result<Self, Error>

pub async fn initialize(self) -> Result<(String, Task<()>), Error>

Initializes the realm, but doesn’t create it. Returns the root URL and the task managing local component implementations. The caller should pass the URL into fuchsia.component.Realm#CreateChild, and keep the task alive until after fuchsia.component.Realm#DestroyChild has been called.

pub async fn build(self) -> Result<RealmInstance, Error>

Creates this realm in a child component collection. By default this happens in the DEFAULT_COLLECTION_NAME collection with an autogenerated name for the instance.

Also by default, after creation it starts the child component by connecting to the fuchsia.component.Binder protocol exposed from the root realm, which gets added automatically by the server.

pub async fn with_nested_component_manager( self, component_manager_fragment_only_url: &str, ) -> Result<Self, Error>

Initializes the created realm under an instance of component manager, specified by the given fragment-only URL. Returns the realm containing component manager.

This function should be used to modify the component manager realm. Otherwise, to directly build the created realm under an instance of component manager, use build_in_nested_component_manager().

NOTE: Any routes passed through from the parent need to be routed to “#realm_builder” in the test component’s CML file.

pub async fn build_in_nested_component_manager( self, component_manager_fragment_only_url: &str, ) -> Result<RealmInstance, Error>

Launches a nested component manager which will run the created realm (along with any local components in the realm). This component manager must be referenced by a fragment-only URL.

This function checks for any protocol routes from parent and arranges for them to be passed through component_manager.

NOTE: Currently, passthrough only supports protocol capabilities.

pub async fn add_child_realm( &self, name: impl Into<String>, options: ChildOptions, ) -> Result<SubRealmBuilder, Error>

pub async fn add_child_realm_from_relative_url( &self, name: impl Into<String>, relative_url: impl Into<String>, options: ChildOptions, ) -> Result<SubRealmBuilder, Error>

pub async fn add_child_realm_from_decl( &self, name: impl Into<String>, decl: ComponentDecl, options: ChildOptions, ) -> Result<SubRealmBuilder, Error>

pub async fn add_local_child( &self, name: impl Into<String>, local_component_implementation: impl Fn(LocalComponentHandles) -> BoxFuture<'static, Result<(), Error>> + Sync + Send + 'static, options: ChildOptions, ) -> Result<ChildRef, Error>

Adds a new component with a local implementation to the realm

pub async fn add_child( &self, name: impl Into<String>, url: impl Into<String>, options: ChildOptions, ) -> Result<ChildRef, Error>

Adds a new component to the realm by URL

pub async fn add_child_from_decl( &self, name: impl Into<String>, decl: ComponentDecl, options: ChildOptions, ) -> Result<ChildRef, Error>

Adds a new component to the realm with the given component declaration

pub async fn get_component_decl( &self, name: impl Into<ChildRef>, ) -> Result<ComponentDecl, Error>

Returns a copy of the decl for a child in this realm. This operation is only supported for:

• A component with a local implementation
• A component added with a fragment-only component URL (typically, components bundled in the same package as the realm builder client, sharing the same /pkg directory, for example, #meta/other-component.cm; see https://fuchsia.dev/fuchsia-src/reference/components/url#relative-fragment-only).
• An automatically generated realm (such as the root)

pub async fn replace_component_decl( &self, name: impl Into<ChildRef>, decl: ComponentDecl, ) -> Result<(), Error>

Replaces the decl for a child of this realm. This operation is only supported for:

• A component with a local implementation
• A component added with a fragment-only component URL (typically, components bundled in the same package as the realm builder client, sharing the same /pkg directory, for example, #meta/other-component.cm; see https://fuchsia.dev/fuchsia-src/reference/components/url#relative-fragment-only).
• An automatically generated realm (such as the root)

pub async fn get_realm_decl(&self) -> Result<ComponentDecl, Error>

Returns a copy the decl for this realm

pub async fn replace_realm_decl(&self, decl: ComponentDecl) -> Result<(), Error>

Replaces the decl for this realm

pub async fn add_route(&self, route: Route) -> Result<(), Error>

Adds a route between components within the realm

pub async fn init_mutable_config_from_package( &self, name: impl Into<ChildRef>, ) -> Result<(), Error>

Load the component’s structured config values from its package before applying overrides.

pub async fn init_mutable_config_to_empty( &self, name: impl Into<ChildRef>, ) -> Result<(), Error>

Allow setting config values without loading any packaged values first.

pub async fn set_config_value( &self, name: impl Into<ChildRef>, key: &str, value: ConfigValue, ) -> Result<(), Error>

Replaces a value of a given configuration field

pub async fn read_only_directory( &self, directory_name: impl Into<String>, to: Vec<impl Into<Ref>>, directory_contents: DirectoryContents, ) -> Result<(), Error>

Creates and routes a read-only directory capability to the given targets. The directory capability will have the given name, and anyone accessing the directory will see the given contents.

pub async fn add_capability( &self, capability: CapabilityDecl, ) -> Result<(), Error>

Adds a Capability to the root realm.

pub async fn add_collection( &self, collection: CollectionDecl, ) -> Result<CollectionRef, Error>

Adds a Collection to the root realm.

pub async fn add_environment( &self, environment: EnvironmentDecl, ) -> Result<(), Error>

Adds a Environment to the root realm.

Trait Implementations

impl Debug for RealmBuilder

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

Formats the value using the given formatter.