使用 CMake 設定組建

Azure 球體使用 CMake 來設定使用 Visual Studio、Visual Studio Code，以及 Windows 和 Linux 命令行的應用程式組建。 CMake 是開放原始碼的跨平臺製作系統。 如需 CMake 的一般資訊，請參閱 CMake Wiki。

下列來源提供搭配 Visual Studio 或 Visual Studio Code 使用 CMake 的相關信息：

• Visual Studio 中的 CMake 專案
• Visual Studio Code 的 CMake Tools 擴充功能

CMake 組建使用下列檔案：

檔	目的
CMakeLists.txt	一般 CMake 組態檔。 所有組建皆為必要。
CMakePresets.json	Visual Studio 和 Visual Studio Code 的組態預設檔。 若要使用 Visual Studio 建置此檔案或CMakeSettings.json，都需要此檔案或CMakeSettings.json。
CMakeSettings.json	Visual Studio 組態檔。 使用 Visual Studio 建置此檔案或CMakePresets.json需要此檔案或CMakePresets.json。
CMakeWorkspaceSettings.json	適用於具有多個根源之專案的Visual Studio組態檔，如 IntercoreComms範例所示。
.vscode/settings.json	Visual Studio Code 組態檔。 使用 Visual Studio Code 建置時需要。

CMake 參數會以空格分隔。 Windows 命令行的線條延續字元 “^”、Linux 命令行的 \ “ 或 Powershell 的 ”'“ 可用於可讀性，但不需要。 特定字元是由 Windows 或 Linux 終端機組態決定。

Azure 球體的 CMake 函數

CMakeLists.txt 檔案提供 CMake 用來建立應用程式的一般組態設定。 Azure 球體支援在 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 球體應用程式的影像套件：

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 快取和重新設定命令。
• 對於 CLI) 組建 (命令行，請刪除您在先前步驟中建立的組建目錄。

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

將現有的應用程式轉換成使用 CMake 函數

如果您已經有在 20.04 SDK 之前使用 CMake 所建置的 Azure 球體應用程式，您應該將其轉換成使用這些新函數。 您目前仍可建立這類應用程式，但支援有限，可能會在未來版本中移除。

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

注意

除了使用函數的更新，這些檔案已在 Azure 球體樣本中更新，以使用小寫函數名稱，因此與 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_FILEARM_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 中從 20.01 或更舊版本更新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 球體」。
• 在偵錯和發行組建的 [設定] 欄位中：
  • “buildRoot” 和 “installRoot” 值不再需要 AzureSphereTargetApiSet 設定。
  • CMake 工具鏈現在定義為 「cmakeToolChain」，而非「變數」。
  • 「變數」字段現在只會指定目標 API 集，並使用新的「最新-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_DIRECTORY 需要這些和 AZURE_SPHERE_TARGET_HARDWARE_DEFINITION 設定，因為這些值現在已設定在 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 工具 擴充功能，以便在工作區開啟時開始設定。

• "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools" 指定 IntelliSense 提供者用於 cpp 工具 擴充功能;在此情況下， Cmake 工具 擴充功能。

{
    "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檔案的資料夾所指定。