Konfigurera versioner med hjälp av CMake

Viktigt!

Det här är dokumentationen om Azure Sphere (Legacy). Azure Sphere (Legacy) upphör den 27 september 2027 och användarna måste migrera till Azure Sphere (integrerad) vid den här tiden. Använd versionsväljaren ovanför TOC för att visa dokumentationen om Azure Sphere (integrerad).

Azure Sphere använder CMake för att konfigurera versioner för program med Visual Studio, Visual Studio Code och Windows- och Linux-kommandoraderna. CMake är ett plattformsoberoende system med öppen källkod. Allmän information om CMake finns i CMake Wiki.

Följande källor innehåller information om hur du använder CMake med Visual Studio eller Visual Studio Code:

• CMake-projekt i Visual Studio
• CMake Tools-tillägget för Visual Studio Code

CMake-versioner använder följande filer:

Fil	Syfte
CMakeLists.txt	Allmän CMake-konfigurationsfil. Krävs för alla versioner.
CMakePresets.json	Konfigurationsförinställningar för Visual Studio och Visual Studio Code. Antingen krävs den här filen eller CMakeSettings.json för att skapa med Visual Studio.
CMakeSettings.json	Visual Studio-konfigurationsfil. Antingen krävs den här filen eller CMakePresets.json för att skapa med Visual Studio.
CMakeWorkspaceSettings.json	Visual Studio-konfigurationsfil för projekt med flera rötter, som i IntercoreComms-exemplet.
.vscode/settings.json	Visual Studio Code-konfigurationsfil. Krävs för att skapa med Visual Studio Code.

CMake-parametrar avgränsas med blanksteg. Radfortsättningstecknet ^för Windows-kommandoraden , " \ " för Linux-kommandoraden eller "'" för Powershell kan användas för läsbarhet men krävs inte. Det specifika tecknet bestäms av windows- eller Linux-terminalkonfigurationen.

CMake-funktioner för Azure Sphere

Filen CMakeLists.txt innehåller de allmänna konfigurationsinställningar som CMake använder för att skapa ett program. Azure Sphere stöder användning av följande funktioner i CMakeLists.txt:

Name	Syfte
azsphere_target_hardware_definition	Ange målmaskinvara.
azsphere_target_add_image_package	Skapa ett avbildningspaket.

Om du har ett befintligt program som skapades med ett SDK tidigare än 20.04 läser du Konvertera en befintlig app för att använda CMake-funktionerna.

Den CMakeLists.txt filen måste anropa projektkommandot innan någon av de azsphere_ funktionerna.

Målmaskinvaradefinition

Du kan ange vilken maskinvara du vill använda genom att anropa funktionen azsphere_target_hardware_definition för att lagra värdet i CMakeLists.txt. Den här funktionen tar två parametrar: en lista över kataloger att söka efter och ett filnamn att söka efter. Till exempel:

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

Parametern TARGET_DEFINITION krävs. Den anger namnet på den maskinvarudefinitionsfil som programmet kräver. Parametern TARGET_DIRECTORY listar de kataloger där filen ska sökas. Den här parametern är valfri. Om du utelämnar det ser CMake bara ut i mappen HardwareDefinitions i SDK-installationen. Om du vill ange flera mappar omger du varje mappnamn inom dubbla citattecken och använder ett blanksteg för att separera mappnamn, som i exemplet. I exemplet <representerar sökvägen> sökvägen till mappen my_app på utvecklingsdatorn.

Skapa avbildningspaket

Ange avbildningspaketfilen och eventuella resursfiler som ska inkluderas när du skapar genom att anropa funktionen azsphere_target_add_image_package för att lagra värdet i CMakeLists.txt. Funktionen azsphere_target_add_image_package och det projekt som ska skapas krävs. Resursfilerna är valfria.

Följande funktionsanrop skapar ett avbildningspaket som endast innehåller Azure Sphere-programmet:

azsphere_target_add_image_package(${PROJECT_NAME})

I nästa exempel skapas ett avbildningspaket som innehåller ett certifikat utöver ett program:

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

CMake-målet som skickas till azsphere_target_add_image_package måste ha namnet ${PROJECT_NAME}, och funktionen azsphere_target_add_image_package kan bara anropas en gång från filen CMakeLists.txt.

Inaktuella CMake-funktioner

Innan SDK version 24.03 användes CMake-funktionerna azsphere_configure_tools och azsphere_configure_api för att ange mål-SDK-verktygens version och mål-API som angetts i filen CMakeLists.txt. Dessa funktioner är nu inaktuella och mål-API-uppsättningen bör anges i lämplig konfigurationsfil i stället. Mer information finns på sidan Programkörningsversion, sysroots och Beta-API:er .

Om du använder en äldre version av SDK:t och ser ett CMake-konfigurationsfel om en revision av verktyg som inte stöds kan du kringgå den genom att lägga till funktionerna i CMakeLists.txt igen. Som exempel:

azsphere_configure_tools(TOOLS_REVISION 23.05) azsphere_configure_api(TARGET_API_SET 16)

Ta bort CMake-cachen när du ändrar konfigurationsfiler

Om du ändrar en av konfigurationsfilerna bör du ta bort CMake-cachen för att säkerställa att efterföljande versioner inte misslyckas. Följ den här proceduren innan du försöker skapa en annan version:

• För Visual Studio Code-versioner kör du kommandot CMake:Delete Cache och Rekonfigurera från kommandopaletten.
• För kommandoradsversioner (CLI) tar du bort den byggkatalog som du skapade i ett tidigare steg.

Visual Studio identifierar ändringar i CMake-konfigurationsfilen och tar bort cachen automatiskt.

Konvertera en befintlig app till att använda CMake-funktionerna

Om du redan har ett Azure Sphere-program som skapades med CMake före SDK 20.04 bör du konvertera det till att använda dessa nya funktioner. Du kan fortfarande skapa sådana program oförändrade för tillfället, men stödet för dem är begränsat och kan tas bort i en framtida version.

Ett exempel på de ändringar du bör göra finns i hur konfigurationsfilerna CMakeLists.txt och *.json ändrades för den externa MCU Update-högnivåappen för 20.04-versionen.

Kommentar

Förutom uppdateringar för att använda funktionerna har dessa filer uppdaterats i Azure Sphere-exemplen för att använda gemena funktionsnamn, vilket överensstämmer med CMake-konventioner.

CMakeLists.txt konfigurationsändringar

I följande exempel visas de ändringar som krävs för att uppdatera CMakeLists.txt-filen från 20.01 eller tidigare för att använda de nya funktionerna.

Exempel 20.01 SDK CMakeLists.txt fil

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

Uppdaterad CMakeLists.txt fil

Den uppdaterade CMakeLists.txt-filen anropar azsphere_target_hardware_definition-funktionerna för att ange målmaskinvaran. Den anropar också azsphere_target_add_image_package för att skapa avbildningspaketet och kan också ange vilka filer som ska ingå i det.

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

Kommentar

Absoluta sökvägar stöds inte för RESOURCE_FILES.

Visual Studio CMakePresets.json konfiguration

Med CMakePresets.json-filen kan du ange vanliga konfigurations-, bygg- och testalternativ och sedan dela dem med utvecklare med hjälp av andra utvecklingsmiljöer. Du kan till exempel använda samma konfigurationsfil för förinställningar för att anropa CMake i Visual Studio, Visual Studio Code, en pipeline för kontinuerlig integrering eller från CLI i Windows, Linux eller macOS.

Från och med version 22.07 använder aktuella projekt förinställningar som definierats i CMakePresets.json, medan befintliga projekt kan fortsätta att använda inställningar i CMakeSettings.json. Exempel levereras med endast en konfigurationsfil, antingen CMakePresets.json eller CMakeSettings.json. Utvecklingsmiljön använder filen som finns. Se varje exempelprojekt för att se vilken fil som används. Information om projekt som använder CMakeSettings.json finns i Visual Studio CMakeSettings.json konfigurationsändringar.

De CMakePresets.json filerna för ett högnivåprogram och för ett realtidsprogram är mycket lika; de enda skillnaderna är i variablerna CMAKE_TOOLCHAIN_FILE och ARM_GNU_PATH .

I ett högnivåprogram ARM_GNU_PATH anges inte och CMAKE_TOOLCHAIN_FILE anges på följande sätt:

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

I ett realtidsprogram CMAKE_TOOLCHAIN_FILE och ARM_GNU_PATH anges på följande sätt:

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

Visual Studio CMakeSettings.json konfiguration

Exempel levereras med antingen en CMakePresets.json- eller CMakeSettings.json konfigurationsfil. Se varje projekt för att se vilken fil som används. I det här avsnittet beskrivs CMakeSettings.json konfiguration. Information om projekt som använder CMakePresets.json finns i Visual Studio CMakePresets.json konfigurationsändringar.

I följande exempel visas de ändringar som krävs för att uppdatera filen CMakeSettings.json i Visual Studio från 20.01 eller tidigare för att använda de nya funktionerna.

Exempel 20.01 SDK CMakeSettings.json fil

{
  "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 fil har uppdaterats

Den uppdaterade CMakeSettings.json-filen innehåller följande ändringar:

• I fältet "miljöer" krävs endast "Azure Sphere".
• I fältet "konfigurationer" för både felsöknings- och versionsversionerna:
  • Värdena "buildRoot" och "installRoot" kräver inte längre inställningen AzureSphereTargetApiSet.
  • CMake-verktygskedjan definieras nu i "cmakeToolChain", i stället för i "variabler".
  • Fältet "variabler" anger nu endast mål-API-uppsättningen och använder det nya "latest-lts"-värdet för att indikera att projektet ska byggas med den senaste långsiktiga stabila sysrooten (LTS). Inställningarna för AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY och AZURE_SPHERE_TARGET_HARDWARE_DEFINITION krävs inte längre eftersom dessa värden nu anges i filen 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"
        }
      ]
    }
  ]
}

Konfiguration av Visual Studio Code .vscode/settings.json

I följande exempel visas de ändringar som krävs för att uppdatera .vscode/settings.json-filen för Visual Studio Code från 20.01 eller tidigare för att använda de nya funktionerna.

Exempel 20.01 SDK .vscode/settings.json-fil

{
    "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-fil har uppdaterats

Filen .vscode/settings.json innehåller arbetsyteinställningar för Visual Studio Code.

Den uppdaterade settings.json-filen innehåller följande ändringar i fältet "cmake.configureSettings":

• AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY Inställningarna och AZURE_SPHERE_TARGET_HARDWARE_DEFINITION krävs inte längre eftersom dessa värden nu anges i filen CMakeLists.txt.
• CMAKE_TOOLCHAIN_FILE Inställningarna och AZURE_SPHERE_TARGET_API_SET krävs inte längre eftersom dessa värden nu anges i filen CMakePresets.json. Värdet AZURE_SPHERE_TARGET_API_SET är nu "latest-lts", vilket anger att projektet ska byggas med den senaste långsiktiga stabila sysrooten (LTS).

Observera att fältet "cmake.configureArgs" också har tagits bort av orsaker som inte är relaterade till CMake. (Fältet krävs inte längre eftersom parametern --no-warn-unused-cli inte behövs för den här versionen.)

Följande fält gäller för tillägg:

• "cmake.configureOnOpen": true meddelar cmake-tools-tillägget för att börja konfigurera när arbetsytan öppnas.

• "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools" anger den IntelliSense-provider som ska användas för cpp-tools-tillägget . I det här fallet cmake-tools-tillägget .

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

Skapa en CMakeWorkspaceSettings.json fil

Om du använder Visual Studio 2022, version 17.1 eller senare och har ett projekt med flera rötter, till exempel IntercoreComms-exemplet, måste du lägga till en CMakeWorkspaceSettings.json fil i mappen på den översta nivån i projektet. Filen har två poster, en för att ange att CMake-versionen är aktiverad och en som innehåller sökvägarna till flera rötter. För exemplet IntercoreComms har CMakeWorkspaceSettings.json till exempel följande innehåll:

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

Sökvägarna anges i förhållande till mappen som innehåller CMakeWorkspaceSettings.json-filen.