Buildek konfigurálása a CMake használatával

Cikk
03/27/2024

Az Azure Sphere a CMake használatával konfigurálja az alkalmazások buildjeinek konfigurálását a Visual Studio, a Visual Studio Code, valamint a Windows és Linux parancssorokkal. A CMake egy nyílt forráskódú, platformfüggetlen make rendszer. A CMake-ről a CMake wikiben talál általános információkat.

Az alábbi források a CMake Visual Studióval vagy Visual Studio Code-dal való használatával kapcsolatos információkat nyújtanak:

A CMake-buildek a következő fájlokat használják:

Fájl	Célja
CMakeLists.txt	Általános CMake konfigurációs fájl. Minden buildhez szükséges.
CMakePresets.json	Konfigurációs beállítások fájlja a Visual Studióhoz és a Visual Studio Code-hoz. Ez a fájl vagy CMakeSettings.json szükséges a Visual Studióval való buildeléshez.
CMakeSettings.json	Visual Studio konfigurációs fájl. Ez a fájl vagy CMakePresets.json szükséges a Visual Studióval való buildeléshez.
CMakeWorkspaceSettings.json	Visual Studio-konfigurációs fájl több gyökerű projektekhez, az IntercoreComms-mintához hasonlóan.
.vscode/settings.json	Visual Studio Code konfigurációs fájl. A Visual Studio Code-dal való buildeléshez szükséges.

A CMake-paraméterek szóközökkel vannak elválasztva. A Windows-parancssor "^" sorfolytatási karaktere, Linux parancssor esetén " \ " vagy PowerShell esetén "" használható az olvashatóság érdekében, de nem kötelező. Az adott karaktert a Windows vagy Linux terminálkonfigurációja határozza meg.

CMake-függvények az Azure Sphere-hez

A CMakeLists.txt fájl tartalmazza azokat az általános konfigurációs beállításokat, amelyeket a CMake egy alkalmazás létrehozásához használ. Az Azure Sphere a következő függvények használatát támogatja a CMakeLists.txt:

Név	Célja
azsphere_target_hardware_definition	Adja meg a célhardvereket.
azsphere_target_add_image_package	Hozzon létre egy képcsomagot.

Ha már rendelkezik olyan alkalmazással, amelyet 20.04-nél korábbi SDK-val hoztak létre, tekintse meg a Meglévő alkalmazás konvertálása a CMake-függvények használatára című témakört.

A CMakeLists.txt fájlnak a project parancsot kell meghívnia a azsphere_ függvények bármelyike előtt.

Célhardver-definíció

A megcélzott hardvert úgy adhatja meg, hogy meghívja a azsphere_target_hardware_definition függvényt az érték CMakeLists.txt való tárolásához. Ez a függvény két paramétert vesz igénybe: a keresendő könyvtárak listáját és a keresendő fájlnevet. Például:

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

A TARGET_DEFINITION paraméter megadása kötelező. Megadja az alkalmazás által igényelt hardverdefiníciós fájl nevét. A TARGET_DIRECTORY paraméter felsorolja azokat a könyvtárakat, amelyekben a fájlt keresni szeretné. Ez a paraméter nem kötelező; Ha kihagyja, a CMake csak az SDK-telepítés HardwareDefinitions mappájában jelenik meg. Több mappa megadásához minden mappanevet dupla idézőjelek közé kell tenni, és szóközzel elválaszthatja a mappaneveket, ahogy az a példában is látható. A példában <az elérési út> a fejlesztői gép my_app mappájának elérési útját jelöli.

Képcsomag létrehozása

Adja meg a képcsomagfájlt és az összeállítás során belefoglalandó erőforrásfájlokat a azsphere_target_add_image_package függvény meghívásával az érték CMakeLists.txt való tárolásához. A azsphere_target_add_image_package függvényre és a létrehozandó projektre van szükség; az erőforrásfájlok megadása nem kötelező.

A következő függvényhívás létrehoz egy képcsomagot, amely csak az Azure Sphere-alkalmazást tartalmazza:

azsphere_target_add_image_package(${PROJECT_NAME})

A következő példa egy rendszerképcsomagot hoz létre, amely egy alkalmazás mellett tanúsítványt is tartalmaz:

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

A azsphere_target_add_image_package átadott CMake-célnak ${PROJECT_NAME} névvel kell rendelkeznie, és a azsphere_target_add_image_package függvény csak egyszer hívható meg a CMakeLists.txt fájlból.

Elavult CMake-függvények

Az SDK 24.03-es verziója előtt a CMake-függvények azsphere_configure_tools és azsphere_configure_api adták meg a cél SDK-eszközök verzióját és a cél API-t a CMakeLists.txt fájlban. Ezek a függvények elavultak, és a cél API-készletet a megfelelő konfigurációs fájlban kell megadni. A részletekért tekintse meg az Alkalmazás futtatókörnyezetének verzióját, a sysroots és a Béta API-kat ismertető oldalt.

Ha az SDK egy régebbi verzióját használja, és egy nem támogatott eszközök változatával kapcsolatos CMake konfigurációs hibát lát, megkerülheti, ha ezeket a függvényeket újra hozzáadja a CMakeLists.txt. Példaként:

azsphere_configure_tools(TOOLS_REVISION 23.05) azsphere_configure_api(TARGET_API_SET 16)

A CMake-gyorsítótár törlése konfigurációs fájlok módosításakor

Ha módosítja az egyik konfigurációs fájlt, törölje a CMake-gyorsítótárat, hogy a későbbi buildek ne hiúsuljanak meg. Egy másik build megkísérlése előtt kövesse az alábbi eljárást:

Visual Studio Code-buildek esetén futtassa a CMake:Gyorsítótár törlése és újrakonfigurálás parancsot a parancskatalógusból.
Parancssori (CLI-) buildek esetén törölje a korábbi lépésben létrehozott buildkönyvtárat.

A Visual Studio észleli a CMake konfigurációs fájljának módosításait, és automatikusan törli a gyorsítótárat.

Meglévő alkalmazás konvertálása a CMake-függvények használatára

Ha már rendelkezik olyan Azure Sphere-alkalmazással, amely a 20.04 SDK előtti CMake-vel lett létrehozva, konvertálja úgy, hogy ezeket az új függvényeket használja. Az ilyen alkalmazásokat egyelőre változatlanul is létrehozhatja, de ezek támogatása korlátozott, és egy későbbi kiadásban megszűnhet.

A szükséges módosításokra példaként tekintse meg, hogyan módosultak a 20.04-es kiadáshoz tartozó külső MCU-frissítés magas szintű alkalmazásának CMakeLists.txt és *.json konfigurációs fájljai.

Megjegyzés

A függvények használatának frissítései mellett ezek a fájlok is frissültek az Azure Sphere-mintákban, hogy kisbetűs függvényneveket használjanak, így igazodva a CMake konvenciókhoz.

konfigurációmódosítások CMakeLists.txt

Az alábbi példák a CMakeLists.txt fájl 20.01-ről vagy korábbi verziójáról az új függvények használatához szükséges módosításokat mutatják be.

20.01-CMakeLists.txt. példa SDK-fájl

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

Frissített CMakeLists.txt fájl

A frissített CMakeLists.txt fájl meghívja a azsphere_target_hardware_definition függvényeket a célhardver beállításához. A azsphere_target_add_image_package is meghívja a rendszerképcsomag összeállításához, és opcionálisan megadja a belefoglalandó fájlokat.

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

Megjegyzés

Az abszolút elérési utak nem támogatottak a RESOURCE_FILES.

A Visual Studio CMakePresets.json konfigurálása

A CMakePresets.json fájl lehetővé teszi a gyakori konfigurálási, létrehozási és tesztelési beállítások megadását, majd más fejlesztői környezetek használatával történő megosztását a fejlesztőkkel. Ugyanezt az előre beállított konfigurációs fájlt használhatja például a CMake meghívásához a Visual Studióban, a Visual Studio Code-ban, egy folyamatos integrációs folyamatban, vagy a parancssori felületről Windows, Linux vagy macOS rendszeren.

A 22.07-es kiadástól kezdve a jelenlegi projektek CMakePresets.json definiált előzetes beállításokat használnak, míg a meglévő projektek továbbra is használhatják CMakeSettings.json beállításait. A minták csak egy konfigurációs fájllal vannak szállítva, CMakePresets.json vagy CMakeSettings.json. A fejlesztői környezet a jelen lévő fájlt fogja használni. A használt fájl megtekintéséhez tekintse meg az egyes mintaprojekteket. A CMakeSettings.json használó projektekről lásd: A Visual Studio CMakeSettings.json konfigurációs módosításai.

A magas szintű alkalmazások és a valós idejű alkalmazások CMakePresets.json fájljai nagyon hasonlóak; az egyetlen különbség a és ARM_GNU_PATH a CMAKE_TOOLCHAIN_FILE változóban van.

Magas szintű alkalmazásokban ARM_GNU_PATH a nincs beállítva, és CMAKE_TOOLCHAIN_FILE a következőképpen van beállítva:

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

Egy valós idejű alkalmazásban a CMAKE_TOOLCHAIN_FILE és ARM_GNU_PATH a a következőképpen vannak beállítva:

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

A Visual Studio CMakeSettings.json konfigurálása

A mintákat egy CMakePresets.json vagy CMakeSettings.json konfigurációs fájl tartalmazza. A használt fájl megtekintéséhez tekintse meg az egyes projekteket. Ez a szakasz a CMakeSettings.json konfigurációját ismerteti. A CMakePresets.json használó projektekről lásd: A Visual Studio CMakePresets.json konfigurációs módosításai.

Az alábbi példák azt mutatják be, hogy az új függvények használatához a Visual Studióban 20.01-ről vagy korábbiról kell frissíteni a CMakeSettings.json fájlt.

20.01-CMakeSettings.json. példa SDK-fájl

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

Frissített SDK-CMakeSettings.json fájl

A frissített CMakeSettings.json fájl a következő módosításokat tartalmazza:

A "környezetek" mezőben csak az "Azure Sphere" szükséges.
A "konfigurációk" mezőben a hibakeresési és a kiadási buildek esetében is:
- A "buildRoot" és az "installRoot" értékhez már nincs szükség az AzureSphereTargetApiSet beállításra.
- A CMake eszközlánc mostantól "cmakeToolChain" nyelven van definiálva a "változók" helyett.
- A "változók" mező most már csak a cél API-készletet adja meg, és az új "latest-lts" értéket használja annak jelzésére, hogy a projektnek a legújabb hosszú távú stabil (LTS) sysroottal kell épülnie. A AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY és a AZURE_SPHERE_TARGET_HARDWARE_DEFINITION beállításaira már nincs szükség, mert ezek az értékek már be vannak állítva a CMakeLists.txt fájlban.

{
  "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 konfigurációja

Az alábbi példák a Visual Studio Code .vscode/settings.json fájljának 20.01-ről vagy korábbi verziójáról az új függvények használatához szükséges módosításokat mutatják be.

20.01-s példa : SDK .vscode/settings.json fájl

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

Frissített .vscode/settings.json fájl

A .vscode/settings.json fájl a Visual Studio Code munkaterület-beállításait tartalmazza.

A frissített settings.json fájl a "cmake.configureSettings" mező alábbi módosításait tartalmazza:

A AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY és AZURE_SPHERE_TARGET_HARDWARE_DEFINITION a beállításra már nincs szükség, mert ezek az értékek már be vannak állítva a CMakeLists.txt fájlban.
A CMAKE_TOOLCHAIN_FILE és AZURE_SPHERE_TARGET_API_SET a beállítás már nem szükséges, mert ezek az értékek már be vannak állítva a CMakePresets.json fájlban. Az AZURE_SPHERE_TARGET_API_SET érték most , "latest-lts"ami azt jelzi, hogy a projektnek a legutóbbi hosszú távú stabil (LTS) sysroottal kell felépítenie.

Vegye figyelembe, hogy a "cmake.configureArgs" mező a CMake-hez nem kapcsolódó okok miatt is törölve lett. (A mezőre már nincs szükség, mert ehhez a --no-warn-unused-cli buildhez nincs szükség a paraméterre.)

A bővítményekre a következő mezők vonatkoznak:

"cmake.configureOnOpen": true értesíti a cmake-tools bővítményt, hogy a munkaterület megnyitásakor megkezdje a konfigurálást.
"C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools" a cpp-tools bővítményhez használandó IntelliSense-szolgáltatót határozza meg; ebben az esetben a cmake-tools bővítmény.

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

CMakeWorkspaceSettings.json-fájl létrehozása

Ha a Visual Studio 2022 17.1-es vagy újabb verzióját használja, és van egy több gyökerű projektje, például az IntercoreComms minta, hozzá kell adnia egy CMakeWorkspaceSettings.json fájlt a projekt legfelső szintű mappájába. A fájl két bejegyzéssel rendelkezik, az egyikben a CMake build engedélyezve van, a másik pedig a több gyökér elérési útját tartalmazza. Az IntercoreComms minta esetében például a CMakeWorkspaceSettings.json a következő tartalommal rendelkezik:

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

Az elérési utak a CMakeWorkspaceSettings.json fájlt tartalmazó mappához viszonyítva vannak megadva.

Megosztás a következőn keresztül: