Builds configureren met CMake

Artikel
03/27/2024

Azure Sphere gebruikt CMake om builds voor toepassingen te configureren met Visual Studio, Visual Studio Code en de Windows- en Linux-opdrachtregels. CMake is een open-source, platformoverschrijdend merksysteem. Zie de CMake-wiki voor algemene informatie over CMake.

De volgende bronnen bieden informatie over het gebruik van CMake met Visual Studio of Visual Studio Code:

CMake-builds gebruiken de volgende bestanden:

Bestand	Purpose
CMakeLists.txt	Algemeen CMake-configuratiebestand. Vereist voor alle builds.
CMakePresets.json	Configuratie-voorinstellingenbestand voor Visual Studio en Visual Studio Code. Dit bestand of CMakeSettings.json is vereist voor het bouwen met Visual Studio.
CMakeSettings.json	Visual Studio-configuratiebestand. Dit bestand of CMakePresets.json is vereist voor het bouwen met Visual Studio.
CMakeWorkspaceSettings.json	Visual Studio-configuratiebestand voor projecten met meerdere wortels, zoals in het IntercoreComms-voorbeeld.
.vscode/settings.json	Visual Studio Code-configuratiebestand. Vereist voor het bouwen met Visual Studio Code.

CMake-parameters worden gescheiden door spaties. Het regelvolgteken ^" voor de Windows-opdrachtregel, " \ " voor de Linux-opdrachtregel of "'" voor PowerShell kan worden gebruikt voor leesbaarheid, maar is niet vereist. Het specifieke teken wordt bepaald door de configuratie van de Windows- of Linux-terminal.

CMake-functies voor Azure Sphere

Het CMakeLists.txt-bestand bevat de algemene configuratie-instellingen die CMake gebruikt om een toepassing te bouwen. Azure Sphere ondersteunt het gebruik van de volgende functies in CMakeLists.txt:

Naam	Purpose
azsphere_target_hardware_definition	Geef doelhardware op.
azsphere_target_add_image_package	Een installatiekopieënpakket maken.

Als u een bestaande toepassing hebt die is gemaakt met een SDK die ouder is dan 20.04, raadpleegt u Een bestaande app converteren om de CMake-functies te gebruiken.

Het CMakeLists.txt-bestand moet de projectopdracht aanroepen voordat een van de azsphere_ functies.

Definitie van doelhardware

U kunt de hardware opgeven waarop u zich richt door de functie azsphere_target_hardware_definition aan te roepen om de waarde op te slaan in CMakeLists.txt. Deze functie heeft twee parameters: een lijst met mappen om te zoeken en een bestandsnaam om naar te zoeken. Bijvoorbeeld:

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

De parameter TARGET_DEFINITION is vereist. Hiermee geeft u de naam op van het hardwaredefinitiebestand dat voor uw toepassing is vereist. De parameter TARGET_DIRECTORY bevat de mappen waarin u naar dit bestand kunt zoeken. Deze parameter is optioneel; als u dit weglaat, wordt CMake alleen weergegeven in de map HardwareDefinitions in de SDK-installatie. Als u meerdere mappen wilt opgeven, plaatst u elke mapnaam tussen dubbele aanhalingstekens en gebruikt u een spatie om mapnamen te scheiden, zoals in het voorbeeld. In het voorbeeld <vertegenwoordigt pad> het pad naar de map my_app op uw ontwikkelcomputer.

Installatiekopieënpakket maken

Geef het installatiekopieënpakketbestand en eventuele resourcebestanden op die moeten worden opgenomen bij het bouwen door de functie azsphere_target_add_image_package aan te roepen om de waarde op te slaan in CMakeLists.txt. De azsphere_target_add_image_package-functie en het te bouwen project zijn vereist; de resourcebestanden zijn optioneel.

Met de volgende functieaanroep wordt een installatiekopieënpakket gemaakt dat alleen de Azure Sphere-toepassing bevat:

azsphere_target_add_image_package(${PROJECT_NAME})

In het volgende voorbeeld wordt een installatiekopieënpakket gemaakt dat naast een toepassing een certificaat bevat:

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

Het CMake-doel dat aan azsphere_target_add_image_package is doorgegeven, moet de naam ${PROJECT_NAME} hebben en de functie azsphere_target_add_image_package kan slechts eenmaal worden aangeroepen vanuit het CMakeLists.txt-bestand.

Afgeschafte CMake-functies

Vóór SDK-versie 24.03 werden de CMake-functies azsphere_configure_tools en azsphere_configure_api gebruikt om de sdk-doelhulpprogramma'sversie en doel-API op te geven die zijn ingesteld in het CMakeLists.txt-bestand. Deze functies zijn nu afgeschaft en de doel-API-set moet in plaats daarvan worden opgegeven in het juiste configuratiebestand. Zie de pagina Toepassingsruntimeversie, sysroots en beta-API's voor meer informatie.

Als u een oudere versie van de SDK gebruikt en een CMake-configuratiefout ziet over een revisie van niet-ondersteunde hulpprogramma's, kunt u deze omzeilen door deze functies opnieuw toe te voegen aan de CMakeLists.txt. Als voorbeeld:

azsphere_configure_tools(TOOLS_REVISION 23.05) azsphere_configure_api(TARGET_API_SET 16)

De CMake-cache verwijderen bij het wijzigen van configuratiebestanden

Als u een van de configuratiebestanden wijzigt, moet u de CMake-cache verwijderen om ervoor te zorgen dat volgende builds niet mislukken. Volg deze procedure voordat u een andere build uitvoert:

Voor Visual Studio Code-builds voert u de opdracht CMake:Cache verwijderen en opnieuw configureren uit vanuit het opdrachtenpalet.
Voor cli-builds (opdrachtregel) verwijdert u de buildmap die u in een eerdere stap hebt gemaakt.

Visual Studio detecteert wijzigingen in het CMake-configuratiebestand en verwijdert de cache automatisch.

Een bestaande app converteren om de CMake-functies te gebruiken

Als u al een Azure Sphere-toepassing hebt die is gebouwd met CMake vóór de 20.04 SDK, moet u deze converteren om deze nieuwe functies te gebruiken. U kunt dergelijke toepassingen voorlopig nog ongewijzigd bouwen, maar de ondersteuning voor deze toepassingen is beperkt en kan in een toekomstige release worden verwijderd.

Voor een voorbeeld van de wijzigingen die u moet aanbrengen, bekijkt u hoe de configuratiebestanden voor CMakeLists.txt en *.json zijn gewijzigd voor de externe MCU-app op hoog niveau voor de 20.04-release.

Opmerking

Naast updates voor het gebruik van de functies, zijn deze bestanden bijgewerkt in de Azure Sphere-voorbeelden om functienamen in kleine letters te gebruiken, waardoor deze overeenkomen met de CMake-conventies.

configuratiewijzigingen CMakeLists.txt

In de volgende voorbeelden ziet u de wijzigingen die nodig zijn om het CMakeLists.txt-bestand vanaf 20.01 of eerder bij te werken voor het gebruik van de nieuwe functies.

Voorbeeld 20.01 SDK CMakeLists.txt-bestand

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

CMakeLists.txt-bestand bijgewerkt

Het bijgewerkte CMakeLists.txt-bestand roept de azsphere_target_hardware_definition-functies aan om de doelhardware in te stellen. Er wordt ook azsphere_target_add_image_package aangeroepen om het installatiekopieënpakket te bouwen en eventueel de bestanden op te geven die erin moeten worden opgenomen.

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

Opmerking

Absolute paden worden niet ondersteund voor RESOURCE_FILES.

Configuratie van Visual Studio CMakePresets.json

Met het CMakePresets.json-bestand kunt u algemene configuratie-, build- en testopties opgeven en deze vervolgens delen met ontwikkelaars via andere ontwikkelomgevingen. U kunt bijvoorbeeld hetzelfde configuratiebestand met voorinstellingen gebruiken om CMake aan te roepen in Visual Studio, Visual Studio Code, een pijplijn voor continue integratie of vanuit de CLI op Windows, Linux of macOS.

Vanaf versie 22.07 gebruiken huidige projecten voorinstellingen die zijn gedefinieerd in CMakePresets.json, terwijl bestaande projecten instellingen in CMakeSettings.json kunnen blijven gebruiken. Voorbeelden worden geleverd met slechts één configuratiebestand, CMakePresets.json of CMakeSettings.json. De ontwikkelomgeving gebruikt het bestand dat aanwezig is. Raadpleeg elk voorbeeldproject om te zien welk bestand wordt gebruikt. Zie Configuratiewijzigingen in Visual Studio CMakeSettings.json voor projecten die gebruikmaken van CMakeSettings.json.

De CMakePresets.json bestanden voor een toepassing op hoog niveau en voor een realtime-toepassing lijken sterk op elkaar; de enige verschillen zijn in de CMAKE_TOOLCHAIN_FILE variabelen en ARM_GNU_PATH .

In een toepassing ARM_GNU_PATH op hoog niveau is niet ingesteld en CMAKE_TOOLCHAIN_FILE wordt deze als volgt ingesteld:

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

In een realtime-toepassing CMAKE_TOOLCHAIN_FILE en ARM_GNU_PATH als volgt zijn ingesteld:

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

Configuratie van Visual Studio CMakeSettings.json

Voorbeelden worden geleverd met een CMakePresets.json of CMakeSettings.json configuratiebestand. Raadpleeg elk project om te zien welk bestand wordt gebruikt. In deze sectie wordt de configuratie van de CMakeSettings.json beschreven. Zie Configuratiewijzigingen in Visual Studio CMakePresets.json voor projecten die gebruikmaken van CMakePresets.json.

In de volgende voorbeelden ziet u de wijzigingen die nodig zijn om het CMakeSettings.json-bestand in Visual Studio vanaf 20.01 of eerder bij te werken om de nieuwe functies te gebruiken.

Voorbeeld van 20.01 SDK-CMakeSettings.json-bestand

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

Sdk-CMakeSettings.json-bestand bijgewerkt

Het bijgewerkte CMakeSettings.json-bestand bevat de volgende wijzigingen:

In het veld 'omgevingen' is alleen 'Azure Sphere' vereist.
In het veld 'configuraties' voor zowel de foutopsporings- als release-builds:
- Voor de waarden 'buildRoot' en 'installRoot' is de instelling AzureSphereTargetApiSet niet meer vereist.
- De CMake-hulpprogrammaketen is nu gedefinieerd in 'cmakeToolChain', in plaats van in 'variabelen'.
- Het veld 'variabelen' geeft nu alleen de doel-API-set op en gebruikt de nieuwe waarde 'latest-lts' om aan te geven dat het project moet worden gebouwd met de meest recente ltS-sysroot (long-term stable). De instellingen voor AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY en AZURE_SPHERE_TARGET_HARDWARE_DEFINITION zijn niet meer vereist, omdat deze waarden nu zijn ingesteld in het CMakeLists.txt-bestand.

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

Configuratie van Visual Studio Code.vscode/settings.json

In de volgende voorbeelden ziet u de wijzigingen die nodig zijn om het bestand .vscode/settings.json voor Visual Studio Code vanaf 20.01 of eerder bij te werken om de nieuwe functies te kunnen gebruiken.

Voorbeeld 20.01 SDK .vscode/settings.json-bestand

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

Vscode/settings.json-bestand bijgewerkt

Het bestand .vscode/settings.json bevat werkruimte-instellingen voor Visual Studio Code.

Het bijgewerkte settings.json-bestand bevat de volgende wijzigingen in het veld cmake.configureSettings:

De AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY instellingen en AZURE_SPHERE_TARGET_HARDWARE_DEFINITION zijn niet meer vereist, omdat deze waarden nu zijn ingesteld in het bestandCMakeLists.txt .
De CMAKE_TOOLCHAIN_FILE instellingen en AZURE_SPHERE_TARGET_API_SET zijn niet meer vereist, omdat deze waarden nu zijn ingesteld in het bestand CMakePresets.json . De AZURE_SPHERE_TARGET_API_SET waarde is nu "latest-lts", wat aangeeft dat het project moet worden gebouwd met de meest recente LTS-sysroot (long-term stable).

Houd er rekening mee dat het "cmake.configureArgs" veld ook is verwijderd om redenen die geen verband houden met CMake. (Het veld is niet meer vereist omdat de --no-warn-unused-cli parameter niet nodig is voor deze build.)

De volgende velden zijn van toepassing op extensies:

"cmake.configureOnOpen": true hiermee wordt de extensie cmake-tools gewaarschuwd om te beginnen met configureren wanneer de werkruimte wordt geopend.
"C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools" specificeert de IntelliSense-provider die moet worden gebruikt voor de cpp-tools-extensie ; in dit geval de extensie 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"
}

Een CMakeWorkspaceSettings.json-bestand maken

Als u Visual Studio 2022 versie 17.1 of hoger gebruikt en u een project hebt met meerdere hoofdmappen, zoals het IntercoreComms-voorbeeld, moet u een CMakeWorkspaceSettings.json-bestand toevoegen aan de map op het hoogste niveau van het project. Het bestand heeft twee vermeldingen, één om op te geven dat CMake-build is ingeschakeld en één met de paden naar de meerdere wortels. Voor het Voorbeeld van IntercoreComms bevat de CMakeWorkspaceSettings.json bijvoorbeeld de volgende inhoud:

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

De paden worden opgegeven ten opzichte van de map die het CMakeWorkspaceSettings.json-bestand bevat.

Delen via