使用 CMake 配置生成

重要

这是 Azure Sphere（旧版）文档。 Azure Sphere（旧版）将于 2027 年 9 月 27 日停用，用户此时必须迁移到 Azure Sphere（集成）。 使用位于 TOC 上方的版本选择器查看 Azure Sphere（集成）文档。

Azure Sphere 通过 Visual Studio、Visual Studio Code 以及 Windows 和 Linux 命令行使用 CMake 来配置应用程序的生成。 CMake 是一个开源的跨平台生成系统。 有关 CMake 的常规信息，请参阅 CMake Wiki。

下列源介绍了如何将 CMake 与 Visual Studio 或 Visual Studio Code 配合使用：

• Visual Studio 中的 CMake 项目
• CMake Tools extension for Visual Studio Code（适用于 Visual Studio Code 的 CMake Tools 扩展）

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	具有多个根的项目的 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	创建映像包。

如果现有应用程序是使用早于 20.04 的 SDK 创建的，请参阅转换现有应用以使用 CMake 函数。

CMakeLists.txt 文件必须先调用 project 命令，然后再调用任何 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 文件夹中查找。 若要指定多个文件夹，请将每个文件夹名称括在双引号中，并使用空格分隔文件夹名称，如示例中所示。 在此示例中， <路径> 表示开发计算机上的 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}，并且 只能从CMakeLists.txt文件中调用azsphere_target_add_image_package 函数一次。

已弃用的 CMake 函数

在 SDK 版本 24.03 之前，CMake 函数 azsphere_configure_tools 和 azsphere_configure_api 用于在CMakeLists.txt文件中指定目标 SDK 工具版本和目标 API 集。 这些函数现已弃用，应改为在相应的配置文件中指定目标 API 集。 有关详细信息，请参阅应用程序运行时版本、sysroot 和 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 更新高级别应用对 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配置更改。

下面的示例展示了需要在 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 文件包括以下更改：

• 在“environments”字段中，只有“Azure Sphere”是必需的。
• 在“调试”和“发布”版本的“配置”字段中：
  • “buildRoot”和“installRoot”值不再需要 AzureSphereTargetApiSet 设置。
  • 现在，CMake 工具链在“cmakeToolChain”中而不是“variables”中定义。
  • “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_DIRECTORY 和 AZURE_SPHERE_TARGET_HARDWARE_DEFINITION 设置，因为这些值现在在 CMakeLists.txt 文件中设置。
• 不再需要设置 CMAKE_TOOLCHAIN_FILE 和 AZURE_SPHERE_TARGET_API_SET 设置，因为这些值现在在 CMakePresets.json 文件中设置。 现在"latest-lts"，该值AZURE_SPHERE_TARGET_API_SET指示项目应使用最新的长期稳定 （LTS） sysroot 进行生成。

请注意， "cmake.configureArgs" 由于与 CMake 无关的原因，该字段也已被删除。 （由于此生成不需要参数， --no-warn-unused-cli 因此不再需要该字段。

以下字段适用于扩展：

• "cmake.configureOnOpen": true 通知 cmake-tools 扩展在工作区打开时开始配置。

• "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools"指定要用于 cpp 工具扩展的 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文件的文件夹指定。