Konfigurace sestavení pomocí CMake

Důležité

Toto je dokumentace k Azure Sphere (starší verze). Azure Sphere (starší verze) se vyřazuje 27. září 2027 a uživatelé musí do této doby migrovat do Azure Sphere (integrované). K zobrazení dokumentace k Azure Sphere (integrované) použijte selektor verzí umístěný nad obsahem.

Azure Sphere pomocí CMake konfiguruje sestavení pro aplikace pomocí sady Visual Studio, Visual Studio Code a příkazového řádku pro Windows a Linux. CMake je opensourcový multiplatformní systém. Obecné informace o CMake najdete na wikiwebu CMake.

Následující zdroje poskytují informace o používání CMake se sadou Visual Studio nebo Visual Studio Code:

• Projekty CMake v sadě Visual Studio
• Rozšíření CMake Tools pro Visual Studio Code

Sestavení CMake používají následující soubory:

Soubor	Účel
CMakeLists.txt	Obecný konfigurační soubor CMake Vyžaduje se pro všechna sestavení.
CMakePresets.json	Konfigurační přednastavený soubor pro Visual Studio a Visual Studio Code Tento soubor nebo CMakeSettings.json se vyžaduje pro sestavení pomocí sady Visual Studio.
CMakeSettings.json	Konfigurační soubor sady Visual Studio. Tento soubor nebo CMakePresets.json se vyžaduje pro sestavení pomocí sady Visual Studio.
CMakeWorkspaceSettings.json	Konfigurační soubor sady Visual Studio pro projekty s více kořeny, jako je v ukázce IntercoreComms.
.vscode/settings.json	Konfigurační soubor editoru Visual Studio Code Vyžaduje se pro sestavení pomocí editoru Visual Studio Code.

Parametry CMake jsou oddělené mezerami. Znak pokračování řádku ^pro příkazový řádek Windows, \ " pro příkazový řádek Linuxu nebo "'" pro PowerShell lze použít pro čitelnost, ale není vyžadován. Konkrétní znak je určen konfigurací terminálu systému Windows nebo Linux.

Funkce CMake pro Azure Sphere

Soubor CMakeLists.txt poskytuje obecné nastavení konfigurace, které CMake používá k sestavení aplikace. Azure Sphere podporuje použití následujících funkcí v CMakeLists.txt:

Název	Účel
azsphere_target_hardware_definition	Zadejte cílový hardware.
azsphere_target_add_image_package	Vytvořte balíček image.

Pokud máte existující aplikaci vytvořenou pomocí sady SDK starší než 20.04, přečtěte si téma Převod existující aplikace na používání funkcí CMake.

Soubor CMakeLists.txt musí před některou z funkcí azsphere_ volat příkaz projektu.

Definice cílového hardwaru

Hardware, na který cílíte , můžete zadat zavoláním funkce azsphere_target_hardware_definition , která uloží hodnotu do CMakeLists.txt. Tato funkce má dva parametry: seznam adresářů, které se mají vyhledat, a název souboru, který se má vyhledat. Příklad:

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

Parametr TARGET_DEFINITION je povinný. Určuje název souboru definice hardwaru, který vaše aplikace vyžaduje. Parametr TARGET_DIRECTORY obsahuje adresáře, ve kterých se má tento soubor hledat. Tento parametr je volitelný; Pokud ho vynecháte, CMake vypadá pouze ve složce HardwareDefinitions v instalaci sady SDK. Pokud chcete zadat více složek, uzavřete každý název složky do dvojitých uvozovek a použijte mezeru k oddělení názvů složek, jako v příkladu. V příkladu <cesta> představuje cestu ke složce my_app ve vašem vývojovém počítači.

Vytvoření balíčku image

Zadejte soubor balíčku image a všechny soubory prostředků, které mají být zahrnuty při sestavování voláním funkce azsphere_target_add_image_package pro uložení hodnoty v CMakeLists.txt. Funkce azsphere_target_add_image_package a projekt, který se má sestavit, jsou povinné. Soubory prostředků jsou volitelné.

Následující volání funkce vytvoří balíček image, který obsahuje pouze aplikaci Azure Sphere:

azsphere_target_add_image_package(${PROJECT_NAME})

Další příklad vytvoří balíček image, který obsahuje certifikát kromě aplikace:

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

Cíl CMake předaný azsphere_target_add_image_package musí mít název ${PROJECT_NAME} a funkci azsphere_target_add_image_package lze volat pouze jednou ze souboru CMakeLists.txt.

Zastaralé funkce CMake

Před sadou SDK verze 24.03 se funkce CMake azsphere_configure_tools a azsphere_configure_api použily k určení verze cílových nástrojů sady SDK a cílového rozhraní API nastaveného v souboru CMakeLists.txt. Tyto funkce jsou teď zastaralé a cílová sada rozhraní API by se měla místo toho zadat v příslušném konfiguračním souboru. Podrobnosti najdete na stránce rozhraní API modulu runtime aplikace, adresářů sysroot a Beta.

Pokud používáte starší verzi sady SDK a zobrazí se chyba konfigurace CMake týkající se nepodporované revize nástrojů, můžete ji obejít opětovným přidáním těchto funkcí do CMakeLists.txt. Příklad:

azsphere_configure_tools(TOOLS_REVISION 23.05) azsphere_configure_api(TARGET_API_SET 16)

Odstranění mezipaměti CMake při změně konfiguračních souborů

Pokud změníte jeden z konfiguračních souborů, měli byste odstranit mezipaměť CMake, aby se zajistilo, že následné sestavení selžou. Před pokusem o další sestavení postupujte podle tohoto postupu:

• V případě sestavení editoru Visual Studio Code spusťte příkaz CMake:Delete Cache and Reconfigure z palety příkazů.
• V případě sestavení příkazového řádku (CLI) odstraňte adresář sestavení, který jste vytvořili v předchozím kroku.

Visual Studio rozpozná změny konfiguračního souboru CMake a automaticky odstraní mezipaměť.

Převedení existující aplikace na používání funkcí CMake

Pokud už máte aplikaci Azure Sphere vytvořenou pomocí CMake před sadou SDK 20.04, měli byste ji převést tak, aby používala tyto nové funkce. Tyto aplikace můžete zatím vytvářet beze změny, ale podpora pro ně je omezená a může být odebrána v budoucí verzi.

Příklad změn, které byste měli provést, se podívejte na to, jak se změnily konfigurační soubory CMakeLists.txt a *.json pro aplikaci externí aktualizace MCU na vysoké úrovni pro verzi 20.04.

Poznámka:

Kromě aktualizací používání funkcí byly tyto soubory aktualizovány v ukázkách Azure Sphere tak, aby používaly názvy malých písmen, a to v souladu s konvencemi CMake.

CMakeLists.txt změny konfigurace

Následující příklady ukazují změny potřebné k aktualizaci souboru CMakeLists.txt z verze 20.01 nebo starší, aby používaly nové funkce.

Příklad souboru CMakeLists.txt sady 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}")

Aktualizace souboru CMakeLists.txt

Aktualizovaný soubor CMakeLists.txt volá funkce azsphere_target_hardware_definition k nastavení cílového hardwaru. Volá také azsphere_target_add_image_package k sestavení balíčku image a volitelně specifikuje soubory, které se do něj mají zahrnout.

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

Poznámka:

Pro RESOURCE_FILES nejsou podporovány absolutní cesty.

Konfigurace CMakePresets.json sady Visual Studio

Soubor CMakePresets.json umožňuje určit běžné možnosti konfigurace, sestavení a testování a pak je sdílet s vývojáři pomocí jiných vývojových prostředí. Můžete například použít stejný přednastavený konfigurační soubor k vyvolání CMake v sadě Visual Studio, Visual Studio Code, kanálu kontinuální integrace nebo z rozhraní příkazového řádku ve Windows, Linuxu nebo macOS.

Od verze 22.07 používají aktuální projekty přednastavení definované v CMakePresets.json, zatímco stávající projekty můžou v CMakeSettings.json nadále používat nastavení. Ukázky se dodávají pouze s jedním konfiguračním souborem, a to buď CMakePresets.json, nebo CMakeSettings.json. Vývojové prostředí bude používat soubor, který je k dispozici. Informace o tom, který soubor se používá, najdete v jednotlivých ukázkových projektech. Projekty používající CMakeSettings.json najdete v tématu Změny konfigurace sady Visual Studio CMakeSettings.json.

Soubory CMakePresets.json pro aplikaci vysoké úrovně a pro aplikaci v reálném čase jsou velmi podobné; jediné rozdíly jsou v proměnnýchCMAKE_TOOLCHAIN_FILE.ARM_GNU_PATH

V aplikaci ARM_GNU_PATH vysoké úrovně není nastavena a CMAKE_TOOLCHAIN_FILE je nastavena takto:

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

V aplikaci CMAKE_TOOLCHAIN_FILE v reálném čase a ARM_GNU_PATH jsou nastaveny takto:

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

Konfigurace CMakeSettings.json sady Visual Studio

Ukázky se dodávají s konfiguračním souborem CMakePresets.json nebo CMakeSettings.json. Informace o tom, který soubor se používá, najdete v jednotlivých projektech. Tato část popisuje konfiguraci CMakeSettings.json. Projekty používající CMakePresets.json najdete v sadě Visual Studio CMakePresets.json změny konfigurace.

Následující příklady ukazují změny potřebné k aktualizaci souboru CMakeSettings.json v sadě Visual Studio z verze 20.01 nebo starší, aby používaly nové funkce.

Příklad souboru CMakeSettings.json sady 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}"
        }
      ]
    }
  ]
}

Aktualizovaný soubor CMakeSettings.json sady SDK

Aktualizovaný soubor CMakeSettings.json obsahuje následující změny:

• V poli Prostředí se vyžaduje jenom Azure Sphere.
• V poli "konfigurace" pro sestavení Debug i Release:
  • Hodnoty buildRoot a installRoot už nevyžadují nastavení AzureSphereTargetApiSet.
  • Sada nástrojů CMake je teď definována v cmakeToolChain místo v proměnných.
  • Pole "variables" teď určuje pouze cílovou sadu rozhraní API a pomocí nové hodnoty "latest-lts" označuje, že projekt by měl sestavit s nejnovějším dlouhodobým sysroot (LTS). Nastavení AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY a AZURE_SPHERE_TARGET_HARDWARE_DEFINITION už nejsou potřeba, protože tyto hodnoty jsou teď nastavené v souboru 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"
        }
      ]
    }
  ]
}

Konfigurace editoru Visual Studio Code .vscode/settings.json

Následující příklady ukazují změny potřebné k aktualizaci souboru .vscode/settings.json pro Visual Studio Code z verze 20.01 nebo starší, aby používaly nové funkce.

Příklad souboru 20.01 SDK .vscode/settings.json

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

Aktualizace souboru .vscode/settings.json

Soubor .vscode/settings.json obsahuje nastavení pracovního prostoru pro Visual Studio Code.

Aktualizovaný soubor settings.json obsahuje následující změny pole cmake.configureSettings:

• Nastavení AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY se už nevyžadují, protože tyto hodnoty jsou teď nastavené v souboru CMakeLists.txt.AZURE_SPHERE_TARGET_HARDWARE_DEFINITION
• Nastavení CMAKE_TOOLCHAIN_FILE se už nevyžadují, protože tyto hodnoty jsou teď nastavené v souboru CMakePresets.json.AZURE_SPHERE_TARGET_API_SET Hodnota AZURE_SPHERE_TARGET_API_SET je nyní "latest-lts", což znamená, že projekt by měl sestavit s nejnovější dlouhodobé stabilní sysroot (LTS).

Všimněte si, že "cmake.configureArgs" pole se také odstranilo z důvodů nesouvisejících s CMake. (Pole už není povinné, protože --no-warn-unused-cli parametr není pro tento build potřeba.)

Pro rozšíření platí následující pole:

• "cmake.configureOnOpen": trueoznámí rozšíření cmake-tools, aby se spustila konfigurace při otevření pracovního prostoru.

• "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools"určuje zprostředkovatele IntelliSense, který se má použít pro rozšíření cpp-tools. V tomto případě rozšíření 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"
}

Vytvoření souboru CMakeWorkspaceSettings.json

Pokud používáte Visual Studio 2022 verze 17.1 nebo novější a máte projekt s více kořeny, jako je ukázka IntercoreComms, budete muset do složky projektu nejvyšší úrovně přidat soubor CMakeWorkspaceSettings.json. Soubor má dvě položky, jednu pro určení, že sestavení CMake je povolené a jeden obsahující cesty k více kořenovým složkám. Například pro ukázku IntercoreComms má CMakeWorkspaceSettings.json následující obsah:

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

Cesty se zadají vzhledem ke složce obsahující CMakeWorkspaceSettings.json souboru.