| # Environments (Components v2) |
| |
| <<../_v2_banner.md>> |
| |
| *Environments* provide a way to configure certain choices the framework makes |
| for components in a [realm][doc-realms]. |
| [Component manifests][doc-component-manifests] may define environments and |
| assign them to child realms. An environment applies to a component instance's |
| entire realm, unless some sub-realm overrides it (see |
| [Propagation](#propagation)). |
| |
| ## Properties {#properties} |
| |
| Environments let you configure the following behavior of a realm: |
| |
| - [Setting the runners available to components](#runners) |
| |
| ### Runners {#runners} |
| |
| By registering a runner in an [environment declaration][doc-environments], you |
| make it available to any component instance which has that environment assigned |
| to it. Components specify which runner they use with a [`use`][doc-use] |
| declaration naming the runner. |
| |
| ## Declaring {#declaring} |
| |
| Define a new environment by adding an [environments][doc-environments] |
| declaration to a [component manifest][doc-component-manifests]. |
| |
| For an environment to be used, you must assign it to a child or collection. See |
| [Propagation](#propagation). |
| |
| Environments support two modes of extension, [`REALM`][fidl-extends] or |
| [`NONE`][fidl-extends]: |
| |
| - [`REALM`][fidl-extends]: The environment inherits its properties from the |
| environment that was assigned to this component (the "parent environment"). |
| Any new properties will be added on top of those inherited from the parent |
| environment. Any properties that overlap with the parent environment will |
| override the parent. |
| - [`NONE`][fidl-extends]: The environment starts empty, with no initial |
| properties. |
| |
| ## Propagation {#propagation} |
| |
| A component instance is assigned an environment in one of two ways: |
| |
| - Its [child][doc-children] or [collection][doc-collections] does not |
| have `environment` set. In this case, it will receive its parent's |
| environment. This is the most common case. |
| - Its [child][doc-children] or [collection][doc-collections] sets |
| `environment`, which refers to one of the [`environments`][doc-environments] |
| defined by this component. |
| |
| The [root component][doc-root-component] is assigned an environment by |
| [component manager][doc-component-manager]. This includes a bootstrap resolver, |
| the [ELF runner][doc-elf-runner], and default configuration options. |
| |
| ## Environments vs. capability routing {#cap-routing} |
| |
| The semantics of environments contrast with |
| [capability routing][doc-capability-routing]. With capability routing, a |
| capability must be explicitly [exposed][doc-expose] or [offered][doc-offer] by |
| every component in the path from the provider to the consumer. The explicit |
| nature of capability routing makes it easy to guarantee that components don't |
| receive access to capabilities they shouldn't have, thus maintaining the |
| [principle of least privilege][wiki-least-privilege]. |
| |
| However, there are some configuration choices that don't make sense to configure |
| on a per-component basis. For example, consider [runners][doc-runners]. Almost |
| every component needs to use a runner, but defining a new runner is not very |
| common -- certainly less common than defining a protocol capability, for |
| instance. Furthermore, access to a runner doesn't inherently grant a component |
| much privilege, for the component framework mediates access to the runner's |
| protocol and the component can't use that protocol directly. Therefore, runner |
| capabilities are registered in an environment, which makes them available to any |
| component in the realm to which that environment was assigned (unless some |
| sub-realm decides to set a new environment with the runner absent). |
| |
| [doc-capability-routing]: ./component_manifests.md#capability-routing |
| [doc-children]: ./component_manifests.md#children |
| [doc-collections]: ./component_manifests.md#collections |
| [doc-component-manager]: ./component_manager.md |
| [doc-root-component]: ./component_manager.md#booting-the-system |
| [doc-component-manifests]: ./component_manifests.md |
| [doc-elf-runner]: ./elf_runner.md |
| [doc-environments]: ./component_manifests.md#environments |
| [doc-expose]: ./component_manifests.md#expose |
| [doc-offer]: ./component_manifests.md#offer |
| [doc-realms]: ./realms.md |
| [doc-runners]: ./runners.md |
| [doc-use]: ./component_manifests.md#use |
| [fidl-extends]: /sdk/fidl/fuchsia.sys2/decls/environment_decl.fidl |
| [wiki-least-privilege]: https://en.wikipedia.org/wiki/Principle_of_least_privilege |