應用程式運行時間版本、sysroots 和 Beta API

發行項
09/27/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，並在後續版本中移至生產環境。 Beta API 提供新功能的早期存取權，並在完成之前啟用原型設計和意見反應。未來 Azure OS 和 SDK 版本之後，使用 Beta API 的應用程式通常需要修改，才能繼續正常運作。

Beta 功能會在文件中標示 為 BETA 功能 。每個 Azure Sphere 高階應用程式都會指定它只以生產 API 或生產與 Beta API 為目標。

目標 API 集合、ARV 和 sysroots

目標 API 集合會指出應用程式所使用的 API：僅限生產 API 或生產與 Beta API。目標 API 集合值是代表應用程式運行時間版本（ARV）或 ARV 加上識別 Beta API 版本的字串的整數。數值只會指定 ARV 中的生產 API，而「value+BetaNumber」則指定特定版本中的生產與 Beta API。例如，ARV 8 表示 21.01 版，而 “8+Beta2101” 會指定 20.01 版本中的生產與 Beta API。未來的版本將會新增額外的ARV。

Azure Sphere SDK 會使用 sysroots 實作多個 API 集合。 sysroot 會指定連結庫、頭檔，以及用來編譯及連結以特定 API 集合為目標的應用程式。 sysroots 會安裝在 sysroots 子資料夾中的 Microsoft Azure Sphere SDK 目錄中。

設定或更新高階應用程式的目標 API 集合

如果您根據 Azure Sphere 範例來建置應用程式，預設會設定目標 API 是範例所使用的 API 集合。如果範例只使用生產 API，目標 API 集合將會設定為目前的 ARV 值。如果範例針對目前版本同時使用生產與 Beta API，則目標 API 集合會是「value+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變數，請在 ARM-Debug 和 ARM-Release 組態中，在 CMakeSettings.json 檔案中設定下列專案：
```
"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，而不會發生錯誤。

在 Azure Sphere OS 的上層版本上，不支援使用 Beta API 的下層映射，而且可能無法依設計運作。例如，以目標 API 集合 1+Beta1902 建置的應用程式可能無法在具有 ARV 2 的 Azure Sphere OS 上執行。除非您在 --force azsphere device sideload deploy 命令上使用旗標，否則嘗試側載這類映射會傳回錯誤。同樣地， azsphere image add 命令需要 --force 旗標才能上傳這類影像。後續不會進行目前的檢查，防止先前上傳的下層映像使用 Beta API 與不再支持這些 Beta API 的上層 OS 一起部署。

具有下層 OS 的上層應用程式

不論其是否使用 Beta API，上層應用程式都無法部署到 Azure Sphere OS 的下層版本。嘗試側載這類映像將會失敗，並出現錯誤。目前無法透過無線方式部署嘗試，因為同時發行上層 SDK 和 OS。

共用方式為