次の方法で共有

アプリケーションのランタイム バージョン、sysroot、およびベータ API

  • [アーティクル]

重要

これは Azure Sphere (レガシ) のドキュメントです。 Azure Sphere (レガシ) は 2027 年 9 月 27 日に 再提供されておりユーザーは現時点で Azure Sphere (統合) に移行する必要があります。 TOC の上にある Version セレクターを使用して、Azure Sphere (統合) のドキュメントを表示します。

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

ベータ機能には、ドキュメント BETA 機能 ラベルが付けられます。 Azure Sphere の高度なアプリケーションのすべてにおいて、運用 API のみをターゲットにするか、運用 API とベータ API の両方をターゲットにするかが指定されます。

Target API Set、ARV、sysroot

Target API Set では、アプリケーションが使用する API (運用 API のみ、または運用 API とベータ API) を指定します。 Target API Set 値は、アプリケーションのランタイム バージョン (ARV) を表す整数か、ベータ API リリースを識別する整数と文字列の組み合わせのいずれかです。 数値のみの場合、ARV の運用 API のみを示します。一方、"<値>+<ベータ番号>" は特定のリリースの運用およびベータ API を示します。 たとえば、ARV 8 は 21.01 リリースを示し、"8+ Beta2101" は 20.01 リリースの運用 API とベータ API を指定します。 今後のリリースでは、ARV が追加されます。

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

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

アプリケーションを Azure Sphere サンプルに基づいて作成した場合、既定でのターゲット API セットは、そのサンプルで使用されている API セットです。 サンプルで実稼働 API のみが使用されている場合、ターゲット API セットは現在の ARV 値に設定されます。 サンプルで、現在のリリースの実稼働およびベータ両方の API が使用されている場合、ターゲット API セットは "値+ベータ番号" になり、ベータ API が含まれます。

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

既にアプリケーションを作成している場合は、新しい OS リリース用にアプリをリビルドするときに、ターゲット API セットの変更が必要になることがあります。 ベータ API を使用するアプリは、Target API Set のオプションが変更されたとき (通常、これは機能リリースごとに発生) に、更新する必要があります。 ベータ API は、ベータ状態から運用状態に直接移行されて新しい ARV になることもあれば、変更されてそのままベータにとどまる場合もあります。 ベータ API を使用するアプリケーションを更新して、より新しいターゲット API セットをターゲットにすると、削除または廃止された API に関するエラーや警告が発生する可能性があります。

Target API Set を変更する場合は常に、アプリケーションをビルドする前に CMakeCache.txt ファイルを削除する必要があります。 このファイルは、プロジェクトの out\ARM-Debug または out\ARM-Release ディレクトリに格納されています。

Target API Set の指定

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 デバッグ構成と ARM リリース構成の両方で、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 との互換性は、アプリケーションを構築する際に使用した Target API Set と、OS のバージョンでサポートされている最新の ARV に依存します。 "下位レベル" のアプリケーションまたは OS ではより古い ARV (番号がより小さい) が使用され、"上位レベル" のアプリケーションまたは OS ではより新しい ARV (番号がより大きい) が使用されます。 次のセクションでは、考えられる各シナリオで期待されることについて説明します。

下位レベルのアプリケーションと上位レベルの OS

運用 API のみを使用する既存の下位レベルのイメージは、Azure Sphere OS の上位レベルでサポートされます。 たとえば、Target API Set 1 を使用して構築されたアプリケーションは、ARV 2 をサポートする Azure Sphere OS 上で正常に稼働します。 したがって、お使いのデプロイ済み既存アプリケーションは、クラウド OS の更新後も正常に動作し続けます。 下位レベルの運用のみのイメージは、上位レベルの OS にエラーなしでサイドロードまたはクラウド デプロイすることができます。

ベータ API を使用する下位レベルのイメージは、Azure Sphere OS の上位レベルのバージョンではサポートされず、動作しない設計になっている場合もあります。 たとえば、Target 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 は同時にリリースされるため、無線でデプロイする試みは現在不可能です。