class Realm

Defined at line 92 of file ../../sdk/lib/sys/component/cpp/testing/realm_builder.h

A `Realm` describes a component instance together with its children.

Clients can use this class to build a realm from scratch,

programmatically adding children and routes.

Clients may also use this class to recursively build sub-realms by calling

`AddChildRealm`.

For more information about RealmBuilder, see the following link.

https://fuchsia.dev/fuchsia-src/development/testing/components/realm_builder

For examples on how to use this library, see the integration tests

found at //sdk/cpp/tests/realm_builder_test.cc

Public Methods

Realm & AddChild (const std::string & child_name, const std::string & url, const ChildOptions & options)

Add a v2 component (.cm) to this Realm.

Names must be unique. Duplicate names will result in a panic.

Defined at line 57 of file ../../sdk/lib/sys/component/cpp/testing/realm_builder.cc

Realm & AddLocalChild (const std::string & child_name, LocalComponent * local_impl, const ChildOptions & options)

This method signature is DEPRECATED.

Add a component instance implementation by raw pointer to a

LocalComponent-derived instance. This component implementation can only be

started once.

The caller is expected to keep the pointer valid for the lifetime of the

component instance (typically the lifetime of the constructed RealmRoot,

unless the component is intentionally stopped earlier). If not, calling

FIDL bindings handled by the LocalComponent would cause undefined behavior.

|Start()| will be called (asynchronously) sometime after calling

component manager start the component automatically.

Names must be unique. Duplicate names will result in a panic.

TODO(https://fxbug.dev/296292544): Remove this method when build support

for API level 16 is removed.

Realm & AddLocalChild (const std::string & child_name, LocalComponentFactory local_impl, const ChildOptions & options)

Add a component by implementing a factory function that creates and returns

a new instance of a |LocalComponentImpl|-derived class. The factory

function will be called whenever the local child is started.

After returning the |LocalComponentImpl|, the RealmBuilder framework will

call |LocalComponentImpl::OnStart()|. Component handles (|ns()|, |svc()|,

and |outgoing()|) are not available during the |LocalComponentImpl|

construction, but are available when |OnStart()| is invoked.

If the component's associated |ComponentController| receives a |Stop()|

request, the |LocalComponentImpl::OnStop()| method will be called. A

derived |LocalComponentImpl| class can override the |OnStop()| method if

the component wishes to take some action during component stop.

A |LocalComponentImpl| can also self-terminate, by calling `Exit()`.

Names must be unique. Duplicate names will result in a panic.

Defined at line 75 of file ../../sdk/lib/sys/component/cpp/testing/realm_builder.cc

void Realm (Realm && )

Defined at line 94 of file ../../sdk/lib/sys/component/cpp/testing/realm_builder.h

Realm & operator= (Realm && )

Defined at line 95 of file ../../sdk/lib/sys/component/cpp/testing/realm_builder.h

void Realm (const Realm & )

Defined at line 97 of file ../../sdk/lib/sys/component/cpp/testing/realm_builder.h

Realm operator= (const Realm & )

Defined at line 98 of file ../../sdk/lib/sys/component/cpp/testing/realm_builder.h

Realm AddChildRealm (const std::string & child_name, const ChildOptions & options)

Create a sub realm as child of this Realm instance. The constructed

Realm is returned.

Defined at line 101 of file ../../sdk/lib/sys/component/cpp/testing/realm_builder.cc

Realm AddChildRealmFromDecl (const std::string & child_name, fuchsia::component::decl::Component & decl, const ChildOptions & options)

Create a sub realm as child of this Realm instance initialized with |decl|. The constructed

Realm is returned.

Defined at line 116 of file ../../sdk/lib/sys/component/cpp/testing/realm_builder.cc

Realm & AddRoute (Route route)

Route a capability from one child to another.

Defined at line 134 of file ../../sdk/lib/sys/component/cpp/testing/realm_builder.cc

Realm & RouteReadOnlyDirectory (const std::string & name, std::vector<Ref> to, DirectoryContents directory)

Offers a directory capability to a component in this realm. The

directory will be read-only (i.e. have `r*` rights), and will have the

contents described in `directory`.

Defined at line 168 of file ../../sdk/lib/sys/component/cpp/testing/realm_builder.cc

Realm & InitMutableConfigFromPackage (const std::string & name)

Load the packaged configuration of the component if available.

Defined at line 186 of file ../../sdk/lib/sys/component/cpp/testing/realm_builder.cc

Realm & InitMutableConfigToEmpty (const std::string & name)

Allow setting configuration values without loading packaged configuration.

Defined at line 194 of file ../../sdk/lib/sys/component/cpp/testing/realm_builder.cc

Realm & SetConfigValue (const std::string & name, const std::string & key, ConfigValue value)

Replaces the value of a given configuration field

Defined at line 202 of file ../../sdk/lib/sys/component/cpp/testing/realm_builder.cc

Realm & AddConfiguration (std::vector<ConfigCapability> configurations)

Adds Configuration Capabilities to the root realm.

Defined at line 210 of file ../../sdk/lib/sys/component/cpp/testing/realm_builder.cc

Realm & AddCapability (fuchsia::component::decl::Capability capability)

Adds a capability to the root realm.

Defined at line 226 of file ../../sdk/lib/sys/component/cpp/testing/realm_builder.cc

Realm & AddCollection (fuchsia::component::decl::Collection collection)

Defined at line 233 of file ../../sdk/lib/sys/component/cpp/testing/realm_builder.cc

Realm & AddEnvironment (fuchsia::component::decl::Environment environment)

Defined at line 239 of file ../../sdk/lib/sys/component/cpp/testing/realm_builder.cc

fuchsia::component::decl::Component GetComponentDecl (const std::string & child_name)

Fetches the Component decl of the given child. This operation is only

supported for:

* A component with a local implementation

* A legacy component

* 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)

Defined at line 261 of file ../../sdk/lib/sys/component/cpp/testing/realm_builder.cc

fuchsia::component::decl::Component GetRealmDecl ()

Fetches the Component decl of this Realm.

Defined at line 269 of file ../../sdk/lib/sys/component/cpp/testing/realm_builder.cc

void ReplaceComponentDecl (const std::string & child_name, fuchsia::component::decl::Component decl)

Updates the Component decl of the given child. This operation is only

supported for:

* A component with a local implementation

* A legacy component

* 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)

Defined at line 247 of file ../../sdk/lib/sys/component/cpp/testing/realm_builder.cc

void ReplaceRealmDecl (fuchsia::component::decl::Component decl)

Updates the Component decl of this Realm.

Defined at line 255 of file ../../sdk/lib/sys/component/cpp/testing/realm_builder.cc

Friends

class RealmBuilder