Настройка сборок с помощью CMake

Azure Sphere использует CMake для настройки сборок для приложений с помощью Visual Studio, Visual Studio Code, а также командных строк Windows и Linux. CMake — это кроссплатформенная система создания с открытым кодом. Общие сведения о CMake см. на Вики-сайте CMake.

Следующие источники содержат сведения об использовании CMake с Visual Studio или Visual Studio Code:

• Проекты CMake в Visual Studio
• Расширение средств CMake для Visual Studio Code

Сборки CMake используют следующие файлы:

Файл	Цель
CMakeLists.txt	Общий файл конфигурации CMake. Требуется для всех сборок.
CMakePresets.json	Файл предустановок конфигурации для Visual Studio и Visual Studio Code. Этот файл или CMakeSettings.json требуется для сборки с помощью Visual Studio.
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.

Функции CMake для Azure Sphere

Файл 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 будет отображаться только в папке HardwareDefinitions в установке пакета SDK. Чтобы указать несколько папок, заключите имя каждой папки в двойные кавычки и используйте пробел для разделения имен папок, как показано в примере. В этом примере <путь> представляет путь к папке 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")

Целевой объект CMake, переданный azsphere_target_add_image_package , должен иметь имя ${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 и Бета-интерфейсы 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

Если у вас уже есть приложение Azure Sphere, созданное с помощью CMake до выпуска пакета SDK 20.04, следует преобразовать его для использования этих новых функций. Вы по-прежнему можете создавать такие приложения без изменений, но их поддержка ограничена и может быть удалена в будущем выпуске.

В качестве примера изменений, которые необходимо внести, ознакомьтесь с тем, как были изменены файлы конфигурации CMakeLists.txt и *.json для высокоуровневого приложения "Обновление внешнего MCU " для выпуска 20.04.

Примечание

Помимо обновлений для использования функций, эти файлы были обновлены в примерах Azure Sphere для использования имен функций в нижнем регистре, что соответствует соглашениям CMake.

изменения конфигурации CMakeLists.txt

В следующих примерах показаны изменения, необходимые для обновления файла CMakeLists.txt версии 20.01 или более ранней версии для использования новых функций.

Пример файла CMakeLists.txt пакета SDK 20.01

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.

Конфигурация CMakePresets.json Visual Studio

Файл CMakePresets.json позволяет указать общие параметры настройки, сборки и тестирования, а затем поделиться ими с разработчиками с помощью других сред разработки. Например, один и тот же файл конфигурации предустановок можно использовать для вызова CMake в Visual Studio, Visual Studio Code, конвейера непрерывной интеграции или из интерфейса командной строки в Windows, Linux или macOS.

С выпуска 22.07 в текущих проектах используются предустановки, определенные в CMakePresets.json, в то время как существующие проекты могут продолжать использовать параметры в CMakeSettings.json. Примеры поставляются только с одним файлом конфигурации, CMakePresets.json или CMakeSettings.json. Среда разработки будет использовать файл, который присутствует. Ознакомьтесь с каждым примером проекта, чтобы узнать, какой файл используется. Сведения о проектах, использующих CMakeSettings.json, см. в статье Изменения конфигурации CMakeSettings.json Visual Studio.

Файлы 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}"

Конфигурация CMakeSettings.json Visual Studio

Примеры поставляются с файлом конфигурации CMakePresets.json или CMakeSettings.json. Ознакомьтесь с каждым проектом, чтобы узнать, какой файл используется. В этом разделе описывается конфигурация CMakeSettings.json. Сведения о проектах, использующих CMakePresets.json, см. в статье Изменения конфигурации CMakePresets.json Visual Studio.

В следующих примерах показаны изменения, необходимые для обновления файла CMakeSettings.json в Visual Studio с версии 20.01 или более ранней версии для использования новых функций.

Пример файла пакета SDK 20.01 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}"
        }
      ]
    }
  ]
}

Обновленный файл CMakeSettings.json пакета SDK

Обновленный файл 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

В следующих примерах показаны изменения, необходимые для обновления vscode/settings.json файла для Visual Studio Code версии 20.01 или более ранней версии для использования новых функций.

Пример vscode/settings.json файла пакета SDK 20.01

{
    "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) системной базы данных.

Обратите внимание, что "cmake.configureArgs" поле также было удалено по причинам, не связанным с CMake. (Поле больше не требуется, --no-warn-unused-cli так как параметр не требуется для этой сборки.)

К расширениям применяются следующие поля:

• "cmake.configureOnOpen": true уведомляет расширение cmake-tools о начале настройки при открытии рабочей области.

• "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools" указывает поставщик IntelliSense, который будет использоваться для расширения cpp-tools ; в этом случае расширение 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.