Konfigurera versioner med hjälp av CMake

Azure Sphere använder CMake för att konfigurera versioner för program med Visual Studio, Visual Studio-kod och Windows- och Linux-kommandoraderna. CMake är ett system för att skapa flera plattformar med öppen källkod. Allmän information om CMake finns på CMake-wikin.

Följande källor ger information om hur du använder CMake med Visual Studio eller Visual Studio-kod:

• CMake-projekt i Visual Studio
• CMake Tools-tillägg för Visual Studio-kod

I CMake-versioner används följande filer:

Filen	Syfte
CMakeLists.txt	Allmän CMake-konfigurationsfil. Krävs för alla versioner.
CMakePresets.json	Konfigurationsförvalsfil för Visual Studio- och Visual Studio-kod. Den här filen eller CMakeSettings.json krävs för att bygga med Visual Studio.
CMakeSettings.json	Visual Studio-konfigurationsfil. Antingen krävs den här filen eller CMakePresets.json för att bygga med Visual Studio.
CMakeWorkspaceSettings.json	Visual Studio-konfigurationsfil för projekt med flera rötter, som i intercoreComms-exemplet.
.vscode/settings.json	Konfigurationsfil för Visual Studio-kod. Krävs för att bygga med Visual Studio-kod.

CMake-parametrar avgränsas med blanksteg. Linjefortsä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 konfigurationen av Windows- eller Linux-terminalen.

CMake-funktioner för Azure Sphere

Den CMakeLists.txt filen innehåller de allmänna konfigurationsinställningar som CMake använder för att skapa ett program. Azure Sphere har stöd för följande funktioner i CMakeLists.txt:

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

Om du har ett befintligt program som har skapats 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ålmaskinvarudefinition

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

Den TARGET_DEFINITION parametern krävs. Den anger namnet på maskinvarudefinitionsfilen som krävs i programmet. Parametern TARGET_DIRECTORY listar de kataloger där du kan söka efter den här filen. Den här parametern är valfri. om du utelämnar det söker CMake bara i mappen HardwareDefinitions i SDK-installationen. Om du vill ange flera mappar omger du varje mappnamn med dubbla citattecken och använder ett blanksteg för att avgränsa mappnamnen, som i exemplet. I exemplet <representerar sökvägen> till mappen my_app på utvecklingsdatorn.

Skapa avbildningspaket

Ange avbildningspaketfilen och eventuella resursfiler som ska ingå när du bygger 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 projektet som ska byggas 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 heta ${PROJECT_NAME}, och funktionen azsphere_target_add_image_package kan bara anropas en gång från den CMakeLists.txt filen.

Inaktuella CMake-funktioner

Före SDK version 24.03 användes funktionerna CMake azsphere_configure_tools och azsphere_configure_api för att ange mål-SDK-verktygsversionen och mål-API:et i den CMakeLists.txt filen. De här funktionerna är nu inaktuella och mål-API-uppsättningen ska anges i rätt 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:et och ser ett CMake-konfigurationsfel om en ändring av verktyg som inte stöds kan du kringgå den genom att lägga till de funktionerna på nytt i CMakeLists.txt. Som exempel:

azsphere_configure_tools(TOOLS_REVISION 23.05) azsphere_configure_api(TARGET_API_SET 16)

Så här tar du 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-kodversioner kör du kommandot CMake:Delete Cache och Konfigurera om från kommandopaletten.
• För CLI-versioner (kommandoradsversioner) tar du bort den byggkatalog som du skapade i ett tidigare steg.

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

Konvertera en befintlig app till att använda funktionerna CMake

Om du redan har ett Azure Sphere-program som har skapats med CMake före SDK 20.04 bör du konvertera det till att använda de nya funktionerna. 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.

Om du vill ha ett exempel på de ändringar du bör göra kan du titta på hur konfigurationsfilerna CMakeLists.txt och *.json har ändrats för högnivåappen Extern MCU Update för 20.04-versionen.

Observera

Förutom uppdateringar för att använda funktionerna har dessa filer uppdaterats i Azure Sphere-exemplen för att använda gemener i 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 den 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 de azsphere_target_hardware_definition funktionerna för att ange målmaskinvaran. Dessutom anropas azsphere_target_add_image_package för att skapa avbildningspaketet och om du vill kan du 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")

Observera

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 som använder 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 på Windows, Linux eller macOS.

Från och med version 22.07 använder aktuella projekt förval definierade 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. I utvecklingsmiljön används filen som finns. Se varje exempelprojekt för att se vilken fil som används. Information om projekt med CMakeSettings.json finns i Visual Studio CMakeSettings.json konfigurationsändringar.

De CMakePresets.json filer för ett program på hög nivå och för ett realtidsprogram är mycket lika; de enda skillnaderna är i CMAKE_TOOLCHAIN_FILE och ARM_GNU_PATH variabler.

I ett program på hög nivå anges ARM_GNU_PATH inte och CMAKE_TOOLCHAIN_FILE anges så här:

    "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 konfigurationen. Information om projekt med CMakePresets.json finns i Visual Studio CMakePresets.json konfigurationsändringar.

Följande exempel visar de ändringar som krävs för att uppdatera CMakeSettings.json-filen 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}"
        }
      ]
    }
  ]
}

Uppdaterad SDK-CMakeSettings.json-fil

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 versionsversioner:
  • Värdena "buildRoot" och "installRoot" kräver inte längre inställningen AzureSfärTargetApiSet.
  • Verktygslådan CMake 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 värdet "latest-lts" 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 denCMakeLists.txt filen.

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

Visual Studio Code .vscode/settings.json konfiguration

I följande exempel visas de ändringar som krävs för att uppdatera .vscode/settings.json-filen för Visual Studio-kod 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"
}

Uppdaterad .vscode/settings.json-fil

Vscode/settings.json-filen innehåller arbetsyteinställningar för Visual Studio-kod.

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

• Och AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORYAZURE_SPHERE_TARGET_HARDWARE_DEFINITION inställningarna är inte längre obligatoriska, eftersom dessa värden nu anges i denCMakeLists.txt filen.
• Inställningarna CMAKE_TOOLCHAIN_FILE och AZURE_SPHERE_TARGET_API_SET krävs inte längre eftersom dessa värden nu anges i den CMakePresets.json filen. 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 är inte längre obligatoriskt 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 tillägget cmake-tools för att börja konfigurera när arbetsytan öppnas.

• "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools" anger vilken IntelliSense-provider som ska användas för tillägget cpp-tools . i det här fallet cmake-verktygstillä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 du har ett projekt med flera rötter, till exempel intercoreComms-exemplet, måste du lägga till en CMakeWorkspaceSettings.json-fil i projektets toppnivåmapp. 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. Exempel: för IntercoreComms-exemplet har CMakeWorkspaceSettings.json följande innehåll:

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

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