Mengonfigurasi build menggunakan CMake

Penting

Ini adalah dokumentasi Azure Sphere (Warisan). Azure Sphere (Warisan) dihentikan pada 27 September 2027, dan pengguna harus bermigrasi ke Azure Sphere (Terintegrasi) saat ini. Gunakan pemilih Versi yang terletak di atas TOC untuk melihat dokumentasi Azure Sphere (Terintegrasi).

Azure Sphere menggunakan CMake untuk mengonfigurasi build untuk aplikasi dengan Visual Studio, Visual Studio Code, dan baris perintah Windows dan Linux. CMake adalah sistem pembuat lintas platform sumber terbuka. Untuk informasi umum tentang CMake, lihat Wiki CMake.

Sumber berikut ini menyediakan informasi tentang menggunakan CMake dengan Visual Studio atau Visual Studio Code:

• Proyek CMake di Visual Studio
• Ekstensi Alat CMake untuk Visual Studio Code

Build CMake menggunakan file berikut:

File	Tujuan
CMakeLists.txt	File konfigurasi CMake umum. Diperlukan untuk semua build.
CMakePresets.json	File prasetel konfigurasi untuk Visual Studio dan Visual Studio Code. File ini atau CMakeSettings.json diperlukan untuk membangun dengan Visual Studio.
CMakeSettings.json	File konfigurasi Visual Studio. File ini atau CMakePresets.json diperlukan untuk membangun dengan Visual Studio.
CMakeWorkspaceSettings.json	File konfigurasi Visual Studio untuk proyek dengan beberapa root, seperti dalam sampel IntercoreComms.
.vscode/settings.json	File konfigurasi Visual Studio Code. Diperlukan untuk membangun dengan Visual Studio Code.

Parameter CMake dipisahkan oleh spasi. Karakter kelanjutan baris "^" untuk baris perintah Windows, " \ " untuk baris perintah Linux, atau "'" untuk Powershell dapat digunakan untuk keterbacaan tetapi tidak diperlukan. Karakter tertentu ditentukan oleh konfigurasi terminal Windows atau Linux.

Fungsi CMake untuk Azure Sphere

File CMakeLists.txt menyediakan pengaturan konfigurasi umum yang digunakan CMake untuk membangun aplikasi. Azure Sphere mendukung penggunaan fungsi berikut dalam CMakeLists.txt:

Nama	Tujuan
azsphere_target_hardware_definition	Tentukan perangkat keras target.
azsphere_target_add_image_package	Buat paket gambar.

Jika Anda memiliki aplikasi yang sudah ada yang dibuat dengan SDK yang lebih awal dari 20.04, lihat Mengonversi aplikasi yang ada untuk menggunakan fungsi CMake.

File CMakeLists.txt harus memanggil perintah proyek sebelum salah satu fungsi azsphere_ .

Definisi perangkat keras target

Anda dapat menentukan perangkat keras yang Anda targetkan dengan memanggil fungsi azsphere_target_hardware_definition untuk menyimpan nilai dalam CMakeLists.txt. Fungsi ini mengambil dua parameter: daftar direktori untuk dicari dan nama file untuk dicari. Contohnya:

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

Parameter TARGET_DEFINITION diperlukan. Ini menentukan nama file definisi perangkat keras yang diperlukan aplikasi Anda. Parameter TARGET_DIRECTORY mencantumkan direktori untuk mencari file ini. Parameter ini bersifat opsional; jika Anda menghilangkannya, CMake hanya terlihat di folder HardwareDefinitions di penginstalan SDK. Untuk menentukan beberapa folder, sertakan setiap nama folder dalam tanda kutip ganda dan gunakan spasi untuk memisahkan nama folder, seperti dalam contoh. Dalam contoh, <jalur> mewakili jalur ke folder my_app pada komputer pengembangan Anda.

Pembuatan paket gambar

Tentukan file paket gambar dan file sumber daya apa pun yang akan disertakan saat membangun dengan memanggil fungsi azsphere_target_add_image_package untuk menyimpan nilai dalam CMakeLists.txt. Fungsi azsphere_target_add_image_package dan proyek yang akan dibangun diperlukan; file sumber daya bersifat opsional.

Panggilan fungsi berikut membuat paket gambar yang hanya berisi aplikasi Azure Sphere:

azsphere_target_add_image_package(${PROJECT_NAME})

Contoh berikutnya membuat paket gambar yang berisi sertifikat selain aplikasi:

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

Target CMake yang diteruskan ke azsphere_target_add_image_package harus bernama ${PROJECT_NAME}, dan fungsi azsphere_target_add_image_package hanya dapat dipanggil sekali dari file CMakeLists.txt.

Fungsi CMake yang tidak digunakan lagi

Sebelum SDK versi 24.03, fungsi CMake azsphere_configure_tools dan azsphere_configure_api digunakan untuk menentukan versi alat SDK target dan API target yang ditetapkan dalam file CMakeLists.txt. Fungsi-fungsi ini sekarang tidak digunakan lagi, dan set API target harus ditentukan dalam file konfigurasi yang sesuai sebagai gantinya. Lihat halaman Versi runtime aplikasi, sysroots, dan BETA API untuk detailnya.

Jika Anda menggunakan versi SDK yang lebih lama dan melihat kesalahan konfigurasi CMake tentang revisi alat yang tidak didukung, Anda dapat mengatasinya dengan menambahkan kembali fungsi tersebut ke CMakeLists.txt. Sebagai contoh:

azsphere_configure_tools(TOOLS_REVISION 23.05) azsphere_configure_api(TARGET_API_SET 16)

Cara menghapus cache CMake saat mengubah file konfigurasi

Jika Anda mengubah salah satu file konfigurasi, Anda harus menghapus cache CMake untuk memastikan bahwa build berikutnya tidak gagal. Ikuti prosedur ini sebelum mencoba build lain:

• Untuk build Visual Studio Code, jalankan perintah CMake:Delete Cache and Reconfigure dari Palet Perintah.
• Untuk build baris perintah (CLI), hapus direktori build yang Anda buat di langkah sebelumnya.

Visual Studio mendeteksi perubahan pada file konfigurasi CMake dan menghapus cache secara otomatis.

Mengonversi aplikasi yang ada untuk menggunakan fungsi CMake

Jika Anda sudah memiliki aplikasi Azure Sphere yang dibangun dengan CMake sebelum SDK 20.04, Anda harus mengonversinya untuk menggunakan fungsi baru ini. Anda masih dapat membangun aplikasi tersebut untuk saat ini, tetapi dukungan untuk aplikasi tersebut terbatas dan dapat dihapus dalam rilis mendatang.

Untuk contoh perubahan yang harus Anda buat, lihat bagaimana file konfigurasi CMakeLists.txt dan *.json diubah untuk aplikasi tingkat tinggi Pembaruan MCU Eksternal untuk rilis 20.04.

Catatan

Selain pembaruan untuk menggunakan fungsi, file-file ini telah diperbarui dalam sampel Azure Sphere untuk menggunakan nama fungsi huruf kecil, sehingga selaras dengan konvensi CMake.

perubahan konfigurasi CMakeLists.txt

Contoh berikut menunjukkan perubahan yang diperlukan untuk memperbarui file CMakeLists.txt dari 20.01 atau yang lebih lama untuk menggunakan fungsi baru.

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

File CMakeLists.txt yang diperbarui

File CMakeLists.txt yang diperbarui memanggil fungsi azsphere_target_hardware_definition untuk mengatur perangkat keras target. Ini juga memanggil azsphere_target_add_image_package untuk membangun paket gambar dan secara opsional menentukan file yang akan disertakan di dalamnya.

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

Catatan

Jalur absolut tidak didukung untuk RESOURCE_FILES.

Konfigurasi CMakePresets.json Visual Studio

File CMakePresets.json memungkinkan Anda menentukan opsi konfigurasi, build, dan pengujian umum, lalu membagikannya dengan pengembang menggunakan lingkungan pengembangan lainnya. Misalnya, Anda dapat menggunakan file konfigurasi prasetel yang sama untuk memanggil CMake di Visual Studio, Visual Studio Code, alur Integrasi Berkelanjutan, atau dari CLI di Windows, Linux, atau macOS.

Pada rilis 22.07, proyek saat ini menggunakan preset yang ditentukan dalam CMakePresets.json, sementara proyek yang ada dapat terus menggunakan pengaturan di CMakeSettings.json. Sampel hanya dikirim dengan satu file konfigurasi, baik CMakePresets.json atau CMakeSettings.json. Lingkungan pengembangan akan menggunakan file yang ada. Lihat setiap proyek sampel untuk melihat file mana yang digunakan. Untuk proyek yang menggunakan CMakeSettings.json, lihat Visual Studio CMakeSettings.json perubahan konfigurasi.

File CMakePresets.json untuk aplikasi tingkat tinggi dan untuk aplikasi real time sangat mirip; satu-satunya perbedaan adalah dalam CMAKE_TOOLCHAIN_FILE variabel dan ARM_GNU_PATH .

Dalam aplikasi tingkat tinggi, ARM_GNU_PATH tidak diatur, dan CMAKE_TOOLCHAIN_FILE diatur sebagai berikut:

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

Dalam aplikasi real-time, CMAKE_TOOLCHAIN_FILE dan ARM_GNU_PATH diatur sebagai berikut:

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

Konfigurasi CMakeSettings.json Visual Studio

Sampel dikirim dengan file konfigurasi CMakePresets.json atau CMakeSettings.json. Lihat setiap proyek untuk melihat file mana yang digunakan. Bagian ini menjelaskan konfigurasi CMakeSettings.json. Untuk proyek yang menggunakan CMakePresets.json, lihat Perubahan konfigurasi visual Studio CMakePresets.json.

Contoh berikut menunjukkan perubahan yang diperlukan untuk memperbarui file CMakeSettings.json di Visual Studio dari 20.01 atau yang lebih lama untuk menggunakan fungsi baru.

Contoh file 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}"
        }
      ]
    }
  ]
}

File CMakeSettings.json SDK yang diperbarui

File CMakeSettings.json yang diperbarui mencakup perubahan berikut:

• Di bidang "lingkungan", hanya "Azure Sphere" yang diperlukan.
• Di bidang "konfigurasi" untuk build Debug dan Rilis:
  • Nilai "buildRoot" dan "installRoot" tidak lagi memerlukan pengaturan AzureSphereTargetApiSet.
  • Toolchain CMake sekarang didefinisikan dalam "cmakeToolChain", alih-alih dalam "variabel".
  • Bidang "variabel" sekarang hanya menentukan set API target dan menggunakan nilai "latest-lts" baru untuk menunjukkan bahwa proyek harus dibangun dengan sysroot long-term-stable (LTS) terbaru. Pengaturan AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY dan AZURE_SPHERE_TARGET_HARDWARE_DEFINITION tidak lagi diperlukan, karena nilai-nilai ini sekarang diatur dalam file 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"
        }
      ]
    }
  ]
}

Konfigurasi .vscode/settings.json Visual Studio Code

Contoh berikut menunjukkan perubahan yang diperlukan untuk memperbarui file .vscode/settings.json untuk Visual Studio Code dari 20.01 atau yang lebih lama untuk menggunakan fungsi baru.

Contoh file .vscode/settings.json 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"
}

File .vscode/settings.json yang diperbarui

File .vscode/settings.json berisi pengaturan ruang kerja untuk Visual Studio Code.

File settings.json yang diperbarui mencakup perubahan berikut pada bidang "cmake.configureSettings":

• Pengaturan AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY dan AZURE_SPHERE_TARGET_HARDWARE_DEFINITION tidak lagi diperlukan, karena nilai-nilai ini sekarang diatur dalam file CMakeLists.txt .
• Pengaturan CMAKE_TOOLCHAIN_FILE dan AZURE_SPHERE_TARGET_API_SET tidak lagi diperlukan, karena nilai-nilai ini sekarang diatur dalam file CMakePresets.json . Nilainya AZURE_SPHERE_TARGET_API_SET sekarang "latest-lts", yang menunjukkan bahwa proyek harus dibangun dengan sysroot long-term-stable (LTS) terbaru.

Perhatikan bahwa "cmake.configureArgs" bidang juga telah dihapus karena alasan yang tidak terkait dengan CMake. (Bidang tidak lagi diperlukan karena --no-warn-unused-cli parameter tidak diperlukan untuk build ini.)

Bidang berikut berlaku untuk ekstensi:

• "cmake.configureOnOpen": true memberi tahu ekstensi cmake-tools untuk mulai mengonfigurasi saat ruang kerja terbuka.

• "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools" menentukan penyedia IntelliSense untuk digunakan untuk ekstensi cpp-tools ; dalam hal ini, ekstensi 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"
}

Membuat file CMakeWorkspaceSettings.json

Jika Anda menggunakan Visual Studio 2022, versi 17.1 atau yang lebih baru, dan Anda memiliki proyek dengan beberapa root, seperti sampel IntercoreComms, Anda harus menambahkan file CMakeWorkspaceSettings.json ke folder tingkat atas proyek. File memiliki dua entri, satu untuk menentukan bahwa build CMake diaktifkan dan satu berisi jalur ke beberapa akar. Misalnya, untuk sampel IntercoreComms, CMakeWorkspaceSettings.json memiliki konten berikut:

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

Jalur ditentukan relatif terhadap folder yang berisi file CMakeWorkspaceSettings.json.