Configurer des builds à l’aide de CMake

Article
04/03/2024

Azure Sphere utilise CMake pour configurer les builds pour les applications avec Visual Studio, Visual Studio Code et les lignes de commande Windows et Linux. CMake est un système multiplateforme open source. Pour obtenir des informations générales sur CMake, consultez le Wiki CMake.

Les sources suivantes fournissent des informations sur l’utilisation de CMake avec Visual Studio ou Visual Studio Code :

Les builds CMake utilisent les fichiers suivants :

Fichier	But
CMakeLists.txt	Fichier de configuration CMake général. Obligatoire pour toutes les builds.
CMakePresets.json	Fichier de présélections de configuration pour Visual Studio et Visual Studio Code. Ce fichier ou CMakeSettings.json est requis pour la génération avec Visual Studio.
CMakeSettings.json	Fichier de configuration Visual Studio. Ce fichier ou CMakePresets.json est requis pour la génération avec Visual Studio.
CMakeWorkspaceSettings.json	Fichier de configuration Visual Studio pour les projets avec plusieurs racines, comme dans l’exemple IntercoreComms.
.vscode/settings.json	Fichier de configuration Visual Studio Code. Requis pour la génération avec Visual Studio Code.

Les paramètres CMake sont séparés par des espaces. Le caractère de continuation de ligne « ^ » pour la ligne de commande Windows, « \ » pour la ligne de commande Linux ou « » pour PowerShell peut être utilisé pour la lisibilité, mais n’est pas obligatoire. Le caractère spécifique est déterminé par la configuration du terminal Windows ou Linux.

Fonctions CMake pour Azure Sphere

Le fichier CMakeLists.txt fournit les paramètres de configuration généraux que CMake utilise pour générer une application. Azure Sphere prend en charge l’utilisation des fonctions suivantes dans CMakeLists.txt :

Nom	But
azsphere_target_hardware_definition	Spécifiez le matériel cible.
azsphere_target_add_image_package	Créez un package d’images.

Si vous avez une application existante qui a été créée avec un KIT de développement logiciel (SDK) antérieur à la version 20.04, consultez Convertir une application existante pour utiliser les fonctions CMake.

Le fichier CMakeLists.txt doit appeler la commande de projet avant l’une des fonctions azsphere_ .

Définition du matériel cible

Vous pouvez spécifier le matériel que vous ciblez en appelant la fonction azsphere_target_hardware_definition pour stocker la valeur dans CMakeLists.txt. Cette fonction prend deux paramètres : une liste de répertoires à rechercher et un nom de fichier à rechercher. Par exemple :

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

Le paramètre TARGET_DEFINITION est obligatoire. Il spécifie le nom du fichier de définition matérielle dont votre application a besoin. Le paramètre TARGET_DIRECTORY répertorie les répertoires dans lesquels rechercher ce fichier. Ce paramètre est facultatif ; Si vous l’omettez, CMake recherche uniquement dans le dossier HardwareDefinitions de l’installation du SDK. Pour spécifier plusieurs dossiers, placez chaque nom de dossier entre guillemets doubles et utilisez un espace pour séparer les noms des dossiers, comme dans l’exemple. Dans l’exemple, <path> représente le chemin d’accès au dossier my_app sur votre ordinateur de développement.

Création d’un package d’image

Spécifiez le fichier de package image et tous les fichiers de ressources à inclure lors de la génération en appelant la fonction azsphere_target_add_image_package pour stocker la valeur dans CMakeLists.txt. La fonction azsphere_target_add_image_package et le projet à générer sont requis ; les fichiers de ressources sont facultatifs.

L’appel de fonction suivant crée un package d’image qui contient uniquement l’application Azure Sphere :

azsphere_target_add_image_package(${PROJECT_NAME})

L’exemple suivant crée un package d’image qui contient un certificat en plus d’une application :

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

La cible CMake transmise à azsphere_target_add_image_package doit être nommée ${PROJECT_NAME}, et la fonction azsphere_target_add_image_package ne peut être appelée qu’une seule fois à partir du fichier CMakeLists.txt.

Fonctions CMake déconseillées

Avant la version 24.03 du Kit de développement logiciel (SDK), les fonctions CMake azsphere_configure_tools et azsphere_configure_api étaient utilisées pour spécifier la version cible des outils sdk et l’ensemble d’API cible dans le fichier CMakeLists.txt. Ces fonctions sont désormais déconseillées, et l’ensemble d’API cible doit être spécifié dans le fichier de configuration approprié à la place. Pour plus d’informations, consultez la page Version du runtime d’application , sysroots et API bêta .

Si vous utilisez une version antérieure du Kit de développement logiciel (SDK) et que vous voyez une erreur de configuration CMake concernant une révision d’outils non prise en charge, vous pouvez la contourner en ajoutant à nouveau ces fonctions au CMakeLists.txt. Par exemple :

azsphere_configure_tools(TOOLS_REVISION 23.05) azsphere_configure_api(TARGET_API_SET 16)

Comment supprimer le cache CMake lors de la modification des fichiers de configuration

Si vous modifiez l’un des fichiers de configuration, vous devez supprimer le cache CMake pour vous assurer que les builds suivantes n’échouent pas. Suivez cette procédure avant de tenter une autre build :

Pour les builds Visual Studio Code, exécutez la commande CMake :Delete Cache and Reconfigure à partir de la palette de commandes.
Pour les builds de ligne de commande (CLI), supprimez le répertoire de build que vous avez créé à l’étape précédente.

Visual Studio détecte les modifications apportées au fichier de configuration CMake et supprime automatiquement le cache.

Convertir une application existante pour utiliser les fonctions CMake

Si vous disposez déjà d’une application Azure Sphere créée avec CMake avant le SDK 20.04, vous devez la convertir pour utiliser ces nouvelles fonctions. Vous pouvez toujours créer de telles applications inchangées pour l’instant, mais leur prise en charge est limitée et peut être supprimée dans une version ultérieure.

Pour obtenir un exemple des modifications que vous devez apporter, examinez la façon dont les fichiers de configuration CMakeLists.txt et *.json ont été modifiés pour l’application de haut niveau Mise à jour du MCU externe pour la version 20.04.

Note

En plus des mises à jour permettant d’utiliser les fonctions, ces fichiers ont été mis à jour dans les exemples Azure Sphere pour utiliser des noms de fonction en minuscules, s’alignant ainsi sur les conventions CMake.

CMakeLists.txt modifications de configuration

Les exemples suivants montrent les modifications nécessaires pour mettre à jour le fichier CMakeLists.txt à partir de la version 20.01 ou antérieure afin d’utiliser les nouvelles fonctions.

Exemple de fichier de 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}")

Fichier CMakeLists.txt mis à jour

Le fichier CMakeLists.txt mis à jour appelle les fonctions azsphere_target_hardware_definition pour définir le matériel cible. Il appelle également azsphere_target_add_image_package pour générer le package d’image et éventuellement spécifier les fichiers à inclure dans celui-ci.

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

Note

Les chemins absolus ne sont pas pris en charge pour RESOURCE_FILES.

Configuration de Visual Studio CMakePresets.json

Le fichier CMakePresets.json vous permet de spécifier les options de configuration, de génération et de test courantes, puis de les partager avec des développeurs à l’aide d’autres environnements de développement. Par exemple, vous pouvez utiliser le même fichier de configuration de présélections pour appeler CMake dans Visual Studio, Visual Studio Code, un pipeline d’intégration continue ou à partir de l’interface CLI sur Windows, Linux ou macOS.

Depuis la version 22.07, les projets actuels utilisent des présélections définies dans CMakePresets.json, tandis que les projets existants peuvent continuer à utiliser les paramètres dans CMakeSettings.json. Les exemples sont fournis avec un seul fichier de configuration, CMakePresets.json ou CMakeSettings.json. L’environnement de développement utilise le fichier présent. Reportez-vous à chaque exemple de projet pour voir quel fichier est utilisé. Pour les projets utilisant CMakeSettings.json, consultez Modifications de configuration de Visual Studio CMakeSettings.json.

Les fichiers CMakePresets.json pour une application de haut niveau et pour une application en temps réel sont très similaires ; les seules différences concernent les CMAKE_TOOLCHAIN_FILE variables et ARM_GNU_PATH .

Dans une application de haut niveau, ARM_GNU_PATH n’est pas défini et CMAKE_TOOLCHAIN_FILE est défini comme suit :

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

Dans une application en temps réel, CMAKE_TOOLCHAIN_FILE et ARM_GNU_PATH sont définis comme suit :

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

Configuration de Visual Studio CMakeSettings.json

Les exemples sont fournis avec un fichier de configuration CMakePresets.json ou CMakeSettings.json. Reportez-vous à chaque projet pour voir quel fichier est utilisé. Cette section décrit la configuration CMakeSettings.json. Pour les projets utilisant CMakePresets.json, consultez Modifications de configuration de Visual Studio CMakePresets.json.

Les exemples suivants montrent les modifications nécessaires pour mettre à jour le fichier CMakeSettings.json dans Visual Studio à partir de la version 20.01 ou antérieure afin d’utiliser les nouvelles fonctions.

Exemple de fichier de 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}"
        }
      ]
    }
  ]
}

Fichier de CMakeSettings.json sdk mis à jour

Le fichier CMakeSettings.json mis à jour inclut les modifications suivantes :

Dans le champ « environnements », seul « Azure Sphere » est requis.
Dans le champ « configurations » pour les builds Debug et Release :
- Les valeurs « buildRoot » et « installRoot » ne nécessitent plus le paramètre AzureSphereTargetApiSet.
- La chaîne d’outils CMake est désormais définie dans « cmakeToolChain », au lieu de dans « variables ».
- Le champ « variables » spécifie désormais uniquement l’ensemble d’API cible et utilise la nouvelle valeur « latest-lts » pour indiquer que le projet doit générer avec la racine sysroot (LTS) la plus récente. Les paramètres AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY et AZURE_SPHERE_TARGET_HARDWARE_DEFINITION ne sont plus nécessaires, car ces valeurs sont désormais définies dans le fichierCMakeLists.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"
        }
      ]
    }
  ]
}

Configuration visual Studio Code .vscode/settings.json

Les exemples suivants montrent les modifications nécessaires pour mettre à jour le fichier .vscode/settings.json pour Visual Studio Code à partir de la version 20.01 ou antérieure afin d’utiliser les nouvelles fonctions.

Exemple de fichier .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"
}

Mise à jour du fichier .vscode/settings.json

Le fichier .vscode/settings.json contient les paramètres de l’espace de travail pour Visual Studio Code.

Le fichier settings.json mis à jour inclut les modifications suivantes apportées au champ « cmake.configureSettings » :

Les AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY paramètres et AZURE_SPHERE_TARGET_HARDWARE_DEFINITION ne sont plus nécessaires, car ces valeurs sont désormais définies dans le fichier CMakeLists.txt .
Les CMAKE_TOOLCHAIN_FILE paramètres et AZURE_SPHERE_TARGET_API_SET ne sont plus nécessaires, car ces valeurs sont désormais définies dans le fichier CMakePresets.json . La AZURE_SPHERE_TARGET_API_SET valeur est maintenant "latest-lts", ce qui indique que le projet doit être généré avec la racine sysroot la plus récente long-term-stable (LTS).

Notez que le "cmake.configureArgs" champ a également été supprimé pour des raisons non liées à CMake. (Le champ n’est plus obligatoire, car le --no-warn-unused-cli paramètre n’est pas nécessaire pour cette build.)

Les champs suivants s’appliquent aux extensions :

"cmake.configureOnOpen": true avertit l’extension cmake-tools de commencer la configuration à l’ouverture de l’espace de travail.
"C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools" spécifie le fournisseur IntelliSense à utiliser pour l’extension cpp-tools ; dans ce cas, l’extension 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"
}

Création d’un fichier CMakeWorkspaceSettings.json

Si vous utilisez Visual Studio 2022, version 17.1 ou ultérieure, et que vous avez un projet avec plusieurs racines, comme l’exemple IntercoreComms, vous devez ajouter un fichier CMakeWorkspaceSettings.json au dossier de niveau supérieur du projet. Le fichier comporte deux entrées : une pour spécifier que la build CMake est activée et l’autre contenant les chemins d’accès aux plusieurs racines. Par exemple, pour l’exemple IntercoreComms, l’CMakeWorkspaceSettings.json contient le contenu suivant :

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

Les chemins d’accès sont spécifiés par rapport au dossier contenant le fichier CMakeWorkspaceSettings.json.