The Fuchsia System Interface is constantly changing, and new Fuchsia releases are constantly being created. Rather than reasoning about each Fuchsia release's compatibility with the Fuchsia System Interface from each other release, which would be overwhelming, a release is compatible with a limited number of API levels.
API levels are essentially the versions of the APIs that make up the Fuchsia
platform surface. For example, API level 10 is the 10th edition of the Fuchsia
API surface. API levels are synchronized with milestone releases, so API level
10 can also be thought of as the latest stable numerical version of the
Fuchsia platform surface when F10 was published.
API levels are immutable. While APIs may be added, removed, or changed over time, the set of APIs and their semantics at a specific API level will never change once that API level has been published. This means that any two Fuchsia releases that know about a given API level agree on the set and behavior of API elements that make up that API level.
The Fuchsia System Interface is not limited to FIDL - it also comprises system calls, C++ libraries and the methods therein, persistent file formats, and more. Conceptually, these are all versioned by API level, but in practice, versioning support for FIDL libraries is much farther along than for other aspects of the Fuchsia System Interface.
As a user of the Fuchsia SDK, you select a single target API level when building
a component. If you target API level 11, your component has access to exactly
the API elements that are available in API level 11, no matter which version
of the Fuchsia SDK you're using. If a method was added in API level 12, the
component cannot use it in the generated bindings. If a method available in API
level 11 was removed in API level 12, the component continues to be able to
use it.
When building a component, the tools in the SDK embed the target API level's associated ABI revision in the component's package. This is called the component's ABI revision stamp.
The ABI revision stamp allows Fuchsia to ensure that the runtime behavior
observed by the component matches the behavior specified by its target API level.
The ABI revision stamp is used very coarsely: if the Fuchsia platform build
supports that ABI revision's corresponding API level, the component is allowed
to run. Otherwise (for instance, if an external component targets API level 11
but the OS binaries no longer implement methods that were part of API level
11), Component Manager prevents it from starting up.
Example
You can use API levels to make statements like, the
fuchsia.lightsensor.LightSensorData FIDL table had three fields in API level
10 (rgbc, calculated_lux, and correlated_color_temperature), but two more
were added in API level 11 (si_rgbc and is_calibrated). Since API level 11,
it has had five fields, but in the future, such as in API level 16, fields may
be added or removed.
Differences for platform developers and users of the Fuchsia SDK
As a user of the Fuchsia SDK, you pick an API level which defines the set of APIs that you can use and (indirectly) the set of platform releases on which your Fuchsia component can run on. Your component will only be able to use APIs that existed at that specific API level, not any API that was added after or deleted before your chosen API level. If you want access to additional APIs, you should update your component's target API level to access the new functionality.
On the other hand, the platform build targets a set of API levels based on the
contents of version_history.json. Thus,
as a platform developer, you need to make sure all your changes are compatible
with all supported API levels. When you add new functionality or otherwise
change the Fuchsia System Interface, you must do so at the HEAD or
NEXT API level.
Phases
A phase indicates the level of support that a Fuchsia release provides for a given API level. An API level can be in a Supported, Sunset, or a Retired phase.
Each Fuchsia release supports multiple API levels, and assigns each API level to a phase.
API levels can be in one of the following phases, listed in the order each API level goes through:
Supported
Components built targeting API levels in this phase (with any release) run on the platform release. In addition, you can use the SDK to build components targeting API levels in this phase.
For example, if API level 17 is Supported in a given release, that means that the OS binaries from that release can run components that target API level 17, and the SDK from that release can build components that target API level 17.
Sunset
Components built targeting API levels in this phase run on the platform release. However, you cannot use the SDK to build components targeting API levels in this phase.
For example, if API level 17 is Sunset in a given release, that means the OS binaries from that release can run components that target API level 17, but the SDK from that release cannot build components that target API level 17.
Retired
Components built targeting API levels in this phase do not run on the platform release, and the SDK does not support them.
For example, if API level 17 is Retired in a given release, the OS binaries from that release cannot run components that target API level 17, and the SDK from that release cannot build components that target API level 17.
Example
For example, a Fuchsia version 20.20240203.2.1 might include:
- API levels
17,18, and19in the Supported phase. This means SDK version20.20240203.2.1can build components targeting any of these API levels, and devices running Fuchsia version20.20240203.2.1can run components that target any of these API levels. - API levels
15and16in the Sunset phase. Fuchsia will still run components that target Sunset API levels, but the SDK will no longer support targeting them when building components. - API levels
1-14in the Retired phase. Fuchsia does not build or run components targeting Retired API levels, but they are retained for posterity.
API levels are published in the Supported phase, shortly before their
corresponding milestone branch cut. The hypothetical 20.20240203.2.1 canary
release above comes from before API level 20 was published, so API level 20
is absent. Shortly before the F20 branch cut, API level 20 will be
published, and subsequent releases (say, 20.20240301.4.1) will list API level
20 as "Supported". In particular, all milestone releases include their
corresponding API level in the Supported phase.
Special API levels
In addition to the stable numerical API levels there are two special API levels:
Unlike other API levels, the contents of NEXT and HEAD can be changed in
arbitrary ways from release to release. API elements can be added, modified,
replaced, deprecated, and/or removed. In principle, NEXT in 20.20240203.1.1
could look completely different from NEXT in 20.20240203.2.1, though in
practice, changes will be incremental.
HEAD is newer than NEXT, meaning that all API changes in NEXT are also
included in HEAD.
As a user of the Fuchsia SDK, targeting HEAD or NEXT voids the
API and ABI compatibility guarantees.
NEXT
NEXT represents a "draft" version of the next numerical API level. When the
release team publishes a new API level, NEXT is replaced with the new API
level throughout the codebase. This is done by creating a changelist replacing
instances of NEXT in FIDL annotations, C preprocessor macros, and Rust macros
with the specific number of the next milestone branch. API elements in NEXT
must be functional, and are unlikely to change before the next API level is
published, though changes are still possible.
HEAD
HEAD represents the bleeding edge of development, intended for use by in-tree
clients (for example, other platform components or integration tests), where
there is no expectation of stability. API elements introduced in HEAD may not
even be functional; for example, a method may have been added to a protocol at
HEAD, but the protocol server might not actually implement that method yet.