Configurer des builds à l’aide de CMake

Azure Sphere utilise CMake pour configurer des builds d’applications avec Visual Studio, Visual Studio Code, et les lignes de commande Windows et Linux. CMake est un système de construction multiplateforme et 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 :

• Projets CMake dans Visual Studio
• Extension CMake Tools pour Visual Studio Code

Les builds CMake utilisent les fichiers suivants :

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 à utiliser dépend de la configuration du terminal (Windows ou Linux).

Fonctions CMake pour Azure Sphere

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

Si vous disposez déjà d’une application qui a été créée avec un 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 project avant toute fonction 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 requis. Il spécifie le nom du fichier de définition matérielle requis par votre application. 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 Kit de développement logiciel (SDK). Pour spécifier plusieurs dossiers, placez chaque nom de dossier entre guillemets doubles et utilisez un espace pour séparer les noms de dossiers, comme dans l’exemple. Dans l’exemple, <le chemin d’accès> 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 du package d’image et 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 obligatoires ; les fichiers de ressources sont facultatifs.

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

azsphere_target_add_image_package(${PROJECT_NAME})

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

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

La cible CMake passée à 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épréciées

Avant sdk version 24.03, les fonctions CMake azsphere_configure_tools et azsphere_configure_api ont été utilisées pour spécifier la version des outils sdk cibles 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 le contourner en ajoutant 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 après un changement de fichier de configuration

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

• Pour les builds Visual Studio Code, exécutez la commande CMake :Delete Cache et Reconfigure à partir de la palette de commandes.
• Pour les builds avec la CLI, supprimez le répertoire de build que vous avez créé à une étape précédente.

Visual Studio détecte les modifications apportées au fichier de configuration de 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 qui a été générée avec CMake et un SDK antérieur à la version 20.04, vous devez la convertir pour utiliser les nouvelles fonctions. Vous pouvez toujours créer de telles applications inchangées pour l’instant, mais la prise en charge de ces applications est limitée et peut être supprimée dans une version ultérieure.

Pour obtenir un exemple des modifications à apporter, examinez les modifications qui ont été effectuées dans les fichiers de configuration CMakeLists.txt et *.json de l’application générale Mise à jour de MCU externe pour la version 20.04.

Modifications dans le fichier de configuration CMakeLists.txt

Les exemples ci-dessous montrent les modifications à apporter au fichier CMakeLists.txt de la version 20.01 ou d’une version antérieure pour le mettre à jour avec les nouvelles fonctions.

Exemple de fichier CMakeLists.txt du 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 la fonction azsphere_target_add_image_package pour générer le package d’image et éventuellement spécifier les fichiers à inclure dans ce package.

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

Configuration de visual Studio CMakePresets.json

Le fichier CMakePresets.json vous permet de spécifier des options courantes de configuration, de génération et de test, puis de les partager avec les développeurs à l’aide d’autres environnements de développement. Par exemple, vous pouvez utiliser le même fichier de configuration prédéfini 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.

À compter de 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 des 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 Visual Studio CMakeSettings.json modifications de configuration.

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 sont dans les variables et ARM_GNU_PATH les CMAKE_TOOLCHAIN_FILE variables.

Dans une application de haut niveau, ARM_GNU_PATH n’est pas définie et CMAKE_TOOLCHAIN_FILE est définie 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éfinies 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 Visual Studio CMakePresets.json modifications de configuration.

Les exemples ci-dessous montrent les modifications à apporter au fichier CMakeSettings.json pour Visual Studio de la version 20.01 ou d’une version antérieure pour le mettre à jour avec les nouvelles fonctions.

Exemple de fichier CMakeSettings.json du 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 CMakeSettings.json du SDK mis à jour

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

• Dans le champ « environments », seul « Azure Sphere » doit être spécifié.
• Dans le champ « configurations » pour les builds Debug et Release :
  • Les valeurs « buildRoot » et « installRoot » n’ont plus besoin d’être définies avec le paramètre AzureSphereTargetApiSet.
  • La chaîne d’outils CMake est maintenant définie dans « cmakeToolChain », et plus dans « variables ».
  • Désormais, le champ « variables » spécifie uniquement l’ensemble d’API cibles et utilise la nouvelle valeur « latest-lts » pour indiquer que le projet doit être généré avec le sysroot LTS le plus récent. Les paramètres AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY et AZURE_SPHERE_TARGET_HARDWARE_DEFINITION ne sont plus nécessaires, car ces valeurs sont maintenant définies dans le fichier 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"
        }
      ]
    }
  ]
}

Configuration de 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 pour utiliser les nouvelles fonctions.

Exemple 20.01 SDK .vscode/settings.json fichier

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

Fichier .vscode/settings.json mis à jour

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 les paramètres ne sont plus obligatoires, 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 les paramètres ne sont plus obligatoires, 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 générer avec le sysroot le plus récent à long terme 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 à configurer lorsque l’espace de travail s’ouvre.

• "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 disposez d’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 qu’elle contient les chemins d’accès aux plusieurs racines. Par exemple, pour l’exemple IntercoreComms, le CMakeWorkspaceSettings.json a 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.