CMake kullanarak derlemeleri yapılandırma

  • Makale

Azure Sphere; Visual Studio, Visual Studio Code ve Windows ve Linux komut satırlarıyla uygulamalar için derlemeleri yapılandırmak için CMake kullanır. CMake açık kaynaklı, platformlar arası bir sistemdir. CMake hakkında genel bilgi için bkz. CMake Wiki.

Aşağıdaki kaynaklar, Visual Studio veya Visual Studio Code ile CMake kullanma hakkında bilgi sağlar:

CMake derlemeleri aşağıdaki dosyaları kullanır:

Dosya Amaç
CMakeLists.txt Genel CMake yapılandırma dosyası. Tüm derlemeler için gereklidir.
CMakePresets.json Visual Studio ve Visual Studio Code için yapılandırma hazır ayarları dosyası. Visual Studio ile derlemek için bu dosya veya CMakeSettings.json gereklidir.
CMakeSettings.json Visual Studio yapılandırma dosyası. Visual Studio ile derlemek için bu dosya veya CMakePresets.json gereklidir.
CMakeWorkspaceSettings.json IntercoreComms örneğinde olduğu gibi birden çok köke sahip projeler için Visual Studio yapılandırma dosyası.
.vscode/settings.json yapılandırma dosyasını Visual Studio Code. Visual Studio Code ile bina için gereklidir.

CMake parametreleri boşluklarla ayrılır. Windows komut satırı için "^", Linux komut satırı için " \ " veya Powershell için "'" satır devamlılığı karakteri okunabilirlik için kullanılabilir ancak gerekli değildir. Belirli karakter Windows veya Linux terminal yapılandırması tarafından belirlenir.

Azure Sphere için CMake işlevleri

CMakeLists.txt dosyası, CMake'in uygulama oluşturmak için kullandığı genel yapılandırma ayarlarını sağlar. Azure Sphere, CMakeLists.txt'de aşağıdaki işlevlerin kullanımını destekler:

Adı Amaç
azsphere_target_hardware_definition Hedef donanımı belirtin.
azsphere_target_add_image_package Görüntü paketi oluşturun.

20.04'ten önceki bir SDK ile oluşturulmuş mevcut bir uygulamanız varsa bkz. CMake işlevlerini kullanmak için var olan bir uygulamayı dönüştürme.

CMakeLists.txt dosyası, azsphere_ işlevlerinden herhangi biri olmadan önce project komutunu çağırmalıdır.

Hedef donanım tanımı

Değeri CMakeLists.txt depolamak için azsphere_target_hardware_definition işlevini çağırarak hedeflediğiniz donanımı belirtebilirsiniz. Bu işlev iki parametre alır: aranacak dizinlerin listesi ve aranacak dosya adı. Örneğin:

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

TARGET_DEFINITION parametresi gereklidir. Uygulamanızın gerektirdiği donanım tanımı dosyasının adını belirtir. TARGET_DIRECTORY parametresi, bu dosyanın arandığı dizinleri listeler. Bu parametre isteğe bağlıdır; bunu atlarsanız, CMake yalnızca SDK yüklemesindeki HardwareDefinitions klasöründe görünür. Birden çok klasör belirtmek için, her klasör adını çift tırnak içine alın ve örnekte olduğu gibi klasör adlarını ayırmak için bir boşluk kullanın. Örnekte yol>, <geliştirme makinenizdeki my_app klasörünün yolunu temsil eder.

Görüntü paketi oluşturma

görüntü paketi dosyasını ve değeri CMakeLists.txt depolamak için azsphere_target_add_image_package işlevini çağırarak derleme sırasında eklenecek tüm kaynak dosyalarını belirtin. azsphere_target_add_image_package işlevi ve derleme projesi gereklidir; kaynak dosyaları isteğe bağlıdır.

Aşağıdaki işlev çağrısı yalnızca Azure Sphere uygulamasını içeren bir görüntü paketi oluşturur:

azsphere_target_add_image_package(${PROJECT_NAME})

Sonraki örnek, uygulamaya ek olarak sertifika içeren bir görüntü paketi oluşturur:

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

azsphere_target_add_image_package geçirilen CMake hedefi ${PROJECT_NAME} olarak adlandırılmalıdır ve azsphere_target_add_image_package işlevi CMakeLists.txt dosyasından yalnızca bir kez çağrılabilir.

Kullanım dışı bırakılmış CMake işlevleri

SDK 24.03 sürümünden önce, CMakeLists.txt dosyasında ayarlanan hedef SDK araçları sürümünü ve hedef API'yi belirtmek için CMake işlevleri azsphere_configure_tools ve azsphere_configure_api kullanıldı. Bu işlevler artık kullanım dışıdır ve bunun yerine hedef API kümesi uygun yapılandırma dosyasında belirtilmelidir. Ayrıntılar için Uygulama çalışma zamanı sürümü, sysroots ve Beta API'ler sayfasına bakın.

SDK'nın eski bir sürümünü kullanıyorsanız ve desteklenmeyen araçlar düzeltmesi hakkında CMake yapılandırma hatası görüyorsanız, bu işlevleri CMakeLists.txt yeniden ekleyerek bu sorunu çözebilirsiniz. Örnek olarak:

azsphere_configure_tools(TOOLS_REVISION 23.05) azsphere_configure_api(TARGET_API_SET 16)

Yapılandırma dosyalarını değiştirirken CMake önbelleğini silme

Yapılandırma dosyalarından birini değiştirirseniz, sonraki derlemelerin başarısız olmadığından emin olmak için CMake önbelleğini silmeniz gerekir. Başka bir derleme denemeden önce şu yordamı izleyin:

  • Visual Studio Code derlemeler için Komut Paleti'nden CMake:Delete Cache ve Reconfigure komutunu çalıştırın.
  • Komut satırı (CLI) derlemeleri için önceki bir adımda oluşturduğunuz derleme dizinini silin.

Visual Studio, CMake yapılandırma dosyasındaki değişiklikleri algılar ve önbelleği otomatik olarak siler.

Mevcut bir uygulamayı CMake işlevlerini kullanacak şekilde dönüştürme

CMake ile 20.04 SDK'sı öncesinde oluşturulmuş bir Azure Sphere uygulamanız zaten varsa, bu yeni işlevleri kullanmak için dönüştürmeniz gerekir. Şimdilik bu tür uygulamaları hala değiştirmeden oluşturabilirsiniz, ancak bunlara yönelik destek sınırlıdır ve gelecek bir sürümde kaldırılabilir.

Yapmanız gereken değişikliklere örnek olarak, 20.04 sürümü için Dış MCU Güncelleştirmesi üst düzey uygulaması için CMakeLists.txt ve *.json yapılandırma dosyalarının nasıl değiştirildiğine bakın.

Not

İşlevleri kullanmaya yönelik güncelleştirmelere ek olarak, bu dosyalar Azure Sphere örneklerinde küçük harf işlev adlarını kullanacak şekilde güncelleştirilmiştir ve bu nedenle CMake kurallarıyla uyumlu hale getirilmiştir.

Yapılandırma değişikliklerini CMakeLists.txt

Aşağıdaki örneklerde, yeni işlevleri kullanmak üzere 20.01 veya önceki sürümlerden CMakeLists.txt dosyasını güncelleştirmek için gereken değişiklikler gösterilir.

Örnek 20.01 SDK CMakeLists.txt dosyası

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

Güncelleştirilmiş CMakeLists.txt dosyası

Güncelleştirilmiş CMakeLists.txt dosyası, hedef donanımı ayarlamak için azsphere_target_hardware_definition işlevlerini çağırır. Ayrıca görüntü paketini oluşturmak için azsphere_target_add_image_package çağırır ve isteğe bağlı olarak buna eklenecek dosyaları belirtir.

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

Not

Mutlak yollar RESOURCE_FILES için desteklenmez.

Visual Studio CMakePresets.json yapılandırması

CMakePresets.json dosyası ortak yapılandırma, derleme ve test seçeneklerini belirtmenize, ardından bunları diğer geliştirme ortamlarını kullanarak geliştiricilerle paylaşmanıza olanak tanır. Örneğin, Visual Studio, Visual Studio Code, Sürekli Tümleştirme işlem hattı veya Windows, Linux veya macOS üzerinde CLI'dan CMake'yi çağırmak için aynı ön ayar yapılandırma dosyasını kullanabilirsiniz.

22.07 sürümünden itibaren geçerli projeler CMakePresets.json'de tanımlanan ön ayarları kullanırken, mevcut projeler CMakeSettings.json'da ayarları kullanmaya devam edebilir. Örnekler, CMakePresets.json veya CMakeSettings.json tek bir yapılandırma dosyasıyla birlikte gönderilir. Geliştirme ortamı, mevcut dosyayı kullanır. Hangi dosyanın kullanıldığını görmek için her örnek projeye bakın. CMakeSettings.json kullanan projeler için bkz. Visual Studio CMakeSettings.json yapılandırma değişiklikleri.

Üst düzey bir uygulama ve gerçek zamanlı bir uygulama için CMakePresets.json dosyaları çok benzer; tek farklar ve ARM_GNU_PATH değişkenlerindedirCMAKE_TOOLCHAIN_FILE.

Üst düzey bir uygulamada ARM_GNU_PATH ayarlanmaz ve CMAKE_TOOLCHAIN_FILE aşağıdaki gibi ayarlanır:

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

Gerçek zamanlı bir uygulamada CMAKE_TOOLCHAIN_FILE ve ARM_GNU_PATH aşağıdaki gibi ayarlanır:

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

Visual Studio CMakeSettings.json yapılandırması

Örnekler bir CMakePresets.json veya CMakeSettings.json yapılandırma dosyasıyla birlikte gönderilir. Hangi dosyanın kullanıldığını görmek için her projeye bakın. Bu bölümde CMakeSettings.json yapılandırması açıklanmaktadır. CMakePresets.json kullanan projeler için bkz. Visual Studio CMakePresets.json yapılandırma değişiklikleri.

Aşağıdaki örneklerde, Visual Studio'daki CMakeSettings.json dosyasını 20.01 veya önceki sürümlerden güncelleştirerek yeni işlevleri kullanmak için gereken değişiklikler gösterilir.

Örnek 20.01 SDK CMakeSettings.json dosyası

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

GÜNCELLEŞTIRILmiş SDK CMakeSettings.json dosyası

Güncelleştirilmiş CMakeSettings.json dosyası aşağıdaki değişiklikleri içerir:

  • "Ortamlar" alanında yalnızca "Azure Sphere" gereklidir.
  • Hem Hata Ayıklama hem de Yayın derlemeleri için "yapılandırmalar" alanında:
    • "buildRoot" ve "installRoot" değerleri artık AzureSphereTargetApiSet ayarını gerektirmez.
    • CMake araç zinciri artık "değişkenler" yerine "cmakeToolChain" içinde tanımlanır.
    • "Değişkenler" alanı artık yalnızca hedef API kümesini belirtir ve projenin en son uzun vadeli kararlı (LTS) sysroot ile derlenmesi gerektiğini belirtmek için yeni "latest-lts" değerini kullanır. Bu değerler artıkCMakeLists.txt dosyasında ayarlandığından AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY ve AZURE_SPHERE_TARGET_HARDWARE_DEFINITION ayarları artık gerekli değildir.
{
  "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"
        }
      ]
    }
  ]
}

.vscode/settings.json yapılandırması Visual Studio Code

Aşağıdaki örneklerde, yeni işlevleri kullanmak üzere 20.01 veya önceki sürümlerden Visual Studio Code için .vscode/settings.json dosyasını güncelleştirmek için gereken değişiklikler gösterilir.

Örnek 20.01 SDK .vscode/settings.json dosyası

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

Güncelleştirilmiş .vscode/settings.json dosyası

.vscode/settings.json dosyası Visual Studio Code için çalışma alanı ayarlarını içerir.

Güncelleştirilmiş settings.json dosyası "cmake.configureSettings" alanında aşağıdaki değişiklikleri içerir:

  • AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY Bu değerler artık CMakeLists.txt dosyasında ayarlandığından ve AZURE_SPHERE_TARGET_HARDWARE_DEFINITION ayarları artık gerekli değildir.
  • CMAKE_TOOLCHAIN_FILE Bu değerler artık CMakePresets.json dosyasında ayarlandığından ve AZURE_SPHERE_TARGET_API_SET ayarları artık gerekli değildir. AZURE_SPHERE_TARGET_API_SET şimdi değeridir ve "latest-lts"bu da projenin en son uzun vadeli kararlı (LTS) sysroot ile derlenmesi gerektiğini gösterir.

"cmake.configureArgs" Alanın CMake ile ilgisiz nedenlerle de silindiğini unutmayın. (Bu derleme için parametre gerekli --no-warn-unused-cli olmadığından alan artık gerekli değildir.)

Uzantılar için aşağıdaki alanlar geçerlidir:

  • "cmake.configureOnOpen": true çalışma alanı açıldığında yapılandırmaya başlamak için cmake-tools uzantısını bildirir.

  • "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools"cpp-tools uzantısı için kullanılacak IntelliSense sağlayıcısını belirtir; bu durumda, cmake-tools uzantısı.

{
    "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 dosyası oluşturma

Visual Studio 2022, sürüm 17.1 veya üzerini kullanıyorsanız ve IntercoreComms örneği gibi birden çok köke sahip bir projeniz varsa, projenin en üst düzey klasörüne bir CMakeWorkspaceSettings.json dosyası eklemeniz gerekir. Dosyada, biri CMake derlemesinin etkinleştirildiğini, diğeri de birden çok köke giden yolları içeren iki girdi vardır. Örneğin, IntercoreComms örneği için CMakeWorkspaceSettings.json aşağıdaki içeriğe sahiptir:

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

Yollar, CMakeWorkspaceSettings.json dosyasını içeren klasöre göre belirtilir.