使用 CMake 配置生成

项目
04/03/2024

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

以下源提供有关将 CMake 与 Visual Studio 配合使用或Visual Studio Code的信息：

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 文件必须在任何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}，并且只能从 CMakeLists.txt 文件中调用 一次 azsphere_target_add_image_package 函数。

已弃用的 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 更新高级应用更改 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、持续集成管道中调用 CMake，或者从 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”中定义。
- “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 文件中设置。现在AZURE_SPHERE_TARGET_API_SET"latest-lts"值为，指示项目应使用最新的长期稳定 (LTS) sysroot 生成。

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

以下字段适用于扩展：

"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 文件的文件夹指定。