使用 CMake 配置生成

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

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

• Visual Studio 中的 CMake 项目
• 适用于 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	具有多个根的项目的 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 文件的文件夹指定。