Konfigurowanie kompilacji przy użyciu usługi CMake

Artykuł
04/03/2024

Usługa Azure Sphere konfiguruje kompilacje dla aplikacji za pomocą programów Visual Studio, Visual Studio Code oraz wierszy poleceń systemu Windows i Linux za pomocą usługi CMake. CMake jest open-source, międzyplatformowy system make. Aby uzyskać ogólne informacje na temat CMake, zobacz CMake Wiki.

Poniższe źródła zawierają informacje na temat używania usługi CMake w programie Visual Studio lub Visual Studio Code:

Kompilacje CMake używają następujących plików:

Plik	Celu
CMakeLists.txt	Ogólny plik konfiguracji CMake. Wymagane dla wszystkich kompilacji.
CMakePresets.json	Plik konfiguracji wstępnie ustawiony dla programów Visual Studio i Visual Studio Code. Ten plik lub CMakeSettings.json jest wymagany do tworzenia za pomocą programu Visual Studio.
CMakeSettings.json	Plik konfiguracji programu Visual Studio. Ten plik lub CMakePresets.json jest wymagany do tworzenia za pomocą programu Visual Studio.
CMakeWorkspaceSettings.json	Plik konfiguracji programu Visual Studio dla projektów o wielu korzeniach, jak w przykładzie IntercoreComms.
vscode/settings.json	Visual Studio Code plik konfiguracji. Wymagane do budynku z Visual Studio Code.

Parametry klucza CMake są oddzielone spacjami. Znak kontynuacji wiersza "^" dla wiersza polecenia systemu Windows, " \ " dla wiersza polecenia systemu Linux lub znak "'" dla programu Powershell może być używany w celu zwiększenia czytelności, ale nie jest wymagany. Konkretny znak jest określany na podstawie konfiguracji terminali systemu Windows lub Linux.

CMake functions for Azure Sphere

Plik CMakeLists.txt zawiera ogólne ustawienia konfiguracji używane przez usługę CMake do utworzenia aplikacji. Usługa Azure Sphere obsługuje korzystanie z następujących funkcji w CMakeLists.txt:

Nazwa	Celu
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ę utworzoną przy użyciu klucza SDK wcześniejszego niż 20.04, zobacz Konwertowanie istniejącej aplikacji na używanie funkcji CMake.

Plik CMakeLists.txt musi wywołać polecenie projektu przed azsphere_ funkcji.

Docelowa definicja sprzętu

Możesz określić sprzęt, na który chcesz kierować reklamy , wywołując funkcję azsphere_target_hardware_definition w celu przechowywania wartości w CMakeLists.txt. Ta funkcja wymaga dwóch parametrów: listy wyszukiwanych katalogów i nazwy 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 wymaganego przez aplikację. Parametr TARGET_DIRECTORY zawiera listę katalogów, w których chcesz wyszukać ten plik. Ten parametr jest opcjonalny. Jeśli go pominiesz, usługa CMake będzie wyglądać tylko w folderze HardwareDefinitions w instalacji SDK. Aby określić wiele folderów, ujmij każdą nazwę folderu w podwójny cudzysłów i rozdziel nazwy folderów spację, tak jak w przykładzie. W tym przykładzie <ścieżka> reprezentuje ścieżkę do folderu my_app na komputerze deweloperskim.

Tworzenie pakietu obrazów

Określ plik pakietu obrazów i wszystkie pliki zasobów , które mają zostać uwzględnione podczas tworzenia, wywołując funkcję azsphere_target_add_image_package w celu przechowywania wartości w CMakeLists.txt. Wymagana jest funkcja azsphere_target_add_image_package i projekt do utworzenia; pliki zasobów są opcjonalne.

Następujące wywołanie funkcji tworzy pakiet obrazów, który zawiera tylko aplikację Azure Sphere:

azsphere_target_add_image_package(${PROJECT_NAME})

W następnym przykładzie jest tworzony pakiet obrazów zawierający certyfikat oprócz aplikacji:

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

Obiekt docelowy 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 CMake

Przed zestawem SDK w wersji 24.03 funkcje CMake azsphere_configure_tools i azsphere_configure_api były używane do określania 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ę Wersja środowiska uruchomieniowego aplikacji, sysroots i interfejsy API beta .

Jeśli używasz starszej wersji klucza SDK i zostanie wyświetlony błąd konfiguracji usługi CMake dotyczący poprawki nieobsługiwanych narzędzi, możesz obejść ten problem, ponownie dodając te funkcje do CMakeLists.txt. Na przykład:

azsphere_configure_tools(TOOLS_REVISION 23.05) azsphere_configure_api(TARGET_API_SET 16)

Jak usunąć pamięć podręczną usługi CMake podczas zmieniania plików konfiguracji

Jeśli zmienisz jeden z plików konfiguracji, należy usunąć pamięć podręczną usługi CMake, aby upewnić się, że kolejne kompilacje nie powiedzie się. Wykonaj tę procedurę przed podjęciem próby innej kompilacji:

W przypadku Visual Studio Code kompilacji uruchom polecenie CMake:Delete Cache i 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 usługi CMake i automatycznie usuwa pamięć podręczną.

Konwertowanie istniejącej aplikacji na używanie funkcji CMake

Jeśli masz już aplikację Azure Sphere, która została utworzona za pomocą narzędzia CMake przed kompilacją SDK 20.04, należy ją przekonwertować, aby korzystać z tych nowych funkcji. Na razie możesz tworzyć takie aplikacje bez zmian, ale ich obsługa jest ograniczona i może zostać usunięta w przyszłej wersji.

Aby uzyskać przykład zmian, które należy wprowadzić, sprawdź, jak pliki konfiguracji CMakeLists.txt i *.json zostały zmienione dla aplikacji wysokiej poziomu aktualizacji mcu zewnętrznej dla wersji 20.04.

Uwaga

Oprócz aktualizacji dotyczących korzystania z tych funkcji, pliki te zostały zaktualizowane w przykładach usługi Azure Sphere w celu użycia małych nazw funkcji, dzięki czemu są one zgodne z konwencjami CMake.

zmiany konfiguracji CMakeLists.txt

W poniższych przykładach przedstawiono zmiany wymagane do zaktualizowania pliku CMakeLists.txt z wersji 20.01 lub wcześniejszej w celu korzystania z nowych funkcji.

Przykład pliku 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}")

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 zbudować pakiet obrazów i opcjonalnie określić pliki, które mają być w nim uwzględnione.

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 dla RESOURCE_FILES.

Konfiguracja CMakePresets.json programu Visual Studio

Plik CMakePresets.json umożliwia określenie typowych opcji konfiguracji, kompilacji i testowania, a następnie udostępnianie ich deweloperom przy użyciu innych środowisk deweloperskich. Na przykład możesz użyć tego samego pliku konfiguracji ustawień wstępnych, aby wywołać funkcję CMake w programie Visual Studio, Visual Studio Code, potoku ciągłej integracji lub z interfejsu cli w systemie Windows, Linux lub macOS.

Od wersji 22.07 bieżące projekty używają wstępnie zdefiniowanych ustawień zdefiniowanych w CMakePresets.json, natomiast istniejące projekty mogą nadal korzystać z ustawień w CMakeSettings.json. Przykłady są dostarczane tylko z jednym plikiem konfiguracji , CMakePresets.json lub CMakeSettings.json. W środowisku deweloperskim zostanie użyty plik, który jest obecny. Zapoznaj się z poszczególnymi przykładowymi projektami, aby sprawdzić, 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; tylko różnice są w CMAKE_TOOLCHAIN_FILE zmiennych 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 sprawdzić, który plik jest używany. W tej sekcji opisano konfigurację CMakeSettings.json. W przypadku projektów korzystających z CMakePresets.json zobacz Zmiany konfiguracji programu Visual Studio CMakePresets.json.

W poniższych przykładach przedstawiono zmiany wymagane do zaktualizowania pliku CMakeSettings.json w programie Visual Studio z wersji 20.01 lub wcześniejszej w celu korzystania z nowych funkcji.

Przykład pliku CMakeSettings.json 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}"
        }
      ]
    }
  ]
}

Zaktualizowany plik CMakeSettings.json SDK

Zaktualizowany plik CMakeSettings.json zawiera następujące zmiany:

W polu "środowiska" jest wymagane tylko "Azure Sphere".
W polu "konfiguracje" zarówno dla kompilacji Debugowanie, jak i Release:
- Wartości "buildRoot" i "installRoot" nie wymagają już ustawienia AzureSphereTargetApiSet.
- Narzędzie CMake jest teraz zdefiniowane w "cmakeToolChain", a nie w "zmiennych".
- Pole "zmienne" określa teraz tylko docelowy zestaw interfejsów API i używa nowej wartości "latest-lts", aby wskazać, że projekt powinien zostać utworzony przy użyciu najnowszego sysrootu długoterminowej stabilnej (LTS). Ustawienia AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY i AZURE_SPHERE_TARGET_HARDWARE_DEFINITION nie są już wymagane, ponieważ te wartości są teraz ustawione w plikuCMakeLists.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 Visual Studio Code vscode/settings.json

W poniższych przykładach przedstawiono zmiany wymagane do zaktualizowania pliku vscode/settings.json dla Visual Studio Code z wersji 20.01 lub starszej w celu korzystania z nowych funkcji.

Przykład pliku vscode/settings.json 20.01 SDK

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

Zaktualizowany plik vscode/settings.json

Plik vscode/settings.json zawiera ustawienia obszaru roboczego dla Visual Studio Code.

Zaktualizowany plik settings.json zawiera następujące zmiany w polu "cmake.configureSettings":

Ustawienia AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY i AZURE_SPHERE_TARGET_HARDWARE_DEFINITION nie są już wymagane, ponieważ te wartości są teraz ustawione w plikuCMakeLists.txt .
Ustawienia CMAKE_TOOLCHAIN_FILE i AZURE_SPHERE_TARGET_API_SET nie są już wymagane, ponieważ te wartości są teraz ustawione w pliku CMakePresets.json . Wartość AZURE_SPHERE_TARGET_API_SET to teraz "latest-lts", co wskazuje, że projekt powinien zostać skonstruowany przy użyciu najnowszego sysrootu długoterminowej stabilnej (LTS).

Należy pamiętać "cmake.configureArgs" , że pole również zostało usunięte z przyczyn niezwiązanych z programem CMake. (Pole nie jest już wymagane, ponieważ --no-warn-unused-cli parametr nie jest potrzebny dla tej kompilacji).

Do rozszerzeń mają zastosowanie następujące pola:

"cmake.configureOnOpen": true powiadamia rozszerzenie cmake-tools , aby rozpocząć konfigurowanie po otwarciu obszaru roboczego.
"C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools" określa dostawcę IntelliSense do używania 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 korzystasz z programu Visual Studio 2022 w wersji 17.1 lub nowszej i masz projekt z wieloma źródłami, takimi jak przykład IntercoreComms, musisz dodać plik CMakeWorkspaceSettings.json do folderu najwyższego poziomu projektu. Plik zawiera dwa wpisy, jeden określający, że jest włączona kompilacja CMake i jeden zawierający ścieżki do wielu katalogów głównych. Na przykład dla przykładu IntercoreComms CMakeWorkspaceSettings.json ma następującą zawartość:

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

Ścieżki są określone względem folderu zawierającego plik CMakeWorkspaceSettings.json.