Buildek konfigurálása a CMake használatával
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
ésAZURE_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
ésAZURE_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. AzAZURE_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.