Google is committed to advancing racial equity for Black communities. See how.

Components v2 migration

Goal & motivation

The Component Framework is one of the key foundations of Fuchsia's usermode runtime environment. The original incarnation of components dates back to the inception of the Fuchsia OS and the initial commits in 2016. The framework has steadily evolved since then.

What's been migrated?

Last updated: September 2021

The migration is underway, but broadly speaking:

  • Over a third of production components have been migrated.
  • All usermode tests have been migrated to run as modern components.

Technical background

Modern and legacy components

Presently there are two revisions of the component framework, the legacy architecture (also called appmgr after its main program, or sometimes Components v1 ) and the modern architecture (also called Component Framework, or sometimes Components v2 ).

The legacy framework is largely comprised of:

  • appmgr, a program that manages the runtime environment for legacy components. appmgr is the root of the legacy components tree, and provides some foundational services such as the legacy component ELF runner and Loader service.
  • sysmgr , a component that manages the sys realm. sysmgr is launched by appmgr.
  • The .cmx file format for legacy component manifests.
  • The fuchsia.sys.* FIDL library.
  • The TestWithEnvironment testing library.

The legacy framework's development reached its peak in 2018. In 2019, Fuchsia team began developing the modern Component Framework. Component Framework is largely comprised of:

The following component framework software supports both modern and legacy components:

Topology

A high-level diagram of the system's component topology is shown below:

Realms diagram

  • Modern components are shown in blue boxes.
  • Legacy components are shown in red boxes.
  • The dashed arrow between the session and Modular represents bidirectional communication between both systems.

In addition, all unit tests with generated manifests are modern components.

Interoperability

Component manager launches appmgr, itself a modern component, which manages legacy components. appmgr is the ancestor of all legacy components running on the system. Users may continue developing and maintaining existing legacy components while migrations take place at their own pace. However, if you write a new component, you are strongly advised to make it a modern component unless there is some reason it must be legacy. All legacy components in-tree must appear in the GN allowlist at //build/components/cmx.

Build configurations that use the Session Framework also include a session component which runs under session_manager. All capabilities hosted by legacy components that are required by the session are routed from appmgr to session_manager by core.

Terminology

Use this terminology when talking about the state of migrating a legacy component and its tests to the modern framework.

  The component Tests that exercise it
Fully migrated
  • has a .cml file and no .cmx file
  • runs as a modern component in all product builds
  • All automated tests run the component as a modern component
Partially migrated
  • has a .cml file and a .cmx file
  • runs as a legacy component in some product configurations but not others, or is guarded by a flag to do so for development purposes
  • Some automated tests exist in which the component runs as a modern component, but others run it as legacy
Prototyped
  • runs as a legacy component in all product configurations
  • has a .cml file
  • All automated tests in CI/CQ run the legacy component
  • there are tests with the modern component, but they don't run in CI/CQ
Not migrated
  • does not have a .cml file
  • There are no tests that run the component as a modern | component
|

Examples

"root_presenter is partially migrated but its tests are not migrated."

"stash and its tests are fully migrated."

"basemgr is a partially migrated component with partially migrated tests. Specifically, ..."

"setui_service's modern component was prototyped and it exposed some missing dependencies."

How to help

Picking a task

Component migrations are happening throughout the system. Any component that still has at least one .cmx file is a migration candidate.

For legacy sys realm components you may use the self-service migration guide. Multiple component owners have recently seen success in using this guide, including but not limited to:

  • Software Delivery
  • Netstack
  • Wlan
  • Bluetooth
  • Cobalt
  • Archivist

Doing a task

Component migrations may take multiple incremental steps to complete due to dependencies between other components that have not been migrated yet. For example, a component and its tests can be migrated separately. For more details on the incremental stages, see terminology.

The final step for migrating a component typically involves replacing all .cmx files with equivalent .cml files. For detailed instructions on migrating a component and its tests, see the self-service migration guide.

Completing a task

Send code reviews to owners of the directories with the component definitions that you're changing, and to one of the people listed below:

Examples

Sponsors

Reach out for questions or for status updates: