Konfigurace sestavení pomocí CMake

Azure Sphere používá CMake ke konfiguraci sestavení pro aplikace pomocí sady Visual Studio, Editoru Visual Studio Code a příkazového řádku pro Windows a Linux. CMake je opensourcový multiplatformní systém značky. Obecné informace o CMake najdete na wikiwebu CMake.

Následující zdroje poskytují informace o použití 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 Povinné pro všechna sestavení.
CMakePresets.json	Soubor přednastavení konfigurace pro Visual Studio a Visual Studio Code Tento soubor nebo CMakeSettings.json se vyžadují pro sestavení pomocí sady Visual Studio.
CMakeSettings.json	Konfigurační soubor sady Visual Studio. Tento soubor nebo CMakePresets.json se vyžadují pro sestavení pomocí sady Visual Studio.
CMakeWorkspaceSettings.json	Konfigurační soubor sady Visual Studio pro projekty s více kořeny, jak je uvedeno v ukázce IntercoreComms.
.vscode/settings.json	Konfigurační soubor editoru Visual Studio Code Vyžaduje se pro vytváření 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 se dá použít pro čitelnost, ale není nutný. 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:

Jméno	Úč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žití funkcí CMake.

Soubor CMakeLists.txt musí před libovolnou funkcí azsphere_ volat příkaz projektu.

Definice cílového hardwaru

Hardware, na který cílíte, můžete určit voláním funkce azsphere_target_hardware_definition , která uloží hodnotu do CMakeLists.txt. Tato funkce přebírá dva parametry: seznam adresářů k hledání 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 seznam adresářů, ve kterých se má tento soubor hledat. Tento parametr je volitelný. Pokud ho vynecháte, CMake se v instalaci sady SDK zobrazí jenom ve složce HardwareDefinitions. Pokud chcete zadat více složek, uzavřete názvy jednotlivých složek 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 na 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é se mají zahrnout při sestavování voláním funkce azsphere_target_add_image_package pro uložení hodnoty v CMakeLists.txt. Vyžaduje se funkce azsphere_target_add_image_package a projekt, který se má sestavit. 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ý kromě aplikace obsahuje certifikát:

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 z CMakeLists.txt souboru volat jenom jednou.

Zastaralé funkce CMake

Před sadou SDK verze 24.03 se funkce CMake azsphere_configure_tools a azsphere_configure_api používaly k určení verze 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 zadat v příslušném konfiguračním souboru. Podrobnosti najdete na stránce Verze modulu runtime aplikací, sysroots a beta rozhraní API .

Pokud používáte starší verzi sady SDK a zobrazí se chyba konfigurace CMake týkající se revize nepodporovaných nástrojů, můžete to obejít tak, že tyto funkce znovu přidáte 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, abyste zajistili, že další sestavení neselžou. Před pokusem o další sestavení postupujte následovně:

• 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 zjistí změny v konfiguračním souboru CMake a automaticky odstraní mezipaměť.

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

Pokud už máte aplikaci Azure Sphere, která byla vytvořená pomocí CMake před sadou SDK 20.04, měli byste ji převést na použití těchto nových funkcí. Tyto aplikace můžete zatím vytvářet beze změny, ale jejich podpora je omezená a v budoucí verzi může být odebrána.

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

Poznámka

Kromě aktualizací pro používání funkcí byly tyto soubory v ukázkách Azure Sphere aktualizovány tak, aby používaly názvy funkcí malými písmeny, což je 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 se nové funkce používaly.

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

Aktualizovaný soubor 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ě k určení souborů, 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

Absolutní cesty nejsou pro RESOURCE_FILES podporované.

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í. Stejný konfigurační soubor předvoleb můžete například použít 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ředvolby definované v CMakePresets.json, zatímco stávající projekty můžou dál používat nastavení v CMakeSettings.json. 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. Pokud chcete zjistit, který soubor se používá, podívejte se na jednotlivé ukázkové projekty. Informace o projektech používajících 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ých CMAKE_TOOLCHAIN_FILE a 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 nastavené 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. Pokud chcete zjistit, který soubor se používá, podívejte se na jednotlivé projekty. Tato část popisuje konfiguraci CMakeSettings.json. Informace o projektech používajících CMakePresets.json najdete v tématu Změny konfigurace sady Visual Studio CMakePresets.json.

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 se nové funkce používaly.

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 pouze Azure Sphere.
• V poli Konfigurace pro buildy Debug i Release:
  • Hodnoty buildRoot a installRoot už nevyžadují nastavení AzureSphereTargetApiSet.
  • Sada nástrojů CMake je teď definovaná v cmakeToolChain místo v proměnné.
  • Pole variables teď určuje jenom cílovou sadu rozhraní API a používá novou hodnotu latest-lts k označení, že projekt by měl být sestavovaný s nejnovějším dlouhodobě stabilním adresářem sysroot (LTS). Nastavení AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY a AZURE_SPHERE_TARGET_HARDWARE_DEFINITION se už nevyžadují, protože tyto hodnoty jsou nyní nastaveny v souboruCMakeLists.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 .vscode/settings.json editoru Visual Studio Code

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

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

{
    "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 a AZURE_SPHERE_TARGET_HARDWARE_DEFINITION se už nevyžadují, protože tyto hodnoty jsou teď nastavené v souboruCMakeLists.txt .
• Nastavení CMAKE_TOOLCHAIN_FILE a AZURE_SPHERE_TARGET_API_SET se už nevyžadují, protože tyto hodnoty jsou nyní nastaveny v souboru CMakePresets.json . Hodnota AZURE_SPHERE_TARGET_API_SET je teď "latest-lts", což označuje, že projekt by se měl sestavit s nejnovějším dlouhodobě stabilním adresářem sysroot (LTS).

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

Následující pole platí pro rozšíření:

• "cmake.configureOnOpen": true upozorní rozšíření cmake-tools , aby při otevření pracovního prostoru zahájil konfiguraci.

• "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 například ukázka IntercoreComms, budete muset do složky projektu nejvyšší úrovně přidat soubor CMakeWorkspaceSettings.json. Soubor obsahuje dvě položky, jednu, která určuje, že je povolené sestavení CMake, a druhá obsahuje 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 jsou zadané vzhledem ke složce, která obsahuje soubor CMakeWorkspaceSettings.json.