アプリケーション ランタイム バージョン、sysroots、Beta API

Azure Sphere SDK リリースには、運用 API とベータ API の両方が含まれている場合があります。 運用 API は長期安定 (LTS) と見なされますが、ベータ API はまだ開発中であり、後のリリースで変更されたり、削除されたりする可能性があります。 ほとんどの場合、新しい API は最初のリリースで Beta とマークされ、後続のリリースで運用環境に移行されます。 ベータ API は、新機能への早期アクセスを提供し、プロトタイプ作成とフィードバックを完了する前に可能にします。 ベータ API を使用するアプリケーションでは、通常、今後の Azure OS および SDK リリースが正常に動作し続けるために、変更が必要になります。

ベータ機能には、ドキュメントの BETA 機能 というラベルが付けられます。 すべての Azure Sphere の高レベル アプリケーションでは、運用 API のみを対象にするか、運用環境とベータ API の両方を対象にするかを指定します。

ターゲット API セット、ARV、および sysroots

ターゲット API セットは、アプリケーションが使用する API (運用 API のみまたは運用 API とベータ API) を示します。 ターゲット API セットの値は、アプリケーション ランタイム バージョン (ARV) を表す整数か、ARV と Beta API リリースを識別する文字列のいずれかです。 数値だけでは ARV の運用 API のみを指定しますが、"value+BetaNumber" は特定のリリースの運用 API と Beta API を指定します。 たとえば、ARV 8 は 21.01 リリースを示し、"8+Beta2101" は 20.01 リリースの運用 API とベータ API を指定します。 今後のリリースでは、ARV が追加される予定です。

Azure Sphere SDK は 、sysroots を使用して複数の API セットを実装します。 sysroot は、特定の API セットを対象とするアプリケーションのコンパイルとリンクに使用されるライブラリ、ヘッダー ファイル、およびツールを指定します。 sysroots は、sysroots サブフォルダーの Microsoft Azure Sphere SDK ディレクトリにインストールされます。

高度なアプリのターゲット API セットを設定または更新する

Azure Sphere サンプルに基づいてアプリケーションを作成する場合、既定で設定されるターゲット API セットは、サンプルで使用される API セットです。 サンプルで運用 API のみを使用する場合、ターゲット API セットは現在の ARV 値に設定されます。 サンプルで現在のリリースで運用 API とベータ API の両方が使用されている場合、ターゲット API セットは "value+BetaNumber" になり、ベータ API が含まれます。

サンプルに基づいてアプリケーションを作成しない場合は、アプリのビルド手順でターゲット API セットを設定する必要があります。

アプリケーションを既に作成している場合は、新しい OS リリース用にアプリをリビルドする場合は、ターゲット API セットの変更が必要になる場合があります。 アプリでベータ API を使用する場合は、ターゲット API セット のオプションが変更されたときに更新する必要があります。これは通常、各機能リリースで発生します。 ベータ API は、ベータ状態から運用環境に直接移動され、新しい ARV が発生する場合や、変更されてベータ版のままになる場合があります。 ベータ 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" に設定できます (まだ設定されていない場合)。 アプリが最新のベータ 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 を使用する下位レベルのアプリケーション

実稼働 API のみを使用する既存の下位レベルのイメージは、Azure Sphere OS のアップレベル バージョンでサポートされています。 たとえば、ターゲット API Set 1 を使用してビルドされたアプリケーションは、ARV 2 をサポートする Azure Sphere OS で正常に実行されます。 そのため、既存のデプロイ済みアプリケーションは、クラウド OS の更新後も引き続き正常に動作します。 ダウンレベルの実稼働専用イメージを、エラーなしで上位レベルの OS にサイドロードまたはクラウドデプロイできます。

ベータ API を使用する下位レベルのイメージは、Azure Sphere OS の上位バージョンではサポートされておらず、設計上は機能しない可能性があります。 たとえば、ターゲット API Set 1 + Beta1902 を使用してビルドされたアプリケーションは、ARV 2 を持つ Azure Sphere OS で実行できない場合があります。 azsphere device sideload deploy コマンドでフラグを使用--forceしない限り、このようなイメージをサイドロードしようとするとエラーが返されます。 同様に、 azsphere image add コマンドでは、そのようなイメージを --force アップロードするためのフラグが必要です。 現在のチェックでは、ベータ API を使用する以前にアップロードされたダウンレベルのイメージが、それらのベータ API をサポートしなくなった上位レベルの OS と共にデプロイされるのを防ぐ必要はありません。

下位レベルの OS を使用した上位レベルのアプリケーション

ベータ API を使用するかどうかに関係なく、上位レベルのアプリケーションを下位レベルのバージョンの Azure Sphere OS にデプロイすることはできません。 このようなイメージをサイドロードしようとすると、エラーで失敗します。 アップレベルの SDK と OS が同時にリリースされるため、現在、空中展開を試みることはできません。