Konfigurieren von Builds mit CMake

  • Artikel

Azure Sphere verwendet CMake, um Builds für Anwendungen mit Visual Studio, Visual Studio Code und den Windows- und Linux-Befehlszeilen zu konfigurieren. CMake ist ein plattformübergreifendes Open-Source-System. Allgemeine Informationen zu CMake finden Sie im CMake-Wiki.

Die folgenden Quellen enthalten Informationen zur Verwendung von CMake mit Visual Studio oder Visual Studio Code:

CMake-Builds verwenden die folgenden Dateien:

Datei Zweck
CMakeLists.txt Allgemeine CMake-Konfigurationsdatei. Erforderlich für alle Builds.
CMakePresets.json Konfigurationsvoreinstellungendatei für Visual Studio und Visual Studio Code. Für die Erstellung mit Visual Studio ist entweder diese Datei oder CMakeSettings.json erforderlich.
CMakeSettings.json Visual Studio-Konfigurationsdatei. Für die Erstellung mit Visual Studio ist entweder diese Datei oder CMakePresets.json erforderlich.
CMakeWorkspaceSettings.json Visual Studio-Konfigurationsdatei für Projekte mit mehreren Stammstrukturen, wie im IntercoreComms-Beispiel.
.vscode/settings.json Visual Studio Code-Konfigurationsdatei. Erforderlich für die Erstellung mit Visual Studio Code.

CMake-Parameter werden durch Leerzeichen getrennt. Das Zeilenfortsetzungszeichen "^" für die Windows-Befehlszeile, " \ " für die Linux-Befehlszeile oder "'" für PowerShell kann zur Lesbarkeit verwendet werden, ist jedoch nicht erforderlich. Das spezifische Zeichen wird durch die Windows- oder Linux-Terminalkonfiguration bestimmt.

CMake-Funktionen für Azure Sphere

Die CMakeLists.txt-Datei enthält die allgemeinen Konfigurationseinstellungen, die von CMake zum Erstellen einer Anwendung verwendet werden. Azure Sphere unterstützt die Verwendung der folgenden Funktionen in CMakeLists.txt:

Namen Zweck
azsphere_target_hardware_definition Geben Sie Die Zielhardware an.
azsphere_target_add_image_package Erstellen Sie ein Imagepaket.

Wenn Sie über eine vorhandene Anwendung verfügen, die mit einem FRÜHERen SDK als 20.04 erstellt wurde, lesen Sie Konvertieren einer vorhandenen App zur Verwendung der CMake-Funktionen.

Die CMakeLists.txt-Datei muss den Projektbefehl vor einer der azsphere_ -Funktionen aufrufen.

Zielhardwaredefinition

Sie können die Zielhardware angeben, indem Sie die funktion azsphere_target_hardware_definition aufrufen, um den Wert in CMakeLists.txt zu speichern. Diese Funktion verwendet zwei Parameter: eine Liste der zu durchsuchenden Verzeichnisse und einen Dateinamen, nach dem gesucht werden soll. Zum Beispiel:

azsphere_target_hardware_definition(${PROJECT_NAME} TARGET_DIRECTORY "<path>/my_app/contoso_hardware_definitions" "<path>/my_app/test_hardware" TARGET_DEFINITION "contoso_board.json")

Der parameter TARGET_DEFINITION ist erforderlich. Es gibt den Namen der Hardwaredefinitionsdatei an, die ihre Anwendung benötigt. Der parameter TARGET_DIRECTORY listet die Verzeichnisse auf, in denen nach dieser Datei gesucht werden soll. Dieser Parameter ist optional. Wenn Sie dies weglassen, sucht CMake in der SDK-Installation nur im Ordner HardwareDefinitions. Um mehrere Ordner anzugeben, schließen Sie jeden Ordnernamen in doppelte Anführungszeichen ein, und verwenden Sie ein Leerzeichen, um Ordnernamen zu trennen, wie im Beispiel gezeigt. Im Beispiel <stellt path> den Pfad zum ordner my_app auf Ihrem Entwicklungscomputer dar.

Imagepaketerstellung

Geben Sie die Bildpaketdatei und alle Ressourcendateien an, die beim Erstellen eingeschlossen werden sollen, indem Sie die azsphere_target_add_image_package-Funktion aufrufen, um den Wert in CMakeLists.txt zu speichern. Die azsphere_target_add_image_package-Funktion und das zu erstellende Projekt sind erforderlich. die Ressourcendateien sind optional.

Der folgende Funktionsaufruf erstellt ein Imagepaket, das nur die Azure Sphere-Anwendung enthält:

azsphere_target_add_image_package(${PROJECT_NAME})

Im nächsten Beispiel wird ein Imagepaket erstellt, das zusätzlich zu einer Anwendung ein Zertifikat enthält:

azsphere_target_add_image_package(${PROJECT_NAME} RESOURCE_FILES "certs/bundle.pem")

Das an azsphere_target_add_image_package übergebene CMake-Ziel muss den Namen ${PROJECT_NAME} haben, und die azsphere_target_add_image_package-Funktion kann nur einmal aus der CMakeLists.txt-Datei aufgerufen werden.

Veraltete CMake-Funktionen

Vor SDK-Version 24.03 wurden die CMake-Funktionen azsphere_configure_tools und azsphere_configure_api verwendet, um die Zielversion des SDK-Tools und den API-Zielsatz in der CMakeLists.txt-Datei anzugeben. Diese Funktionen sind jetzt veraltet, und der ZIEL-API-Satz sollte stattdessen in der entsprechenden Konfigurationsdatei angegeben werden. Weitere Informationen finden Sie auf der Seite Anwendungsruntimeversion, Sysroots und Beta-APIs .

Wenn Sie eine ältere Version des SDK verwenden und bei einer nicht unterstützten Toolsrevision ein CMake-Konfigurationsfehler angezeigt wird, können Sie dies umgehen, indem Sie diese Funktionen erneut zum CMakeLists.txt hinzufügen. Beispiel:

azsphere_configure_tools(TOOLS_REVISION 23.05) azsphere_configure_api(TARGET_API_SET 16)

Löschen des CMake-Caches beim Ändern von Konfigurationsdateien

Wenn Sie eine der Konfigurationsdateien ändern, sollten Sie den CMake-Cache löschen, um sicherzustellen, dass nachfolgende Builds nicht fehlschlagen. Führen Sie dieses Verfahren aus, bevor Sie versuchen, einen anderen Build zu erstellen:

  • Führen Sie für Visual Studio Code-Builds den Befehl CMake:Delete Cache and Reconfigure in der Befehlspalette aus.
  • Löschen Sie für Befehlszeilenbuilds (CLI) das Buildverzeichnis, das Sie in einem früheren Schritt erstellt haben.

Visual Studio erkennt Änderungen an der CMake-Konfigurationsdatei und löscht den Cache automatisch.

Konvertieren einer vorhandenen App zur Verwendung der CMake-Funktionen

Wenn Sie bereits über eine Azure Sphere-Anwendung verfügen, die vor dem SDK 20.04 mit CMake erstellt wurde, sollten Sie sie für die Verwendung dieser neuen Funktionen konvertieren. Sie können solche Anwendungen vorerst unverändert erstellen, aber die Unterstützung für sie ist begrenzt und kann in einer zukünftigen Version entfernt werden.

Ein Beispiel für die Änderungen, die Sie vornehmen sollten, finden Sie unter , wie die CMakeLists.txt- und *.json-Konfigurationsdateien für die allgemeine externe MCU-Update-App für das Release 20.04 geändert wurden.

Hinweis

Zusätzlich zu den Updates für die Verwendung der Funktionen wurden diese Dateien in den Azure Sphere-Beispielen aktualisiert, um Funktionsnamen in Kleinbuchstaben zu verwenden und somit den CMake-Konventionen zu entsprechen.

CMakeLists.txt Konfigurationsänderungen

Die folgenden Beispiele zeigen die Änderungen, die zum Aktualisieren der CMakeLists.txt-Datei von 20.01 oder früher erforderlich sind, um die neuen Funktionen zu verwenden.

Beispieldatei für 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}")

Aktualisierte CMakeLists.txt-Datei

Die aktualisierte CMakeLists.txt-Datei ruft die azsphere_target_hardware_definition-Funktionen auf, um die Zielhardware festzulegen. Außerdem wird azsphere_target_add_image_package aufgerufen, um das Imagepaket zu erstellen, und optional die Dateien anzugeben, die darin eingeschlossen werden sollen.

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")

Hinweis

Absolute Pfade werden für RESOURCE_FILES nicht unterstützt.

Konfiguration von Visual Studio CMakePresets.json

Mit der CMakePresets.json-Datei können Sie allgemeine Konfigurations-, Build- und Testoptionen angeben und diese dann für Entwickler freigeben, die andere Entwicklungsumgebungen verwenden. Beispielsweise können Sie die gleiche Konfigurationsdatei für Voreinstellungen verwenden, um CMake in Visual Studio, Visual Studio Code, einer Continuous Integration-Pipeline oder über die CLI unter Windows, Linux oder macOS aufzurufen.

Ab Release 22.07 verwenden aktuelle Projekte Voreinstellungen, die in CMakePresets.json definiert sind, während vorhandene Projekte weiterhin Einstellungen in CMakeSettings.json verwenden können. Beispiele werden mit nur einer Konfigurationsdatei ausgeliefert, entweder CMakePresets.json oder CMakeSettings.json. Die Entwicklungsumgebung verwendet die vorhandene Datei. Sehen Sie sich jedes Beispielprojekt an, um zu sehen, welche Datei verwendet wird. Informationen zu Projekten, die CMakeSettings.json verwenden, finden Sie unter Visual Studio CMakeSettings.json Konfigurationsänderungen.

Die CMakePresets.json Dateien für eine allgemeine Anwendung und für eine Echtzeitanwendung sind sehr ähnlich; die einzigen Unterschiede bestehen in den CMAKE_TOOLCHAIN_FILE Variablen und ARM_GNU_PATH .

In einer allgemeinen Anwendung ARM_GNU_PATH ist nicht festgelegt, und CMAKE_TOOLCHAIN_FILE wird wie folgt festgelegt:

    "CMAKE_TOOLCHAIN_FILE": "$env{AzureSphereDefaultSDKDir}/CMakeFiles/AzureSphereToolchain.cmake",

In einer Echtzeitanwendung CMAKE_TOOLCHAIN_FILE werden und ARM_GNU_PATH wie folgt festgelegt:

    "CMAKE_TOOLCHAIN_FILE": "$env{AzureSphereDefaultSDKDir}/CMakeFiles/AzureSphereRTCoreToolchain.cmake",
    "ARM_GNU_PATH": "$env{ArmGnuPath}"

Visual Studio CMakeSettings.json-Konfiguration

Beispiele werden entweder mit einer CMakePresets.json- oder CMakeSettings.json-Konfigurationsdatei ausgeliefert. Sehen Sie sich jedes Projekt an, um zu sehen, welche Datei verwendet wird. In diesem Abschnitt wird die konfiguration der CMakeSettings.json beschrieben. Informationen zu Projekten, die CMakePresets.json verwenden, finden Sie unter Visual Studio CMakePresets.json Konfigurationsänderungen.

Die folgenden Beispiele zeigen die Änderungen, die zum Aktualisieren der CMakeSettings.json-Datei in Visual Studio von 20.01 oder früher erforderlich sind, um die neuen Funktionen zu verwenden.

Beispieldatei für 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}"
        }
      ]
    }
  ]
}

Aktualisierte SDK-CMakeSettings.json-Datei

Die aktualisierte CMakeSettings.json-Datei enthält die folgenden Änderungen:

  • Im Feld "umgebungen" ist nur "Azure Sphere" erforderlich.
  • Im Feld "Konfigurationen" für den Debug- und den Releasebuild:
    • Für die Werte "buildRoot" und "installRoot" ist die Einstellung AzureSphereTargetApiSet nicht mehr erforderlich.
    • Die CMake-Toolkette wird jetzt in "cmakeToolChain" und nicht in "variables" definiert.
    • Das Feld "variables" gibt jetzt nur den ZIEL-API-Satz an und verwendet den neuen Wert "latest-lts", um anzugeben, dass das Projekt mit dem neuesten long-stable (LTS) sysroot erstellt werden soll. Die Einstellungen AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY und AZURE_SPHERE_TARGET_HARDWARE_DEFINITION sind nicht mehr erforderlich, da diese Werte jetzt in der CMakeLists.txt-Datei festgelegt sind.
{
  "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-Konfiguration ".vscode/settings.json"

Die folgenden Beispiele zeigen die Änderungen, die zum Aktualisieren der VSCODE/settings.json-Datei für Visual Studio Code von 20.01 oder früher erforderlich sind, um die neuen Funktionen zu verwenden.

Vscode/settings.json-Beispieldatei des 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"
}

Aktualisierte VSCODE/settings.json-Datei

Die Datei .vscode/settings.json enthält Arbeitsbereichseinstellungen für Visual Studio Code.

Die aktualisierte settings.json Datei enthält die folgenden Änderungen am Feld "cmake.configureSettings":

  • Die AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY Einstellungen und AZURE_SPHERE_TARGET_HARDWARE_DEFINITION sind nicht mehr erforderlich, da diese Werte jetzt in der CMakeLists.txt-Datei festgelegt sind.
  • Die CMAKE_TOOLCHAIN_FILE Einstellungen und AZURE_SPHERE_TARGET_API_SET sind nicht mehr erforderlich, da diese Werte jetzt in der CMakePresets.json-Datei festgelegt sind. Der AZURE_SPHERE_TARGET_API_SET Wert ist jetzt "latest-lts", was angibt, dass das Projekt mit dem neuesten long-stable -Sysroot (LTS) erstellt werden soll.

Beachten Sie, dass das "cmake.configureArgs" Feld auch aus Gründen gelöscht wurde, die nichts mit CMake zu tun haben. (Das Feld ist nicht mehr erforderlich, da der --no-warn-unused-cli Parameter für diesen Build nicht benötigt wird.)

Die folgenden Felder gelten für Erweiterungen:

  • "cmake.configureOnOpen": true benachrichtigt die Erweiterung cmake-tools , mit der Konfiguration zu beginnen, wenn der Arbeitsbereich geöffnet wird.

  • "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools" gibt den IntelliSense-Anbieter an, der für die Erweiterung cpp-tools verwendet werden soll; in diesem Fall die Erweiterung 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"
}

Erstellen einer CMakeWorkspaceSettings.json-Datei

Wenn Sie Visual Studio 2022, Version 17.1 oder höher, verwenden und über ein Projekt mit mehreren Stammstrukturen verfügen, z. B. das IntercoreComms-Beispiel, müssen Sie dem Ordner auf oberster Ebene des Projekts eine CMakeWorkspaceSettings.json Datei hinzufügen. Die Datei verfügt über zwei Einträge: einer, der angibt, dass der CMake-Build aktiviert ist, und einer mit den Pfaden zu den mehreren Stammelementen. Für das Beispiel IntercoreComms hat die CMakeWorkspaceSettings.json beispielsweise den folgenden Inhalt:

{
  "enableCMake": true,
  "sourceDirectory": [ "IntercoreComms_HighLevelApp", "IntercoreComms_RTApp_MT3620_BareMetal" ]
}

Die Pfade werden relativ zum Ordner angegeben, der die CMakeWorkspaceSettings.json Datei enthält.