应用程序运行时版本、sysroot 和 Beta API

项目
11/05/2024

重要

这是 Azure Sphere（旧版）文档。 Azure Sphere（旧版）将于 2027 年 9 月 27 日停用，用户此时必须迁移到 Azure Sphere（集成）。 使用位于 TOC 上方的版本选择器查看 Azure Sphere（集成）文档。

Azure Sphere SDK 版本可能同时包含生产 API 和 Beta API。生产 API 被认为是长期稳定的 (LTS)，而 Beta API 则仍在开发中，可能会在以后的版本中更改或删除。在大多数情况下，新 API 在其第一个版本中会标记为 Beta，在后续版本中改为生产 API。通过 Beta API 可以提前访问新功能，以便在最终推出新 API 之前进行原型制作和获得反馈。将来发行新的 Azure OS 和 SDK 版本后，使用 Beta API 的应用程序通常需要经过修改才能继续正常工作。

Beta 功能在文档中标记为 BETA 功能 。每个 Azure Sphere 高级应用程序都会指定它是只面向生产 API，还是同时面向生产和 Beta API。

目标 API 集、ARV 和 sysroot

目标 API 集指示应用程序使用哪些 API：仅生产 API，或生产和 Beta API。 “目标 API 集”值是一个表示应用程序运行时版本 (ARV) 的整数，或者是 ARV 加上一个标识 Beta API 版本的字符串。该数值单独指定 ARV 中的生产 API，而“value+BetaNumber”指定特定版本中的生产和 Beta API。例如，ARV 8 指示 21.01 版本，“8+Beta2101”指定 20.01 版本中的生产 API 和 Beta API。未来版本会添加其他 ARV。

Azure Sphere SDK 使用 sysroot 实现多个 API 集。 sysroot 指定所需的库、标头文件和工具，用于编译和链接面向特定 API 集的应用程序。 sysroot 安装在 Microsoft Azure Sphere SDK 目录中的 sysroots 子文件夹内。

设置或更新高级应用的目标 API 集

如果让应用程序基于 Azure Sphere 示例，则默认情况下，设置的目标 API 是该示例使用的 API 集。如果该示例只使用生产 API，则目标 API 集将设置为当前的 ARV 值。如果该示例对当前版本使用生产版和 Beta 版 API，则目标 API 集将为“值+BetaNumber”，这样就可以包含 Beta API。

如果不让应用程序基于示例，则需在应用的生成说明中设置目标 API 集。

如果已创建应用程序，则在为新的 OS 版本重新生成应用的情况下，可能需要更改目标 API 集。如果应用使用 Beta API，则应在目标 API 集选项更改（通常在每个功能发布时发生）时进行更新。 Beta API 可以直接从 Beta 状态变为生产状态，从而产生新的 ARV，或者可以改变并保持 Beta 状态。如果更新使用 Beta API 以面向较新的目标 API 集的应用程序，则可能会遇到有关已删除或停用 API 的错误或警告。

无论何时更改目标 API 集，都需要在生成应用程序之前删除 CMakeCache.txt 文件。此文件存储在项目的 out\ARM-Debug 或 out\ARM-Release 目录中。

指定目标 API 集

在CMakePresets.json中设置目标 API：

使用“AZURE_SPHERE_TARGET_API_SET”配置目标 API 集。例如：

"AZURE_SPHERE_TARGET_API_SET": "5" 或 "AZURE_SPHERE_TARGET_API_SET": "5+Beta2004"

如果应用面向最新的 API 集，则只需将此变量设置为“latest-lts”（如果尚未设置）。如果应用面向最新的 Beta API 集，则只需将此变量设置为“latest-beta”（如果尚未设置）。但是，如果应用针对较旧的 API 集，则需将此变量设置为与它使用的特定值匹配。

若要在 Visual Studio 项目中指定外部 AZURE_SPHERE_TARGET_API_SET 变量，请在 CMakeSettings.json 文件的 ARM-Debug 和 ARM-Release 配置中进行以下设置：
```
"variables": [
  {
    "name": "AZURE_SPHERE_TARGET_API_SET",
    "value": "latest-beta"
  }
]
```
若要在 Visual Studio Code 项目中指定外部 AZURE_SPHERE_TARGET_API_SET 变量，请在 .vscode/settings.json 文件中设置以下内容：
```
    "cmake.configureSettings": {
      "AZURE_SPHERE_TARGET_API_SET": "latest-lts"
  },
```
若要在命令行上指定外部 AZURE_SPHERE_TARGET_API_SET 变量，请在调用 CMake 时包含此参数：

-DAZURE_SPHERE_TARGET_API_SET="latest-lts"

如前所述，将“latest-lts”替换为“latest-beta”或某个具体的较旧值（例如“4”或“5+Beta2004”）。

目标 API 集和 OS 兼容性

应用程序与 Azure Sphere OS 的兼容性取决于生成应用程序所用的目标 API 集和 OS 版本所支持的最新 ARV。下层应用程序或 OS 使用较旧的 ARV（其数值较小），而上层应用程序或 OS 使用较新的 ARV（其数值较大）。以下部分描述了每个可能场景中应使用的项。

具有高级 OS 的下层应用程序

仅使用生产 API 的现有下层映像可以在 Azure Sphere OS 的上层版本上运行。例如，使用目标 API 集 1 生成的应用程序在支持 ARV 2 的 Azure Sphere OS 上成功运行。因此，更新云 OS 之后，现有的已部署应用程序将继续正常运行。可以将下层仅生产映像旁加载或云部署到上层 OS，且不会出现错误。

使用 Beta API 的下层映像不受支持，根据设计，可能无法在 Azure Sphere OS 的上层版本上运行。例如，使用目标 API 集 1+Beta1902 生成的应用程序可能无法在具有 ARV 2 的 Azure Sphere OS 上运行。除非在 --force azsphere device sideload deploy 命令上使用标志，否则尝试旁加载此类映像将返回错误。同样， azsphere image add 命令要求 --force 标志上传此类图像。当前检查随后无法阻止先前上传的下层映像（从部署开始即使用 Beta API）以及上层 OS（不再支持这些 Beta API）。

具有下层 OS 的上层应用程序

上层应用程序不能部署到 Azure Sphere OS 的下层版本，无论它们是否使用 Beta API。尝试旁加载此类映像将失败，并出现错误。由于同时发布了上层 SDK 和 OS，因此目前不可能尝试进行无线部署。

通过