Starboard Versioning
Stay organized with collections
Save and categorize content based on your preferences.
Motivation
When a porter implements Starboard for a platform, it is more precise to say
that they have implemented support for a certain version of Starboard.
Changes to the Starboard API are associated with Starboard versions. Any usage
of new Starboard APIs must also be protected by a compile-time check for the
Starboard version it belongs to. This decoupling of Cobalt and Starboard
versions ensures that a porter can update to a newer version of Cobalt, but not
be required to implement new Starboard APIs, if the version of Starboard they
have implemented is still supported.
Starboard API version vs. Starboard application version
The Starboard version describes the set of Starboard APIs available to Starboard
applications. It will be incremented with every open-source release that
includes changes to the Starboard API. Reasons to increment the Starboard API
version include:
- New Starboard APIs
- Removed Starboard APIs
- Modified semantics to existing APIs
Some notable cases that do not justify incrementing the Starboard version
include:
- More descriptive or clearer comments for existing APIs that do not change the
semantics
- New utility classes that are built on top of Starboard APIs, such as
starboard::ScopedFile
- Changes that affect the upward API to Starboard applications, but not the
downward API to porters. For example, defining new upward APIs in terms of
existing Starboard APIs.
A particular Starboard application may be versioned independently of the
Starboard API. A given version of a Starboard application may support a range of
Starboard versions. It may be the case that some new functionality in a
Starboard application requires Starboard APIs that were added to a particular
API version. If a porter wants to use such a feature, they must therefore also
implement the required version of the Starboard API. For example, Voice Search
was added to Cobalt version 5 and requires the SbMicrophone APIs which were
added to Starboard version 2. Platforms that implemented Starboard version 1
continued to build and run Cobalt 5 correctly, but the Voice Search feature
would be unavailable.
Range of supported Starboard versions
The minimum supported API version is defined by the SB_MINIMUM_API_VERSION
macro, which is defined in starboard/configuration.h. Likewise, the
SB_MAXIMUM_API_VERSION macro defines the maximum supported API version. All
platforms must declare a SB_API_VERSION macro in the platform’s
configuration.h to declare the starboard version the platform has implemented.
Declaring implementation for an API version outside this range will result in an
error at compilation time.
Generally Starboard applications will not support all versions of the Starboard
API indefinitely. Starboard application owners may increment the minimum
required Starboard version at their discretion.
Using new Starboard APIs from Starboard Applications
Usage of a Starboard API that is not available in all supported Starboard API
versions must be guarded with a check for SB_API_VERSION. Starboard
applications must continue to function correctly and must not disable existing
functionality if this check evaluates to false, but it’s acceptable to disable
new functionality in Starboard applications if this evaluates to false.
Adding and using new Starboard APIs
"Frozen" Starboard versions
All Starboard versions that are less than the SB_MAXIMUM_API_VERSION version
are considered frozen. Any Starboard APIs in a frozen version MUST not change.
Communicating Starboard API changes to porters
When a new version of Starboard is released, starboard/CHANGELOG.md should be
updated with the feature define comments for all features enabled in that
version.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-09-03 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-03 UTC."],[[["\u003cp\u003eStarboard API versioning allows Cobalt and Starboard to update independently, enabling porters to adopt new Cobalt versions without immediately implementing the latest Starboard APIs.\u003c/p\u003e\n"],["\u003cp\u003eStarboard applications may require specific Starboard API versions for certain features, and porters must implement the necessary API version to enable those features.\u003c/p\u003e\n"],["\u003cp\u003ePlatforms must declare their implemented Starboard API version using \u003ccode\u003eSB_API_VERSION\u003c/code\u003e, falling within the minimum and maximum supported versions defined by Starboard.\u003c/p\u003e\n"],["\u003cp\u003eWhen using newer Starboard APIs, applications must include version checks to ensure compatibility and gracefully handle cases where the required API version is unavailable.\u003c/p\u003e\n"],["\u003cp\u003eStarboard API versions prior to the maximum supported version are considered "frozen," meaning their APIs should remain unchanged to maintain backward compatibility.\u003c/p\u003e\n"]]],["Starboard versions define available APIs, incrementing with each open-source release that modifies the API (new, removed, or changed semantics). Cobalt's compatibility with Starboard versions ensures porters can update Cobalt without immediately implementing new Starboard APIs. `SB_MINIMUM_API_VERSION` and `SB_MAXIMUM_API_VERSION` define the supported range, with `SB_API_VERSION` declaring a platform's implemented version. New API usage requires checks for `SB_API_VERSION`. Frozen versions (below `SB_MAXIMUM_API_VERSION`) cannot be modified. Changes are documented in `CHANGELOG.md`.\n"],null,["Motivation\n\nWhen a porter implements Starboard for a platform, it is more precise to say\nthat they have implemented support for a certain version of Starboard.\nChanges to the Starboard API are associated with Starboard versions. Any usage\nof new Starboard APIs must also be protected by a compile-time check for the\nStarboard version it belongs to. This decoupling of Cobalt and Starboard\nversions ensures that a porter can update to a newer version of Cobalt, but not\nbe required to implement new Starboard APIs, if the version of Starboard they\nhave implemented is still supported.\n\nStarboard API version vs. Starboard application version\n\nThe Starboard version describes the set of Starboard APIs available to Starboard\napplications. It will be incremented with every open-source release that\nincludes changes to the Starboard API. Reasons to increment the Starboard API\nversion include:\n\n- New Starboard APIs\n- Removed Starboard APIs\n- Modified semantics to existing APIs\n\nSome notable cases that do not justify incrementing the Starboard version\ninclude:\n\n- More descriptive or clearer comments for existing APIs that do not change the semantics\n- New utility classes that are built on top of Starboard APIs, such as `starboard::ScopedFile`\n- Changes that affect the upward API to Starboard applications, but not the downward API to porters. For example, defining new upward APIs in terms of existing Starboard APIs.\n\nA particular Starboard application may be versioned independently of the\nStarboard API. A given version of a Starboard application may support a range of\nStarboard versions. It may be the case that some new functionality in a\nStarboard application requires Starboard APIs that were added to a particular\nAPI version. If a porter wants to use such a feature, they must therefore also\nimplement the required version of the Starboard API. For example, Voice Search\nwas added to Cobalt version 5 and requires the SbMicrophone APIs which were\nadded to Starboard version 2. Platforms that implemented Starboard version 1\ncontinued to build and run Cobalt 5 correctly, but the Voice Search feature\nwould be unavailable.\n\nRange of supported Starboard versions\n\nThe minimum supported API version is defined by the `SB_MINIMUM_API_VERSION`\nmacro, which is defined in starboard/configuration.h. Likewise, the\n`SB_MAXIMUM_API_VERSION` macro defines the maximum supported API version. All\nplatforms must declare a `SB_API_VERSION` macro in the platform's\nconfiguration.h to declare the starboard version the platform has implemented.\nDeclaring implementation for an API version outside this range will result in an\nerror at compilation time.\nGenerally Starboard applications will not support all versions of the Starboard\nAPI indefinitely. Starboard application owners may increment the minimum\nrequired Starboard version at their discretion.\n\nUsing new Starboard APIs from Starboard Applications\n\nUsage of a Starboard API that is not available in all supported Starboard API\nversions must be guarded with a check for `SB_API_VERSION`. Starboard\napplications must continue to function correctly and must not disable existing\nfunctionality if this check evaluates to false, but it's acceptable to disable\nnew functionality in Starboard applications if this evaluates to false.\n\nAdding and using new Starboard APIs\n\n\"Frozen\" Starboard versions\n\nAll Starboard versions that are less than the `SB_MAXIMUM_API_VERSION` version\nare considered frozen. Any Starboard APIs in a frozen version MUST not change.\n\nCommunicating Starboard API changes to porters\n\nWhen a new version of Starboard is released, [starboard/CHANGELOG.md](../CHANGELOG.md) should be\nupdated with the feature define comments for all features enabled in that\nversion."]]
