The Starboard ABI was introduced to provide a single, consistent method for specifying the Starboard API version and the ABI. This specification ensures that any two binaries, built with the same Starboard ABI and with arbitrary toolchains, are compatible.
The Starboard ABI is the set of features, such as the Starboard API version or the sizes of data types, that collectively describes the relationship between the Starboard API and ABI of a binary. In the past, each of these features were inconsistently and ambiguously defined in a variety of files. This led to confusion, and made it difficult to track down the feature values for a platform. To simplify how Starboard is configured for a target platform, all of these features, and their concrete values, are now listed for each distinct target architecture in Starboard ABI files. These files provide a consistent, consolidated view of the values for each of these features, decoupling platform-specific details from architecture.
The overall goal of the Starboard ABI is to provide a way to implement and verify binary compatibility on a target platform, and this goal can be broken down into the following more concise motivations:
With the Starboard ABI being the source of truth for all things architecture related, each platform must now include a Starboard ABI file in its build (see //starboard/sabi for examples). Starboard ABI files are JSON, and should all contain identical keys with the values being appropriate for the architecture. Each platform must override the new GetPathToSabiJsonFile method in its platform configuration to return the path to the desired Starboard ABI file (e.g. //starboard/linux/shared/gyp_configuration.py). By default, an empty and invalid Starboard ABI file is provided.
Additionally, all platforms must include the sabi.gypi in their build configuration. This file will consume the specified Starboard ABI file, resulting in the creation of a set of GYP variables and preprocessor macros. The preprocessor macros are passed directly to the compiler and replace the macros you might be familiar with, such as
The newly defined GYP variables need to be transformed into toolchain specific flags; these flags are what actually makes the build result in a binary for the desired architecture. These flags will, in most cases, be identical to the flags already being used for building.
The process outlined above is shown in the diagram below.
A number of GYP variables and preprocessor macros should no longer be defined directly, and instead the Starboard ABI file will be used to define them. These definitions need to be removed.
The Cobalt team provides, and maintains, Starboard ABI files for the following architectures:
If you find that no valid Starboard ABI file exists for your architecture, or that you need to change any values of a provided Starboard ABI file, please reach out to the Cobalt team to advise.
Similar to the process prior to Starboard ABI files, there are multiple levels of verification that occur:
Finally, binaries produced by the Cobalt team for your architecture, including NPLB, will be made available to ensure end-to-end correctness of the produced binaries.