使用 CMake 設定組建

發行項
11/05/2024

重要

這是 Azure Sphere （舊版）檔。 Azure Sphere（舊版）將於 2027 年 9 月 27 日淘汰，且使用者此時必須移轉至 Azure Sphere（整合式）。 使用位於 TOC 上方的版本選取器來檢視 Azure Sphere （整合式）檔。

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 的組態預設檔案。需要此檔案或CMakeSettings.json，才能使用Visual Studio進行建置。
CMakeSettings.json	Visual Studio 組態檔。需要此檔案或CMakePresets.json，才能使用Visual Studio進行建置。
CMakeWorkspaceSettings.json	具有多個根目錄之專案的Visual Studio組態檔，如IntercoreComms範例所示。
.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	建立映像套件。

如果您有使用 SDK 早於 20.04 建立的現有應用程式，請參閱轉換現有的應用程式以使用 CMake 函式。

CMakeLists.txt檔案必須在任何azsphere_函式之前呼叫專案命令。

目標硬體定義

您可以呼叫 azsphere_target_hardware_definition 函式，將值儲存在 CMakeLists.txt 中，以指定您要設定目標的硬體。此函式會採用兩個參數：要搜尋的目錄清單，以及要搜尋的檔名。例如：

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 檔案呼叫一次。

已淘汰的 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 Reconfigure 命令。
針對命令列（CLI）組建，請刪除您在先前步驟中建立的組建目錄。

Visual Studio 會偵測 CMake 組態檔的變更，並自動刪除快取。

轉換現有的應用程式以使用 CMake 函式

如果您已經有在 20.04 SDK 之前使用 CMake 建置的 Azure Sphere 應用程式，您應該將其轉換為使用這些新函式。您仍然可以針對目前未變更建置這類應用程式，但支援這些應用程式會受到限制，而且在未來版本中可能會移除。

如需您應該進行的變更範例，請查看 20.04 版外部 MCU Update 高階應用程式的CMakeLists.txt和 *.json組態檔如何變更。

注意

除了使用函式的更新之外，這些檔案已在 Azure Sphere 範例中更新為使用小寫函式名稱，因此符合 CMake 慣例。

CMakeLists.txt組態變更

下列範例顯示從 20.01 或更早版本更新CMakeLists.txt檔案以使用新函式所需的變更。

範例 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。開發環境會使用存在的檔案。請參閱每個範例專案，以查看使用哪一個檔案。如需使用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組態變更。

下列範例顯示從 20.01 或更早版本更新 Visual Studio 中CMakeSettings.json檔案以使用新函式所需的變更。

範例 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 來建置。不再需要AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY和AZURE_SPHERE_TARGET_HARDWARE_DEFINITION設定，因為這些值現在會在 CMakeLists.txt 檔案中設定。

{
  "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 組態

下列範例顯示從 20.01 或更早版本更新 Visual Studio Code 的 .vscode/settings.json 檔案以使用新函式所需的變更。

範例 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 設定AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY，因為這些值現在會在 CMakeLists.txt 檔案中設定。
CMAKE_TOOLCHAIN_FILE不再需要和 AZURE_SPHERE_TARGET_API_SET 設定，因為這些值現在會在 CMakePresets.json 檔案中設定。值 AZURE_SPHERE_TARGET_API_SET 現在 "latest-lts"為，表示項目應該使用最新的長期穩定（LTS） sysroot 來建置。

請注意， "cmake.configureArgs" 由於與 CMake 無關的原因，欄位也已刪除。（因為此組建不需要參數， --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檔案新增至專案的最上層資料夾。檔案有兩個專案，一個指定已啟用 CMake 建置，另一個專案包含多個根目錄的路徑。例如，針對 IntercoreComms 範例，CMakeWorkspaceSettings.json具有下列內容：

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

路徑會指定相對於包含CMakeWorkspaceSettings.json檔案的資料夾。

共用方式為