Konfigurieren von Builds mit CMake

Azure Sphere verwendet CMake, um Builds für Anwendungen mit Visual Studio, Visual Studio Code und den Befehlszeilen von Windows und Linux zu konfigurieren. CMake ist ein plattformübergreifendes Open-Source-Erstellungstool. 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-Projekte in Visual Studio
• CMake Tools-Erweiterung für Visual Studio Code

Bei CMake-Builds werden die folgenden Dateien verwendet:

CMake-Parameter werden mit Leerzeichen voneinander 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 tatsächliche Zeichen wird durch die Konfiguration des Windows- oder Linux-Terminals bestimmt.

CMake-Funktionen für Azure Sphere

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

Wenn Sie über eine Anwendung verfügen, die mit einem SDK vor Version 20.04 erstellt wurde, lesen Sie unter Konvertieren einer vorhandenen App zur Verwendung der CMake-Funktionen nach.

Die Datei „CMakeLists.txt“ muss den project-Befehl 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 von Verzeichnissen, nach der gesucht werden soll, und einen Dateinamen, nach dem gesucht werden soll. 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. Er 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 es weglassen, sucht CMake nur im Ordner "HardwareDefinitions" in der SDK-Installation. Wenn Sie mehrere Ordner angeben möchten, schließen Sie jeden Ordnernamen in doppelte Anführungszeichen ein, und verwenden Sie ein Leerzeichen, um Ordnernamen wie im Beispiel zu trennen. Im Beispiel steht <path> für den Pfad zum Ordner my_app auf Ihrem Entwicklungscomputer.

Imagepaketerstellung

Sie geben die Imagepaketdatei und alle Ressourcendateien für den Build an, indem Sie die Funktion azsphere_target_add_image_package aufrufen, um den Wert in „CMakeLists.txt“ zu speichern. Die Funktion azsphere_target_add_image_package und das zu erstellende Projekt sind erforderlich, während die Ressourcendateien optional sind.

Mit dem folgenden Funktionsaufruf wird ein Imagepaket erstellt, 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 Version der Ziel-SDK-Tools und die Ziel-API in der CMakeLists.txt Datei anzugeben. Diese Funktionen sind jetzt veraltet, und der Ziel-API-Satz sollte stattdessen in der entsprechenden Konfigurationsdatei angegeben werden. Ausführliche Informationen finden Sie auf der Seite "Anwendungslaufzeitversion", "Sysroots" und "Beta-APIs ".

Wenn Sie eine ältere Version des SDK verwenden und einen CMake-Konfigurationsfehler bei einer nicht unterstützten Tools-Revision sehen, können Sie sie umgehen, indem Sie diese Funktionen dem CMakeLists.txt erneut hinzufügen. Beispiel:

azsphere_configure_tools(TOOLS_REVISION 23.05) azsphere_configure_api(TARGET_API_SET 16)

Löschen des CMake-Caches bei Änderungen an Konfigurationsdateien

Wenn Sie eine der Konfigurationsdateien ändern, sollten Sie den CMake-Cache löschen, um sicherzustellen, dass nachfolgende Builds nicht fehlschlagen. Führen Sie die folgenden Schritte aus, bevor Sie einen weiteren Build versuchen:

• Führen Sie für Visual Studio Code-Builds den Befehl "CMake:Delete Cache" und "Reconfigure" aus der Befehlspalette aus.
• Löschen Sie bei Befehlszeilenbuilds 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 mit CMake vor der SDK-Version 20.04 erstellt wurde, sollten Sie sie konvertieren, damit sie diese neuen Funktionen verwendet. Sie können solche Anwendungen weiterhin unverändert erstellen, aber die Unterstützung für sie ist eingeschränkt und kann in einer zukünftigen Version entfernt werden.

Ein Beispiel für die Änderungen, die Sie vornehmen sollten, finden Sie daran, wie die Konfigurationsdateien „CMakeLists.txt“ und „*.json“ für die External MCU Update High-Level-App für das Release 20.04 geändert wurden.

Konfigurationsänderungen an „CMakeLists.txt“

Die folgenden Beispiele zeigen die Änderungen, die erforderlich sind, um die Datei „CMakeLists.txt“ von Version 20.01 oder früher zu aktualisieren, damit die neuen Funktionen verwendet werden.

Beispieldatei „CMakeLists.txt“ für das 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}")

Aktualisierte Datei „CMakeLists.txt“

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

Visual Studio CMakePresets.json-Konfiguration

Mit der CMakePresets.json-Datei können Sie allgemeine Konfigurationsoptionen, Build- und Testoptionen angeben und sie dann mit Entwicklern teilen, die andere Entwicklungsumgebungen verwenden. Sie können z. B. die gleiche Voreinstellungskonfigurationsdatei verwenden, um CMake in Visual Studio, Visual Studio Code, eine Pipeline für kontinuierliche Integration oder über die CLI unter Windows, Linux oder macOS aufzurufen.

Ab Version 22.07 verwenden aktuelle Projekte in CMakePresets.json definierte Voreinstellungen, während vorhandene Projekte weiterhin Einstellungen in CMakeSettings.json verwenden können. Beispiele werden nur mit einer Konfigurationsdatei geliefert, entweder CMakePresets.json oder CMakeSettings.json. Die Entwicklungsumgebung verwendet die datei, die vorhanden ist. Verweisen Sie auf jedes Beispielprojekt, um zu sehen, welche Datei verwendet wird. Projekte, 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 sind in den CMAKE_TOOLCHAIN_FILE und ARM_GNU_PATH Variablen.

In einer Anwendung auf hoher Ebene ist ARM_GNU_PATH nicht festgelegt, und CMAKE_TOOLCHAIN_FILE ist wie folgt festgelegt:

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

In einer Echtzeitanwendung werden CMAKE_TOOLCHAIN_FILE 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 geliefert. Verweisen Sie auf jedes Projekt, um zu sehen, welche Datei verwendet wird. In diesem Abschnitt werden die CMakeSettings.json Konfiguration beschrieben. Informationen zu Projekten mit CMakePresets.json finden Sie unter Konfigurationsänderungen in Visual Studio CMakePresets.json.

Die folgenden Beispiele zeigen die Änderungen, die erforderlich sind, um die Datei „CMakeSettings.json“ in Visual Studio von Version 20.01 oder früher zu aktualisieren, damit die neuen Funktionen verwendet werden.

Beispieldatei „CMakeSettings.json“ für das 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}"
        }
      ]
    }
  ]
}

Aktualisierte SDK-Datei „CMakeSettings.json“

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

• Im Feld „environments“ ist nur „Azure Sphere“ erforderlich.
• Im Feld "Konfigurationen" für die Builds "Debug" und "Release":
  • Für die Werte „buildRoot“ und „installRoot“ ist die Einstellung „AzureSphereTargetApiSet“ nicht mehr erforderlich.
  • Die CMake-Toolkette wird nun in „cmakeToolChain“ anstelle von „variables“ definiert.
  • Das Feld „variables“ gibt jetzt nur den API-Zielsatz an und verwendet den neuen Wert „latest-lts“, um anzugeben, dass das Projekt mit der aktuellsten Sysroot-Version aus dem LTS-Branch (Long-Term Stable) erstellt werden soll. Die Einstellungen AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY und AZURE_SPHERE_TARGET_HARDWARE_DEFINITION sind nicht mehr erforderlich, da diese Werte nun in der Datei CMakeLists.txt festgelegt werden.

{
  "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-Konfiguration

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.

Beispieldatei 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"
}

Aktualisierte VSCODE/settings.json-Datei

Die VSCODE/settings.json-Datei 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- und AZURE_SPHERE_TARGET_HARDWARE_DEFINITION-Einstellungen sind nicht mehr erforderlich, da diese Werte jetzt in der Datei CMakeLists.txt festgelegt werden.
• Die CMAKE_TOOLCHAIN_FILE und AZURE_SPHERE_TARGET_API_SET Einstellungen sind nicht mehr erforderlich, da diese Werte jetzt in der Datei CMakePresets.json festgelegt werden. Der AZURE_SPHERE_TARGET_API_SET Wert ist jetzt "latest-lts", was angibt, dass das Projekt mit dem neuesten long-term-stable (LTS) sysroot erstellt werden soll.

Beachten Sie, dass das Feld auch aus Gründen gelöscht wurde, die "cmake.configureArgs" nicht mit CMake zusammenhängen. (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 cmake-tools-Erweiterung, beim Öffnen des Arbeitsbereichs mit der Konfiguration zu beginnen.

• "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 Wurzeln verfügen, z. B. das IntercoreComms-Beispiel, müssen Sie dem Ordner der obersten Ebene des Projekts eine CMakeWorkspaceSettings.json Datei hinzufügen. Die Datei enthält zwei Einträge, eine, um anzugeben, dass der CMake-Build aktiviert ist, und eine, die die Pfade zu den mehreren Wurzeln enthält. Für das IntercoreComms-Beispiel enthält 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.