CMake を使用してビルドを構成する

[アーティクル]
03/27/2024

Azure Sphere では、CMake を使用して、Visual Studio、Visual Studio Code、および Windows および Linux のコマンドラインを使用してアプリケーションのビルドを構成します。 CMake はオープンソースのクロスプラットフォームメイクシステムです。 CMake に関する一般的な情報については、 CMake Wiki を参照してください。

次のソースは、Visual Studio または Visual Studio Code での CMake の使用に関する情報を提供します。

CMake ビルドでは、次のファイルが使用されます。

ファイル	目的
CMakeLists.txt	一般的な CMake 構成ファイル。すべてのビルドに必要です。
CMakePresets.json	Visual Studio および Visual Studio Code 用の構成プリセットファイル。 Visual Studio を使用してビルドするには、このファイルまたはCMakeSettings.jsonが必要です。
CMakeSettings.json	Visual Studio 構成ファイル。 Visual Studio を使用してビルドするには、このファイルまたはCMakePresets.jsonが必要です。
CMakeWorkspaceSettings.json	IntercoreComms サンプルのように、複数のルートを持つプロジェクトの Visual Studio 構成ファイル。
.vscode/settings.json	Visual Studio Code 構成ファイル。 Visual Studio Code を使用したビルドに必要です。

CMake パラメーターはスペースで区切られます。 Windows コマンドラインの行継続文字 "^"、Linux コマンドラインの場合は " \ "、Powershell の場合は "'" は読みやすくするために使用できますが、必須ではありません。特定の文字は、Windows または Linux のターミナル構成によって決まります。

Azure Sphere の CMake 関数

CMakeLists.txt ファイルには、CMake がアプリケーションのビルドに使用する一般的な構成設定が用意されています。 Azure Sphere では、CMakeLists.txt で次の関数の使用がサポートされています。

名前	目的
azsphere_target_hardware_definition	ターゲットハードウェアを指定します。
azsphere_target_add_image_package	イメージパッケージを作成します。

20.04 より前の SDK で作成された既存のアプリケーションがある場合は、「 CMake 関数を使用するように既存のアプリを変換する」を参照してください。

CMakeLists.txt ファイルは、azsphere_関数の前に project コマンドを呼び出す必要があります。

ターゲットハードウェア定義

ターゲットとするハードウェアを指定するには、azsphere_target_hardware_definition関数を呼び出して値を CMakeLists.txt に格納します。この関数は、検索するディレクトリの一覧と検索するファイル名の 2 つのパラメーターを受け取ります。例えば：

azsphere_target_hardware_definition(${PROJECT_NAME} TARGET_DIRECTORY "<path>/my_app/contoso_hardware_definitions" "<path>/my_app/test_hardware" TARGET_DEFINITION "contoso_board.json")

TARGET_DEFINITION パラメーターが必要です。アプリケーションで必要なハードウェア定義ファイルの名前を指定します。 TARGET_DIRECTORY パラメーターには、このファイルを検索するディレクトリが一覧表示されます。このパラメーターは省略可能です。省略した場合、CMake は SDK インストールの HardwareDefinitions フォルダーでのみ検索されます。複数のフォルダーを指定するには、各フォルダー名を二重引用符で囲み、例のようにスペースを使用してフォルダー名を区切ります。この例では、path> は開発<用コンピューター上のmy_app フォルダーへのパスを表します。

イメージパッケージの作成

ビルド時に含めるイメージパッケージファイルとリソースファイルを指定するには、 azsphere_target_add_image_package 関数を呼び出して値を CMakeLists.txt に格納します。 azsphere_target_add_image_package関数とビルドするプロジェクトが必要です。リソースファイルは省略可能です。

次の関数呼び出しでは、Azure Sphere アプリケーションのみを含むイメージパッケージが作成されます。

azsphere_target_add_image_package(${PROJECT_NAME})

次の例では、アプリケーションに加えて証明書を含むイメージパッケージを作成します。

azsphere_target_add_image_package(${PROJECT_NAME} RESOURCE_FILES "certs/bundle.pem")

azsphere_target_add_image_packageに渡される CMake ターゲットは ${PROJECT_NAME}という名前にする必要があり、azsphere_target_add_image_package関数は CMakeLists.txt ファイルから 1 回だけ呼び出すことができます。

非推奨の CMake 関数

SDK バージョン 24.03 より前では、CMake 関数 azsphere_configure_tools と azsphere_configure_api を使用して、CMakeLists.txt ファイルでターゲット SDK ツールのバージョンとターゲット API セットを指定していました。これらの関数は非推奨になり、代わりにターゲット API セットを適切な構成ファイルに指定する必要があります。詳細については、アプリケーションランタイムのバージョン、sysroots、Beta API の各ページを参照してください。

古いバージョンの SDK を使用していて、サポートされていないツールリビジョンに関する CMake 構成エラーが表示される場合は、それらの関数を CMakeLists.txt に再追加することで回避できます。例として、

azsphere_configure_tools(TOOLS_REVISION 23.05) azsphere_configure_api(TARGET_API_SET 16)

構成ファイルを変更するときに CMake キャッシュを削除する方法

構成ファイルのいずれかを変更する場合は、後続のビルドが失敗しないように CMake キャッシュを削除する必要があります。別のビルドを試みる前に、次の手順に従います。

Visual Studio Code ビルドの場合は、コマンドパレットから CMake:Delete Cache and Configure コマンドを実行します。
コマンドライン (CLI) ビルドの場合は、前の手順で作成したビルドディレクトリを削除します。

Visual Studio は CMake 構成ファイルの変更を検出し、キャッシュを自動削除します。

CMake 関数を使用するように既存のアプリを変換する

20.04 SDK より前の CMake でビルドされた Azure Sphere アプリケーションが既にある場合は、これらの新しい関数を使用するように変換する必要があります。現時点では、このようなアプリケーションは変更せずにビルドできますが、サポートは限られており、今後のリリースで削除される可能性があります。

行う必要がある変更の例については、20.04 リリースの外部 MCU Update 高レベルアプリの CMakeLists.txt および *.json構成ファイルがどのように変更されたかを確認してください。

メモ

関数を使用するための更新に加えて、これらのファイルは、小文字の関数名を使用するように Azure Sphere サンプルで更新されているため、CMake 規則に合わせて更新されています。

CMakeLists.txt 構成の変更

次の例は、新しい関数を使用するために、CMakeLists.txt ファイルを 20.01 以前から更新するために必要な変更を示しています。

例 20.01 SDK CMakeLists.txt ファイル

CMAKE_MINIMUM_REQUIRED(VERSION 3.8)
PROJECT(ExternalMcuUpdateNrf52 C)

ADD_EXECUTABLE(${PROJECT_NAME} main.c file_view.c mem_buf.c epoll_timerfd_utilities.c nordic/slip.c nordic/crc.c nordic/dfu_uart_protocol.c)
TARGET_LINK_LIBRARIES(${PROJECT_NAME} applibs pthread gcc_s c)

SET(ADDITIONAL_APPROOT_INCLUDES "ExternalNRF52Firmware/blinkyV1.bin;ExternalNRF52Firmware/blinkyV1.dat;ExternalNRF52Firmware/s132_nrf52_6.1.0_softdevice.bin;ExternalNRF52Firmware/s132_nrf52_6.1.0_softdevice.dat")
INCLUDE("${AZURE_SPHERE_MAKE_IMAGE_FILE}")

CMakeLists.txt ファイルを更新しました

更新された CMakeLists.txt ファイルは 、ターゲット ハードウェアを設定するためにazsphere_target_hardware_definition関数を呼び出します。また、 azsphere_target_add_image_package を呼び出してイメージパッケージをビルドし、必要に応じてそれに含めるファイルを指定します。

cmake_minimum_required(VERSION 3.20)

project(ExternalMcuUpdateNrf52 C)

add_executable(${PROJECT_NAME} main.c file_view.c mem_buf.c epoll_timerfd_utilities.c nordic/slip.c nordic/crc.c nordic/dfu_uart_protocol.c)
target_link_libraries(${PROJECT_NAME} applibs pthread gcc_s c)

azsphere_target_hardware_definition(${PROJECT_NAME} TARGET_DIRECTORY "../../../HardwareDefinitions/mt3620_rdb" TARGET_DEFINITION "sample_hardware.json")

azsphere_target_add_image_package(
    ${PROJECT_NAME}
    RESOURCE_FILES
        "ExternalNRF52Firmware/blinkyV1.bin"
        "ExternalNRF52Firmware/blinkyV1.dat"
        "ExternalNRF52Firmware/s132_nrf52_6.1.0_softdevice.bin"
        "ExternalNRF52Firmware/s132_nrf52_6.1.0_softdevice.dat")

メモ

絶対パスは、RESOURCE_FILESではサポートされていません。

Visual Studio CMakePresets.json構成

CMakePresets.json ファイルを使用すると、一般的な構成、ビルド、テストの各オプションを指定し、他の開発環境を使用して開発者と共有できます。たとえば、同じプリセット構成ファイルを使用して、Visual Studio、Visual Studio Code、継続的インテグレーションパイプライン、または Windows、Linux、または macOS 上の CLI から CMake を呼び出すことができます。

リリース 22.07 の時点で、現在のプロジェクトではCMakePresets.jsonで定義されているプリセットが使用されますが、既存のプロジェクトでは引き続きCMakeSettings.jsonの設定を使用できます。サンプルには、CMakePresets.jsonまたはCMakeSettings.jsonのいずれかの構成ファイルが 1 つだけ付属しています。開発環境では、存在するファイルが使用されます。使用されているファイルを確認するには、各サンプルプロジェクトを参照してください。 CMakeSettings.jsonを使用するプロジェクトについては、「 Visual Studio CMakeSettings.json構成の変更」を参照してください。

高度なアプリケーションとリアルタイムアプリケーション用のCMakePresets.json ファイルは非常によく似ています。唯一の違いは、 CMAKE_TOOLCHAIN_FILE 変数と ARM_GNU_PATH 変数です。

大まかなアプリケーションでは、 ARM_GNU_PATH は設定されず、 CMAKE_TOOLCHAIN_FILE 次のように設定されます。

    "CMAKE_TOOLCHAIN_FILE": "$env{AzureSphereDefaultSDKDir}/CMakeFiles/AzureSphereToolchain.cmake",

リアルタイムアプリケーションでは、 CMAKE_TOOLCHAIN_FILE と ARM_GNU_PATH は次のように設定されます。

    "CMAKE_TOOLCHAIN_FILE": "$env{AzureSphereDefaultSDKDir}/CMakeFiles/AzureSphereRTCoreToolchain.cmake",
    "ARM_GNU_PATH": "$env{ArmGnuPath}"

Visual Studio CMakeSettings.json構成

サンプルには、CMakePresets.jsonまたはCMakeSettings.json構成ファイルが付属しています。使用されているファイルを確認するには、各プロジェクトを参照してください。このセクションでは、CMakeSettings.json構成について説明します。 CMakePresets.jsonを使用するプロジェクトについては、「 Visual Studio CMakePresets.json構成の変更」を参照してください。

次の例では、新しい関数を使用するために Visual Studio の CMakeSettings.json ファイルを 20.01 以前から更新するために必要な変更を示します。

例 20.01 SDK CMakeSettings.json ファイル

{
  "environments": [
    {
      "environment": "AzureSphere",
      "AzureSphereTargetApiSet": "4",
      "AzureSphereTargetHardwareDefinitionDirectory": "${projectDir}\\..\\..\\..\\Hardware\\mt3620_rdb",
      "AzureSphereTargetHardwareDefinition": "sample_hardware.json"
    }
  ],
  "configurations": [
    {
      "name": "ARM-Debug",
      "generator": "Ninja",
      "configurationType": "Debug",
      "inheritEnvironments": [
        "AzureSphere"
      ],
      "buildRoot": "${projectDir}\\out\\${name}-${env.AzureSphereTargetApiSet}",
      "installRoot": "${projectDir}\\install\\${name}-${env.AzureSphereTargetApiSet}",
      "cmakeCommandArgs": "--no-warn-unused-cli",
      "buildCommandArgs": "-v",
      "ctestCommandArgs": "",
      "variables": [
        {
          "name": "CMAKE_TOOLCHAIN_FILE",
          "value": "${env.AzureSphereDefaultSDKDir}CMakeFiles\\AzureSphereToolchain.cmake"
        },
        {
          "name": "AZURE_SPHERE_TARGET_API_SET",
          "value": "${env.AzureSphereTargetApiSet}"
        },
        {
          "name": "AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY",
          "value": "${env.AzureSphereTargetHardwareDefinitionDirectory}"
        },
        {
          "name": "AZURE_SPHERE_TARGET_HARDWARE_DEFINITION",
          "value": "${env.AzureSphereTargetHardwareDefinition}"
        }
      ]
    },
    {
      "name": "ARM-Release",
      "generator": "Ninja",
      "configurationType": "Release",
      "inheritEnvironments": [
        "AzureSphere"
      ],
      "buildRoot": "${projectDir}\\out\\${name}-${env.AzureSphereTargetApiSet}",
      "installRoot": "${projectDir}\\install\\${name}-${env.AzureSphereTargetApiSet}",
      "cmakeCommandArgs": "--no-warn-unused-cli",
      "buildCommandArgs": "-v",
      "ctestCommandArgs": "",
      "variables": [
        {
          "name": "CMAKE_TOOLCHAIN_FILE",
          "value": "${env.AzureSphereDefaultSDKDir}CMakeFiles\\AzureSphereToolchain.cmake"
        },
        {
          "name": "AZURE_SPHERE_TARGET_API_SET",
          "value": "${env.AzureSphereTargetApiSet}"
        },
        {
          "name": "AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY",
          "value": "${env.AzureSphereTargetHardwareDefinitionDirectory}"
        },
        {
          "name": "AZURE_SPHERE_TARGET_HARDWARE_DEFINITION",
          "value": "${env.AzureSphereTargetHardwareDefinition}"
        }
      ]
    }
  ]
}

SDK CMakeSettings.json ファイルを更新しました

更新されたCMakeSettings.json ファイルには、次の変更が含まれます。

[環境] フィールドでは、"Azure Sphere" のみが必要です。
デバッグビルドとリリースビルドの両方の [構成] フィールドで、次の手順を実行します。
- "buildRoot" と "installRoot" の値には、AzureSphereTargetApiSet 設定は不要です。
- CMake ツールチェーンは、"変数" ではなく "cmakeToolChain" で定義されるようになりました。
- "variables" フィールドはターゲット API セットのみを指定し、新しい "latest-lts" 値を使用して、プロジェクトが最新の長期安定 (LTS) sysroot でビルドする必要があることを示します。これらの値はCMakeLists.txt ファイルに設定されているため、 AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORYとAZURE_SPHERE_TARGET_HARDWARE_DEFINITIONの設定は不要になりました。

{
  "environments": [
    {
      "environment": "AzureSphere"
    }
  ],
  "configurations": [
    {
      "name": "ARM-Debug",
      "generator": "Ninja",
      "configurationType": "Debug",
      "inheritEnvironments": [
        "AzureSphere"
      ],
      "buildRoot": "${projectDir}\\out\\${name}",
      "installRoot": "${projectDir}\\install\\${name}",
      "cmakeToolchain": "${env.AzureSphereDefaultSDKDir}CMakeFiles\\AzureSphereToolchain.cmake",
      "buildCommandArgs": "-v",
      "ctestCommandArgs": "",
      "variables": [
        {
          "name": "AZURE_SPHERE_TARGET_API_SET",
          "value": "latest-lts"
        }
      ]
    },
    {
      "name": "ARM-Release",
      "generator": "Ninja",
      "configurationType": "Release",
      "inheritEnvironments": [
        "AzureSphere"
      ],
      "buildRoot": "${projectDir}\\out\\${name}",
      "installRoot": "${projectDir}\\install\\${name}",
      "cmakeToolchain": "${env.AzureSphereDefaultSDKDir}CMakeFiles\\AzureSphereToolchain.cmake",
      "buildCommandArgs": "-v",
      "ctestCommandArgs": "",
      "variables": [
        {
          "name": "AZURE_SPHERE_TARGET_API_SET",
          "value": "latest-lts"
        }
      ]
    }
  ]
}

Visual Studio Code .vscode/settings.json 構成

次の例は、新しい関数を使用するために Visual Studio Code の .vscode/settings.json ファイルを 20.01 以前から更新するために必要な変更を示しています。

例 20.01 SDK .vscode/settings.json ファイル

{
    "cmake.generator": "Ninja",
    "cmake.buildDirectory": "${workspaceRoot}/out/${buildType}-${command:azuresphere.AzureSphereTargetApiSet}",
    "cmake.buildToolArgs": [ "-v" ],
    "cmake.configureArgs": [ "--no-warn-unused-cli" ],
    "cmake.configureSettings": {
        "CMAKE_TOOLCHAIN_FILE": "${command:azuresphere.AzureSphereSdkDir}/CMakeFiles/AzureSphereToolchain.cmake",
        "AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY": "${workspaceRoot}/../../../HardwareDefinitions/mt3620_rdb",
        "AZURE_SPHERE_TARGET_HARDWARE_DEFINITION": "sample_hardware.json",
        "AZURE_SPHERE_TARGET_API_SET": "4"
    },
    "cmake.configureOnOpen": true,
    "C_Cpp.default.configurationProvider": "vector-of-bool.cmake-tools"
}

.vscode/settings.json ファイルを更新しました

.vscode/settings.json ファイルには、Visual Studio Code のワークスペース設定が含まれています。

更新されたsettings.json ファイルには、"cmake.configureSettings" フィールドに対する次の変更が含まれています。

AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORYこれらの値は CMakeLists.txt ファイルに設定されているため、と AZURE_SPHERE_TARGET_HARDWARE_DEFINITION の設定は不要になりました。
CMAKE_TOOLCHAIN_FILEこれらの値は CMakePresets.json ファイルに設定されているため、と AZURE_SPHERE_TARGET_API_SET の設定は不要になりました。値は AZURE_SPHERE_TARGET_API_SET になりました "latest-lts"。これは、プロジェクトが最新の長期安定 (LTS) sysroot を使用してビルドする必要があることを示します。

CMake に "cmake.configureArgs" 関係のない理由で、フィールドも削除されていることに注意してください。 (このビルドではパラメーターが必要ないため --no-warn-unused-cli 、フィールドは不要になりました)。

拡張機能には、次のフィールドが適用されます。

"cmake.configureOnOpen": true は、ワークスペースが開いたときに構成を開始するように cmake-tools 拡張機能に通知します。
"C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools"は、cpp-tools 拡張機能に使用する IntelliSense プロバイダーを指定します。この場合は、cmake-tools 拡張機能が使用されます。

{
    "cmake.generator": "Ninja",
    "cmake.buildDirectory": "${workspaceRoot}/out/${buildType}-${command:azuresphere.AzureSphereTargetApiSet}",
    "cmake.buildToolArgs": [ "-v" ]
    },
    "cmake.configureOnOpen": true,
    "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools"
}

CMakeWorkspaceSettings.json ファイルの作成

Visual Studio 2022 バージョン 17.1 以降を使用していて、 IntercoreComms サンプルなどの複数のルートを持つプロジェクトがある場合は、プロジェクトの最上位フォルダーにCMakeWorkspaceSettings.json ファイルを追加する必要があります。ファイルには 2 つのエントリがあります。1 つは CMake ビルドが有効になっていることを指定し、もう 1 つは複数のルートへのパスを含みます。たとえば、IntercoreComms サンプルの場合、CMakeWorkspaceSettings.jsonには次の内容があります。

{
  "enableCMake": true,
  "sourceDirectory": [ "IntercoreComms_HighLevelApp", "IntercoreComms_RTApp_MT3620_BareMetal" ]
}

パスは、CMakeWorkspaceSettings.json ファイルを含むフォルダーを基準にして指定されます。