Configurare le build con CMake

Articolo
04/03/2024

Azure Sphere usa CMake per configurare le build per le applicazioni con Visual Studio, Visual Studio Code e le righe di comando di Windows e Linux. CMake è un sistema di creazione open source multipiattaforma. Per informazioni generali su CMake, vedere CMake Wiki.

Le fonti seguenti forniscono informazioni sull'utilizzo di CMake con Visual Studio o Visual Studio Code:

CMake build utilizza i file seguenti:

File	Scopo
CMakeLists.txt	Generale CMake file di configurazione. Obbligatorio per tutte le build.
CMakePresets.json	File di configurazione preimpostati per Visual Studio e Visual Studio Code. Questo file o CMakeSettings.json è necessario per la compilazione con Visual Studio.
CMakeSettings.json	File di configurazione di Visual Studio. Questo file o CMakePresets.json è necessario per la compilazione con Visual Studio.
CMakeWorkspaceSettings.json	File di configurazione di Visual Studio per progetti con più radici, come nell'esempio IntercoreComms.
vscode/settings.json	File di configurazione di Visual Studio Code. Obbligatorio per la costruzione con Visual Studio Code.

CMake parametri sono separati da spazi. Il carattere di continuazione riga "^" per la riga di comando di Windows, " \ " per la riga di comando Linux o "'" per PowerShell può essere usato per la leggibilità, ma non è obbligatorio. Il carattere specifico è determinato dalla configurazione del terminale Windows o Linux.

CMake funzioni per Azure Sphere

Il file CMakeLists.txt fornisce le impostazioni di configurazione generali utilizzate da CMake per creare un'applicazione. Azure Sphere supporta l'uso delle funzioni seguenti in CMakeLists.txt:

Nome	Scopo
azsphere_target_hardware_definition	Specificare l'hardware di destinazione.
azsphere_target_add_image_package	Creare un pacchetto di immagini.

Se si ha un'applicazione esistente creata con un SDK precedente alla 20.04, vedere Convertire un'app esistente per usare le funzioni CMake.

Il file CMakeLists.txt deve chiamare il comando del progetto prima di una qualsiasi delle funzioni azsphere_ .

Definizione hardware di destinazione

È possibile specificare l'hardware di destinazione chiamando la funzione azsphere_target_hardware_definition per memorizzare il valore in CMakeLists.txt. Questa funzione accetta due parametri: un elenco di directory da cercare e un nome file da cercare. Per esempio:

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

Il parametro TARGET_DEFINITION è obbligatorio. Specifica il nome del file di definizione hardware richiesto dall'applicazione. Il parametro TARGET_DIRECTORY elenca le directory in cui cercare il file. Questo parametro è facoltativo; se viene omesso, CMake cerca solo nella cartella HardwareDefinitions nell'installazione dell'SDK. Per specificare più cartelle, racchiudere ogni nome di cartella tra virgolette doppie e usare uno spazio per separare i nomi delle cartelle, come nell'esempio. Nell'esempio path <> rappresenta il percorso della cartella my_app nel computer di sviluppo.

Creazione di pacchetti di immagini

Specificare il file del pacchetto di immagini e gli eventuali file di risorse da includere durante la creazione chiamando la funzione azsphere_target_add_image_package per archiviare il valore in CMakeLists.txt. La funzione azsphere_target_add_image_package e il progetto da compilare sono necessari; i file di risorse sono facoltativi.

La chiamata di funzione seguente crea un pacchetto di immagini che contiene solo l'applicazione Azure Sphere:

azsphere_target_add_image_package(${PROJECT_NAME})

Nell'esempio seguente viene creato un pacchetto di immagini contenente un certificato oltre a un'applicazione:

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

La destinazione CMake passata a azsphere_target_add_image_package deve essere denominata ${PROJECT_NAME} e la funzione azsphere_target_add_image_package può essere chiamata una sola volta dal file CMakeLists.txt.

Funzioni CMake deprecate

Prima della versione 24.03 dell'SDK, le funzioni CMake azsphere_configure_tools e azsphere_configure_api venivano usate per specificare la versione degli strumenti SDK di destinazione e l'API di destinazione impostate nel file di CMakeLists.txt. Queste funzioni sono ora deprecate e il set di API di destinazione deve essere specificato nel file di configurazione appropriato. Per informazioni dettagliate, vedi la versione di Application Runtime, sysroots e la pagina delle API Beta .

Se si usa una versione precedente dell'SDK e viene visualizzato un errore di configurazione CMake relativo a una revisione degli strumenti non supportati, è possibile risolvere il problema aggiungendo di nuovo queste funzioni al CMakeLists.txt. Ad esempio:

azsphere_configure_tools(TOOLS_REVISION 23.05) azsphere_configure_api(TARGET_API_SET 16)

Come eliminare la cache CMake durante la modifica dei file di configurazione

Se si modifica uno dei file di configurazione, è necessario eliminare la cache CMake per assicurarsi che le build successive non fallisca. Seguire questa procedura prima di tentare un'altra build:

Per le build di Visual Studio Code, eseguire il comando CMake:Delete Cache e Riconfigurare dal tavolozza dei comandi.
Per le build della riga di comando, eliminare la directory di compilazione creata in un passaggio precedente.

Visual Studio rileva le modifiche apportate al file di configurazione CMake ed elimina automaticamente la cache.

Convertire un'app esistente per usare le funzioni CMake

Se hai già un'applicazione Azure Sphere creata con CMake prima dell'SDK 20.04, devi convertirla per usare queste nuove funzioni. Per il momento è comunque possibile creare tali applicazioni invariate, ma il supporto per tali applicazioni è limitato e potrebbe essere rimosso in una versione futura.

Per un esempio delle modifiche da apportare, esaminare come sono stati modificati i file di configurazione CMakeLists.txt e *.json per l'app di alto livello Aggiornamento MCU esterno per la versione 20.04.

Nota

Oltre agli aggiornamenti per l'uso delle funzioni, questi file sono stati aggiornati negli esempi di Azure Sphere per usare nomi di funzioni minuscole, allineati quindi con le convenzioni CMake.

CMakeLists.txt modifiche alla configurazione

Gli esempi seguenti mostrano le modifiche necessarie per aggiornare il file CMakeLists.txt dalla 20.01 o versione precedente per usare le nuove funzioni.

Esempio di file di 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}")

File CMakeLists.txt aggiornato

Il file CMakeLists.txt aggiornato chiama le funzioni azsphere_target_hardware_definition per impostare l'hardware di destinazione. Chiama anche azsphere_target_add_image_package per creare il pacchetto di immagini e, facoltativamente, specificare i file da includere al suo interno.

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

Nota

I percorsi assoluti non sono supportati per RESOURCE_FILES.

Configurazione di Visual Studio CMakePresets.json

Il file CMakePresets.json consente di specificare opzioni comuni di configurazione, compilazione e test, quindi di condividerle con gli sviluppatori che usano altri ambienti di sviluppo. Ad esempio, è possibile usare lo stesso file di configurazione preimpostati per richiamare CMake in Visual Studio, Visual Studio Code, una pipeline di integrazione continua o dall'ambiente cli su Windows, Linux o macOS.

A partire dal rilascio 22.07, i progetti correnti usano preimpostati definiti in CMakePresets.json, mentre i progetti esistenti possono continuare a usare le impostazioni in CMakeSettings.json. I campioni vengono forniti con un solo file di configurazione, CMakePresets.json o CMakeSettings.json. L'ambiente di sviluppo utilizzerà il file presente. Fare riferimento a ogni progetto di esempio per vedere quale file viene usato. Per i progetti che usano CMakeSettings.json, vedi Modifiche alla configurazione di Visual Studio CMakeSettings.json.

I file CMakePresets.json per un'applicazione di alto livello e per un'applicazione in tempo reale sono molto simili; le uniche differenze sono nelle CMAKE_TOOLCHAIN_FILE variabili e ARM_GNU_PATH .

In un'applicazione di alto livello, ARM_GNU_PATH non è impostata ed CMAKE_TOOLCHAIN_FILE è impostata come segue:

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

In un'applicazione CMAKE_TOOLCHAIN_FILE in tempo reale e ARM_GNU_PATH sono impostati come segue:

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

Configurazione di Visual Studio CMakeSettings.json

I campioni vengono forniti con un file di configurazione CMakePresets.json o CMakeSettings.json. Fare riferimento a ogni progetto per vedere quale file viene usato. In questa sezione viene descritta la configurazione CMakeSettings.json. Per i progetti che usano CMakePresets.json, vedi Modifiche alla configurazione di Visual Studio CMakePresets.json.

Gli esempi seguenti mostrano le modifiche necessarie per aggiornare il file CMakeSettings.json in Visual Studio dalla 20.01 o versione precedente per usare le nuove funzioni.

Esempio di file di 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}"
        }
      ]
    }
  ]
}

File di CMakeSettings.json SDK aggiornato

Il file CMakeSettings.json aggiornato include le modifiche seguenti:

Nel campo "ambienti", è richiesto solo "Azure Sphere".
Nel campo "configurazioni" per le build Debug e Release:
- I valori "buildRoot" e "installRoot" non richiedono più l'impostazione AzureSphereTargetApiSet.
- Il toolchain CMake è ora definito in "cmakeToolChain" anziché in "variabili".
- Il campo "variabili" ora specifica solo il set di API di destinazione e utilizza il nuovo valore "latest-lts" per indicare che il progetto deve essere compilato con la sysroot più recente a lungo termine stabile (LTS). Le impostazioni AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY e AZURE_SPHERE_TARGET_HARDWARE_DEFINITION non sono più necessarie, perché questi valori sono ora impostati nel fileCMakeLists.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"
        }
      ]
    }
  ]
}

Configurazione di Visual Studio Code .vscode/settings.json

Gli esempi seguenti mostrano le modifiche necessarie per aggiornare il file .vscode/settings.json per Visual Studio Code dalla 20.01 o versione precedente per usare le nuove funzioni.

Esempio di file vscode/settings.json SDK 20.01 SDK

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

File con estensione vscode/settings.json aggiornato

Il file .vscode/settings.json contiene le impostazioni dell'area di lavoro per Visual Studio Code.

Il file settings.json aggiornato include le seguenti modifiche al campo "cmake.configureSettings":

Le AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY impostazioni e AZURE_SPHERE_TARGET_HARDWARE_DEFINITION non sono più necessarie, perché questi valori sono ora impostati nel file CMakeLists.txt .
Le CMAKE_TOOLCHAIN_FILE impostazioni e AZURE_SPHERE_TARGET_API_SET non sono più necessarie, perché questi valori sono ora impostati nel file CMakePresets.json . Il AZURE_SPHERE_TARGET_API_SET valore è ora "latest-lts", che indica che il progetto deve essere compilato con la sysroot (LTS) stabile a lungo termine più recente.

Notare che il "cmake.configureArgs" campo è stato eliminato anche per motivi non correlati a CMake. Il campo non è più necessario perché il --no-warn-unused-cli parametro non è necessario per questa build.

I campi seguenti si applicano alle estensioni:

"cmake.configureOnOpen": true notifica l'estensione cmake-tools per avviare la configurazione all'apertura dell'area di lavoro.
"C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools" specifica il provider IntelliSense da utilizzare per l'estensione cpp-tools ; in questo caso, l'estensione 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"
}

Creazione di un file di CMakeWorkspaceSettings.json

Se si usa Visual Studio 2022, versione 17.1 o successiva, e si ha un progetto con più radici, ad esempio intercorecomms esempio, sarà necessario aggiungere un file di CMakeWorkspaceSettings.json alla cartella di primo livello del progetto. Il file contiene due voci, una per specificare che la build CMake è abilitata e una contenente i percorsi dei più radice. Ad esempio, per l'esempio IntercoreComms, il CMakeWorkspaceSettings.json ha il contenuto seguente:

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

I percorsi vengono specificati in relazione alla cartella che contiene il file CMakeWorkspaceSettings.json.