Konfigurowanie kompilacji przy użyciu narzędzia CMake
Ważne
Jest to dokumentacja usługi Azure Sphere (starsza wersja). Usługa Azure Sphere (starsza wersja) zostanie wycofana 27 września 2027 r., a użytkownicy muszą przeprowadzić migrację do usługi Azure Sphere (zintegrowanej) do tej pory. Użyj selektora wersji znajdującego się powyżej spisu treści, aby wyświetlić dokumentację usługi Azure Sphere (zintegrowaną).
Usługa Azure Sphere używa narzędzia CMake do konfigurowania kompilacji dla aplikacji za pomocą programów Visual Studio, Visual Studio Code oraz wierszy poleceń systemów Windows i Linux. CMake to wieloplatformowy system typu open source. Aby uzyskać ogólne informacje na temat narzędzia CMake, zobacz witrynę CMake Wiki.
Następujące źródła zawierają informacje o korzystaniu z narzędzia CMake w programie Visual Studio lub Visual Studio Code:
Kompilacje narzędzia CMake używają następujących plików:
Parametry narzędzia CMake są oddzielone spacjami. Znak kontynuacji wiersza "^" dla wiersza polecenia systemu Windows, " \ " dla wiersza polecenia systemu Linux lub "'" dla programu PowerShell może służyć do czytelności, ale nie jest wymagany. Określony znak jest określany przez konfigurację terminalu systemu Windows lub Linux.
Funkcje narzędzia CMake dla usługi Azure Sphere
Plik CMakeLists.txt zawiera ogólne ustawienia konfiguracji używane przez narzędzie CMake do kompilowania aplikacji. Usługa Azure Sphere obsługuje korzystanie z następujących funkcji w CMakeLists.txt:
| Nazwisko | Purpose |
|---|---|
| azsphere_target_hardware_definition | Określ sprzęt docelowy. |
| azsphere_target_add_image_package | Utwórz pakiet obrazów. |
Jeśli masz istniejącą aplikację, która została utworzona przy użyciu zestawu SDK wcześniej niż 20.04, zobacz Konwertowanie istniejącej aplikacji w celu korzystania z funkcji CMake.
Plik CMakeLists.txt musi wywołać polecenie projektu przed dowolną funkcją azsphere_ .
Docelowa definicja sprzętu
Możesz określić docelowy sprzęt , wywołując funkcję azsphere_target_hardware_definition w celu przechowywania wartości w CMakeLists.txt. Ta funkcja przyjmuje dwa parametry: listę katalogów do wyszukania i nazwę pliku do wyszukania. Na przykład:
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 jest wymagany. Określa nazwę pliku definicji sprzętu wymaganej przez aplikację. Parametr TARGET_DIRECTORY zawiera listę katalogów, w których należy wyszukać ten plik. Ten parametr jest opcjonalny; Jeśli go pominięto, narzędzie CMake wygląda tylko w folderze HardwareDefinitions w instalacji zestawu SDK. Aby określić wiele folderów, należy ująć każdą nazwę folderu w podwójny cudzysłów i użyć miejsca do oddzielenia nazw folderów, jak w przykładzie. W przykładzie <ścieżka> reprezentuje ścieżkę do folderu my_app na maszynie dewelopera.
Tworzenie pakietu obrazów
Określ plik pakietu obrazu i wszystkie pliki zasobów, które mają być uwzględniane podczas kompilowania, wywołując funkcję azsphere_target_add_image_package do przechowywania wartości w CMakeLists.txt. Wymagana jest funkcja azsphere_target_add_image_package i projekt do skompilowania. Pliki zasobów są opcjonalne.
Następujące wywołanie funkcji tworzy pakiet obrazu zawierający tylko aplikację usługi Azure Sphere:
azsphere_target_add_image_package(${PROJECT_NAME})
W następnym przykładzie tworzony jest pakiet obrazu zawierający certyfikat oprócz aplikacji:
azsphere_target_add_image_package(${PROJECT_NAME} RESOURCE_FILES "certs/bundle.pem")
Element docelowy narzędzia CMake przekazany do azsphere_target_add_image_package musi mieć nazwę ${PROJECT_NAME}, a funkcja azsphere_target_add_image_package może być wywoływana tylko raz z pliku CMakeLists.txt.
Przestarzałe funkcje narzędzia CMake
Przed zestawem SDK w wersji 24.03 funkcje narzędzia CMake azsphere_configure_tools i azsphere_configure_api zostały użyte do określenia docelowej wersji narzędzi zestawu SDK i docelowego interfejsu API ustawionego w pliku CMakeLists.txt. Te funkcje są teraz przestarzałe, a docelowy zestaw interfejsu API powinien zostać określony w odpowiednim pliku konfiguracji. Aby uzyskać szczegółowe informacje, zobacz stronę Środowisko uruchomieniowe aplikacji, Sysroots i Beta API.
Jeśli używasz starszej wersji zestawu SDK i widzisz błąd konfiguracji narzędzia CMake dotyczący nieobsługiwanej poprawki narzędzi, możesz go obejść, dodając ponownie te funkcje do CMakeLists.txt. Przykład:
azsphere_configure_tools(TOOLS_REVISION 23.05)
azsphere_configure_api(TARGET_API_SET 16)
Jak usunąć pamięć podręczną CMake podczas zmieniania plików konfiguracji
Jeśli zmienisz jeden z plików konfiguracji, usuń pamięć podręczną CMake, aby upewnić się, że kolejne kompilacje nie kończą się niepowodzeniem. Przed podjęciem próby wykonania innej kompilacji wykonaj następującą procedurę:
- W przypadku kompilacji programu Visual Studio Code uruchom polecenie CMake:Delete Cache and Reconfigure z palety poleceń.
- W przypadku kompilacji wiersza polecenia usuń katalog kompilacji utworzony we wcześniejszym kroku.
Program Visual Studio wykrywa zmiany w pliku konfiguracji narzędzia CMake i automatycznie usuwa pamięć podręczną.
Konwertowanie istniejącej aplikacji w celu korzystania z funkcji CMake
Jeśli masz już aplikację usługi Azure Sphere utworzoną za pomocą narzędzia CMake przed zestawem SDK 20.04, należy przekonwertować ją, aby używać tych nowych funkcji. Na razie można tworzyć takie aplikacje bez zmian, ale ich obsługa jest ograniczona i może zostać usunięta w przyszłej wersji.
Na przykładowe zmiany, które należy wprowadzić, sprawdź, jak zostały zmienione pliki konfiguracji CMakeLists.txt i *.json dla aplikacji wysokiego poziomu zewnętrznej aktualizacji MCU dla wersji 20.04.
Uwaga
Oprócz aktualizacji do korzystania z funkcji te pliki zostały zaktualizowane w przykładach usługi Azure Sphere w celu używania małych liter nazw funkcji, w związku z czym są zgodne z konwencjami narzędzia CMake.
CMakeLists.txt zmiany konfiguracji
W poniższych przykładach pokazano zmiany wymagane do zaktualizowania pliku CMakeLists.txt z wersji 20.01 lub starszej do korzystania z nowych funkcji.
Przykładowy plik CMakeLists.txt zestawu 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}")
Zaktualizowany plik CMakeLists.txt
Zaktualizowany plik CMakeLists.txt wywołuje funkcje azsphere_target_hardware_definition w celu ustawienia sprzętu docelowego. Wywołuje również azsphere_target_add_image_package , aby skompilować pakiet obrazu i opcjonalnie określić pliki do uwzględnienia w nim.
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")
Uwaga
Ścieżki bezwzględne nie są obsługiwane w przypadku RESOURCE_FILES.
Konfiguracja CMakePresets.json programu Visual Studio
Plik CMakePresets.json umożliwia określenie typowych opcji konfigurowania, kompilowania i testowania, a następnie udostępniania ich deweloperom przy użyciu innych środowisk programistycznych. Na przykład można użyć tego samego pliku konfiguracji ustawień wstępnych, aby wywołać narzędzie CMake w programie Visual Studio, programie Visual Studio Code, potoku ciągłej integracji lub za pomocą interfejsu wiersza polecenia w systemie Windows, Linux lub macOS.
Od wersji 22.07 bieżące projekty używają ustawień wstępnych zdefiniowanych w CMakePresets.json, podczas gdy istniejące projekty mogą nadal używać ustawień w CMakeSettings.json. Przykłady są dostarczane tylko z jednym plikiem konfiguracji, CMakePresets.json lub CMakeSettings.json. Środowisko programistyczne będzie używać pliku, który jest obecny. Zapoznaj się z każdym przykładowym projektem, aby zobaczyć, który plik jest używany. W przypadku projektów korzystających z CMakeSettings.json zobacz Zmiany konfiguracji programu Visual Studio CMakeSettings.json.
Pliki CMakePresets.json dla aplikacji wysokiego poziomu i aplikacji w czasie rzeczywistym są bardzo podobne; jedyną różnicą są zmienne CMAKE_TOOLCHAIN_FILE i ARM_GNU_PATH .
W aplikacji ARM_GNU_PATH wysokiego poziomu nie jest ustawiona i CMAKE_TOOLCHAIN_FILE jest ustawiona w następujący sposób:
"CMAKE_TOOLCHAIN_FILE": "$env{AzureSphereDefaultSDKDir}/CMakeFiles/AzureSphereToolchain.cmake",
W aplikacji CMAKE_TOOLCHAIN_FILE w czasie rzeczywistym i ARM_GNU_PATH są ustawione w następujący sposób:
"CMAKE_TOOLCHAIN_FILE": "$env{AzureSphereDefaultSDKDir}/CMakeFiles/AzureSphereRTCoreToolchain.cmake",
"ARM_GNU_PATH": "$env{ArmGnuPath}"
Konfiguracja CMakeSettings.json programu Visual Studio
Przykłady są dostarczane z plikiem konfiguracji CMakePresets.json lub CMakeSettings.json. Zapoznaj się z poszczególnymi projektami, aby zobaczyć, który plik jest używany. W tej sekcji opisano konfigurację CMakeSettings.json. W przypadku projektów korzystających z CMakePresets.json zobacz Visual Studio CMakePresets.json zmiany konfiguracji.
W poniższych przykładach pokazano zmiany wymagane do zaktualizowania pliku CMakeSettings.json w programie Visual Studio z wersji 20.01 lub starszej do korzystania z nowych funkcji.
Przykładowy plik zestawu SDK 20.01 CMakeSettings.json
{
"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}"
}
]
}
]
}
Zaktualizowany plik CMakeSettings.json zestawu SDK
Zaktualizowany plik CMakeSettings.json zawiera następujące zmiany:
- W polu "środowiska" wymagane jest tylko "Azure Sphere".
- W polu "konfiguracje" kompilacji debugowania i wydania:
- Wartości "buildRoot" i "installRoot" nie wymagają już ustawienia AzureSphereTargetApiSet.
- Łańcuch narzędzi CMake jest teraz zdefiniowany w parametrze "cmakeToolChain", a nie w zmiennej.
- Pole "variables" teraz określa tylko docelowy zestaw interfejsu API i używa nowej wartości "latest-lts", aby wskazać, że projekt powinien zostać skompilowywany z najnowszym długoterminowym elementem sysroot (LTS). Ustawienia AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY i AZURE_SPHERE_TARGET_HARDWARE_DEFINITION nie są już wymagane, ponieważ te wartości są teraz ustawiane w pliku 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"
}
]
}
]
}
Konfiguracja .vscode/settings.json programu Visual Studio Code
W poniższych przykładach pokazano zmiany wymagane do zaktualizowania pliku .vscode/settings.json dla programu Visual Studio Code z wersji 20.01 lub starszej do korzystania z nowych funkcji.
Przykładowy plik .vscode/settings.json zestawu 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"
}
Zaktualizowano plik .vscode/settings.json
Plik .vscode/settings.json zawiera ustawienia obszaru roboczego programu Visual Studio Code.
Zaktualizowany plik settings.json zawiera następujące zmiany w polu "cmake.configureSettings":
- Ustawienia
AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORYiAZURE_SPHERE_TARGET_HARDWARE_DEFINITIONnie są już wymagane, ponieważ te wartości są teraz ustawiane w pliku CMakeLists.txt . - Ustawienia
CMAKE_TOOLCHAIN_FILEiAZURE_SPHERE_TARGET_API_SETnie są już wymagane, ponieważ te wartości są teraz ustawiane w pliku CMakePresets.json . WartośćAZURE_SPHERE_TARGET_API_SETto teraz"latest-lts", która wskazuje, że projekt powinien zostać skompilowy z najnowszym długoterminowym elementem sysroot (LTS).
Należy pamiętać, że "cmake.configureArgs" pole zostało również usunięte z powodów niepowiązanych z CMake. (Pole nie jest już wymagane, ponieważ --no-warn-unused-cli parametr nie jest wymagany dla tej kompilacji).
Do rozszerzeń mają zastosowanie następujące pola:
"cmake.configureOnOpen": truepowiadamia rozszerzenie cmake-tools, aby rozpocząć konfigurowanie po otwarciu obszaru roboczego."C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools"określa dostawcę funkcji IntelliSense do użycia dla rozszerzenia cpp-tools . W tym przypadku rozszerzenie 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"
}
Tworzenie pliku CMakeWorkspaceSettings.json
Jeśli używasz programu Visual Studio 2022 w wersji 17.1 lub nowszej i masz projekt z wieloma katalogami głównymi, takimi jak przykład IntercoreComms, musisz dodać plik CMakeWorkspaceSettings.json do folderu najwyższego poziomu projektu. Plik zawiera dwa wpisy, jeden, aby określić, że kompilacja CMake jest włączona i jedna zawierająca ścieżki do wielu katalogów głównych. Na przykład w przykładzie IntercoreComms CMakeWorkspaceSettings.json ma następującą zawartość:
{
"enableCMake": true,
"sourceDirectory": [ "IntercoreComms_HighLevelApp", "IntercoreComms_RTApp_MT3620_BareMetal" ]
}
Ścieżki są określane względem folderu zawierającego plik CMakeWorkspaceSettings.json.