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

项目
03/27/2024

Azure Sphere SDK 版本可能包含生产 API 和 Beta API。生产 API 被视为长期稳定的 (LTS) ，而 Beta API 仍在开发中，可能会在更高版本中更改或从中删除。在大多数情况下，新 API 在其第一个版本中标记为 Beta，并在后续版本中移动到生产环境。 Beta API 提供对新功能的早期访问，从而在最终完成之前实现原型制作和反馈。在未来的 Azure OS 和 SDK 版本发布后，使用 Beta API 的应用程序通常需要进行修改才能继续正常工作。

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

目标 API 集、ARV 和 sysroot

目标 API 集指示应用程序使用的 API：仅限生产 API 或生产 API 和 Beta API。目标 API 集值可以是表示应用程序运行时版本 (ARV) 的整数，要么是 ARV 加上标识 Beta API 版本的字符串。数值仅指定 ARV 中的生产 API，而“value+BetaNumber”则指定特定版本中的生产 API 和 Beta API。例如，ARV 8 指示 21.01 版本，“8+Beta2101”指定 20.01 版本中的生产 API 和 Beta API。未来的版本将添加其他 AAV。

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

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

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

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

如果已创建应用程序，则可能需要更改目标 API 集（如果为新的 OS 版本重新生成应用）。如果应用使用 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 的下层应用程序

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

使用 Beta API 的下层映像在 Azure Sphere OS 的上层版本中不受支持，并且可能无法按设计工作。例如，使用目标 API 集 1+Beta1902 生成的应用程序可能无法在具有 ARV 2 的 Azure Sphere OS 上运行。尝试旁加载此类映像将返回错误， --force 除非在 az sphere device sideload deploy 命令上使用标志。同样， az sphere image add 命令需要标志 --force 来上传此类图像。当前检查会阻止以前上传的使用 Beta API 的下层映像与不再支持这些 Beta API 的上层 OS 一起部署。

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

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

通过