Configurare le compilazioni con CMake

Importante

Questa è la documentazione di Azure Sphere (legacy). Azure Sphere (legacy) viene ritirato il 27 settembre 2027 e gli utenti devono eseguire la migrazione ad Azure Sphere (integrato) entro questo periodo. Usare il selettore di versione posizionato sopra il sommario per visualizzare la documentazione di Azure Sphere (integrata).

Azure Sphere usa CMake per configurare le compilazioni per le applicazioni con Visual Studio, Visual Studio Code e gli strumenti da riga di comando di Windows e Linux. CMake è un sistema di automazione open source multipiattaforma. Per informazioni di carattere generale su CMake, vedere il Wiki di CMake.

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

• Progetti CMake in Visual Studio
• Estensione CMake Tools per Visual Studio Code

Le compilazioni CMake usano i file seguenti:

file	Scopo
CMakeLists.txt	File di configurazione generale CMake. Necessario per tutte le compilazioni.
CMakePresets.json	File dei set di impostazioni di configurazione 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. Necessario per la compilazione con Visual Studio Code.

I parametri di CMake sono separati da spazi. Il carattere di continuazione della 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.

Funzioni CMake per Azure Sphere

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

Nome	Scopo
azsphere_target_hardware_definition	Specificare l'hardware della destinazione.
azsphere_target_add_image_package	Creare un pacchetto immagine.

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

Il file CMakeLists.txt deve chiamare il comando project prima di qualsiasi funzione azsphere_.

Definizione dell'hardware di destinazione

È possibile specificare l'hardware di destinazione chiamando la funzione azsphere_target_hardware_definition per archiviare il valore nel file CMakeLists.txt. Questa funzione accetta due parametri: un elenco di directory da cercare e un nome file da cercare. Ad 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 il <percorso> rappresenta il percorso della cartella my_app nel computer di sviluppo.

Creazione del pacchetto immagine

Specificare il file del pacchetto immagine e gli eventuali file di risorse da includere durante la compilazione chiamando la funzione azsphere_target_add_image_package per archiviare il valore in nel file CMakeLists.txt. La funzione azsphere_target_add_image_package e il progetto da compilare sono obbligatori. I file di risorse sono facoltativi.

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

azsphere_target_add_image_package(${PROJECT_NAME})

Nell'esempio seguente viene creato un pacchetto immagine che contiene 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 dell'SDK versione 24.03, le funzioni CMake azsphere_configure_tools e azsphere_configure_api sono state usate per specificare la versione degli strumenti SDK di destinazione e il set di API di destinazione nel file 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, vedere la pagina Versione del runtime dell'applicazione, sysroot e API beta.

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

azsphere_configure_tools(TOOLS_REVISION 23.05) azsphere_configure_api(TARGET_API_SET 16)

Come eliminare la cache di CMake quando si modificano i file di configurazione

Se si modifica uno dei file di configurazione, è necessario eliminare la cache CMake per assicurarsi che le compilazioni successive non riescano. Prima di procedere a un'altra compilazione, seguire questa procedura:

• Per le compilazioni di Visual Studio Code, eseguire il comando CMake:Delete Cache e Riconfigurare dal riquadro comandi.
• Per le compilazioni 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 si dispone già di un'applicazione Azure Sphere compilata con CMake prima dell'SDK versione 20.04, è necessario convertirla per poter usare queste nuove funzioni. È comunque possibile compilare tali applicazioni invariate per il momento, 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 per l'aggiornamento del microcontroller esterno per la versione 20.04.

Nota

Oltre agli aggiornamenti per usare le funzioni, questi file sono stati aggiornati negli esempi di Azure Sphere per usare nomi di funzioni con lettere minuscole, in modo da essere allineati con le convenzioni di CMake.

Modifiche di configurazione per il file CMakeLists.txt

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

File CMakeLists.txt dell'SDK versione 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 di CMakeLists.txt aggiornato chiama le funzioni di azsphere_target_hardware_definition per impostare l'hardware di destinazione. Chiama anche la funzione azsphere_target_add_image_package per compilare il pacchetto immagine e, facoltativamente, specificare i file da includere nel pacchetto.

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 condividerle con gli sviluppatori usando altri ambienti di sviluppo. Ad esempio, è possibile usare lo stesso file di configurazione dei set di impostazioni per richiamare CMake in Visual Studio, Visual Studio Code, una pipeline di integrazione continua o dall'interfaccia della riga di comando in Windows, Linux o macOS.

A partire dalla versione 22.07, i progetti correnti usano set di impostazioni definiti in CMakePresets.json, mentre i progetti esistenti possono continuare a usare le impostazioni in CMakeSettings.json. Gli esempi vengono forniti con un solo file di configurazione, CMakePresets.json o CMakeSettings.json. L'ambiente di sviluppo userà il file presente. Fare riferimento a ogni progetto di esempio per vedere quale file viene usato. Per i progetti che usano CMakeSettings.json, vedere 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 e CMAKE_TOOLCHAIN_FILE viene 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

Gli esempi vengono forniti con un file di configurazione CMakePresets.json o CMakeSettings.json. Fare riferimento a ogni progetto per vedere quale file viene usato. Questa sezione descrive la configurazione CMakeSettings.json. Per i progetti che usano CMakePresets.json, vedere Modifiche alla configurazione di Visual Studio CMakePresets.json.

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

File CMakeSettings.json dell'SDK versione 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 CMakeSettings.json dell'SDK aggiornato

Il file CMakeSettings.json aggiornato include le modifiche seguenti:

• Nel campo "environments" è necessario solo "Azure Sphere".
• Nel campo "configurazioni" per le build di debug e versione:
  • I valori per "buildRoot" e "installRoot" non richiedono più l'impostazione AzureSphereTargetApiSet.
  • La toolchain di CMake è ora definita in "cmakeToolChain" anziché in "variables".
  • Il campo "variables" ora specifica solo il set di API di destinazione e usa il nuovo valore "latest-lts" per indicare che il progetto deve essere compilato con la directory sysroot con stabilità a lungo termine più recente (LTS). Le impostazioni per AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY e AZURE_SPHERE_TARGET_HARDWARE_DEFINITION non sono più necessarie, perché questi valori sono ora impostati nel file 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"
        }
      ]
    }
  ]
}

Configurazione di Visual Studio Code con estensione vscode/settings.json

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

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

File con estensione vscode/settings.json aggiornato

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

Il file di settings.json aggiornato include le modifiche seguenti 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 più recente sysroot (LTS) stabile a lungo termine.

Si noti 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 compilazione.

I campi seguenti si applicano alle estensioni:

• "cmake.configureOnOpen": true notifica all'estensione cmake-tools di avviare la configurazione all'apertura dell'area di lavoro.

• "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools" specifica il provider IntelliSense da usare 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 CMakeWorkspaceSettings.json

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

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

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