Application runtime version, sysroots, and Beta APIs

Article
03/26/2024

An Azure Sphere SDK release may contain both production APIs and Beta APIs. Production APIs are considered long-term stable (LTS), whereas Beta APIs are still in development and may change in or be removed from a later release. In most cases, new APIs are marked Beta in their first release and moved to production in a subsequent release. Beta APIs provide early access to new features, enabling prototyping and feedback before they are finalized. Applications that use Beta APIs will generally require modifications after future Azure OS and SDK releases to continue to work correctly.

Beta features are labeled BETA feature in the documentation. Every Azure Sphere high-level application specifies whether it targets only production APIs or both production and Beta APIs.

Target API sets, ARV, and sysroots

The target API set indicates which APIs the application uses: either production APIs only or production and Beta APIs. The target API set value is either an integer that represents the application runtime version (ARV) or the ARV plus a string that identifies the Beta API release. The numeric value alone specifies only the production APIs in the ARV, whereas the "value+BetaNumber" specifies the production and Beta APIs in a particular release. For example, ARV 8 indicates the 21.01 release, and "8+Beta2101" specifies the production and Beta APIs in the 20.01 release. Future releases will add additional ARVs.

The Azure Sphere SDK implements multiple API sets by using sysroots. A sysroot specifies the libraries, header files, and tools that are used to compile and link an application that targets a particular API set. The sysroots are installed in the Microsoft Azure Sphere SDK directory in the sysroots subfolder.

Set or update the target API set for a high-level app

If you base your application on an Azure Sphere sample, the target API set by default is the API set that the sample uses. If the sample uses only production APIs, the target API set will be set to the current ARV value. If the sample uses both production and Beta APIs for the current release, the target API set will be "value+BetaNumber", to include the Beta APIs.

If you don't base your application on a sample, you'll need to set the target API set in the build instructions for the app.

If you've already created an application, you might need to change the target API set if you rebuild the app for a new OS release. If the app uses Beta APIs, you should update it when the target API set options change, which typically occurs at each feature release. Beta APIs may be moved directly from Beta status to production, resulting in a new ARV, or they might be changed and remain in Beta. If you update an application that uses Beta APIs to target a more recent target API set, you may encounter errors or warnings about removed or retired APIs.

Any time you change the target API set, you need to delete the CMakeCache.txt file before you build the application. This file is stored in the out\ARM-Debug or out\ARM-Release directory for your project.

Specify target API set

Set the target API set in CMakePresets.json:

Use "AZURE_SPHERE_TARGET_API_SET" to configure the target API set. For example:

"AZURE_SPHERE_TARGET_API_SET": "5" or "AZURE_SPHERE_TARGET_API_SET": "5+Beta2004"

If your app targets the latest API set, you can just set this variable to "latest-lts", if it isn't already. If your app targets the latest Beta API set, you can just set this variable to "latest-beta", if it isn't already. However, if your app targets an older API set, you need to set this variable to match the specific value it uses.

To specify the external AZURE_SPHERE_TARGET_API_SET variable in a Visual Studio project, set the following in the CMakeSettings.json file, within both the ARM-Debug and ARM-Release configurations:
```
"variables": [
  {
    "name": "AZURE_SPHERE_TARGET_API_SET",
    "value": "latest-beta"
  }
]
```
To specify the external AZURE_SPHERE_TARGET_API_SET variable in a Visual Studio Code project, set the following in the .vscode/settings.json file:
```
    "cmake.configureSettings": {
      "AZURE_SPHERE_TARGET_API_SET": "latest-lts"
  },
```
To specify the external AZURE_SPHERE_TARGET_API_SET variable on the command line, include the parameter when invoking CMake:

-DAZURE_SPHERE_TARGET_API_SET="latest-lts"

Replace "latest-lts" with "latest-beta" or a specific older value such as "4" or "5+Beta2004" as explained earlier.

Target API sets and OS compatibility

The compatibility of an application with the Azure Sphere OS depends on the target API set with which the application was built and the latest ARV that the OS version supports. A down-level application or OS uses an older ARV (which has a lower number), and an up-level application or OS uses a more recent ARV (which has a higher number). The following sections describe what to expect in each possible scenario.

Down-level applications with up-level OS

Existing down-level images that use only production APIs are supported on up-level versions of the Azure Sphere OS. For example, an application that was built with target API Set 1 runs successfully on an Azure Sphere OS that supports ARV 2. Thus, your existing deployed applications will continue to operate properly after cloud OS updates. You can either sideload or cloud-deploy down-level, production-only images to an up-level OS without error.

Down-level images that use Beta APIs are not supported, and may not work by design, on up-level versions of the Azure Sphere OS. For example, an application that was built with target API Set 1+Beta1902 might fail to run on an Azure Sphere OS that has ARV 2. Attempts to sideload such an image return an error unless you use the --force flag on the az sphere device sideload deploy command. Similarly, the az sphere image add command requires the --force flag to upload such an image. No current checks subsequently prevent a previously uploaded down-level image that uses Beta APIs from being deployed alongside an up-level OS that no longer supports those Beta APIs.

Up-level applications with down-level OS

Up-level applications cannot be deployed to down-level versions of the Azure Sphere OS, regardless of whether they use Beta APIs. Attempts to sideload such an image will fail with an error. Attempts to deploy over-the-air are not currently possible because the up-level SDK and OS are released simultaneously.

Share via