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

Статья
11/05/2024

Внимание

Это документация по Azure Sphere (устаревшая версия). Служба Azure Sphere (устаревшая версия) выходит на пенсию 27 сентября 2027 г., и к этому времени пользователи должны перейти в Azure Sphere (интегрированная). Используйте селектор версий, расположенный над toC, чтобы просмотреть документацию по Azure Sphere (интегрированная).

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

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

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

Файлы	Характер использования
CMakeLists.txt	Общий файл конфигурации CMake. Требуется для всех сборок.
CMakePresets.json	Предустановки файла конфигурации для Visual Studio и Visual Studio Code. Этот файл или CMakeSettings.json требуется для сборки с помощью Visual Studio.
CMakeSettings.json	Файл конфигурации Visual Studio. Этот файл или CMakePresets.json требуется для сборки с помощью Visual Studio.
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 должен вызывать команду 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 выглядит только в папке 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 использовались для указания версии целевых средств SDK и целевого API в файле CMakeLists.txt. Теперь эти функции устарели, а целевой набор 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 и Reconfigure из палитры команд.
Для сборок командной строки удалите каталог сборки, созданный на предыдущем шаге.

Visual Studio обнаруживает изменения в файле конфигурации CMake и автоматически удаляет кэш.

Преобразование существующего приложения для использования функций CMake

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

Чтобы получить пример изменений, которые необходимо внести, обратите внимание на отличия в файлах конфигурации CMakeLists.txt и *JSON высокоуровневого приложения обновления внешнего микроконтроллера для выпуска 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, см. в статье об изменениях конфигурации 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}"

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

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

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

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

{
  "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 содержит следующие изменения:

В поле "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

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

Пример файла пакета SDK 20.01 .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 больше не требуются, так как эти значения теперь задаются в файле CMakeLists.txt.AZURE_SPHERE_TARGET_HARDWARE_DEFINITION
Параметры 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.

Поделиться через