Mengonfigurasi build menggunakan CMake

Artikel
03/27/2024

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

Sumber berikut ini menyediakan informasi tentang menggunakan CMake dengan Visual Studio atau 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. Baik file ini atau CMakeSettings.json diperlukan untuk membangun dengan Visual Studio.
CMakeSettings.json	File konfigurasi Visual Studio. Baik file ini atau CMakePresets.json diperlukan untuk membangun dengan Visual Studio.
CMakeWorkspaceSettings.json	File konfigurasi Visual Studio untuk proyek dengan beberapa akar, seperti dalam sampel IntercoreComms.
.vscode/settings.json	Visual Studio Code file konfigurasi. 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 membuat 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 lama dari 20.04, lihat Mengonversi aplikasi yang sudah ada untuk menggunakan fungsi CMake.

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

Definisi perangkat keras target

Anda bisa menentukan perangkat keras yang Anda targetkan dengan memanggil fungsi azsphere_target_hardware_definition untuk menyimpan nilai di CMakeLists.txt. Fungsi ini memerlukan dua parameter: daftar direktori untuk dicari dan nama file untuk dicari. Misalnya:

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 opsional; jika Anda menghilangkannya, CMake hanya terlihat di folder HardwareDefinitions dalam penginstalan SDK. Untuk menentukan beberapa folder, apit 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 di komputer pengembangan Anda.

Pembuatan paket gambar

Tentukan file paket gambar dan file sumber daya apa pun untuk disertakan saat menyusun dengan memanggil fungsi azsphere_target_add_image_package untuk menyimpan nilai di 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 dikirim ke azsphere_target_add_image_package harus bernama ${PROJECT_NAME}, dan fungsi azsphere_target_add_image_package hanya dapat disebut 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 set API target dalam file CMakeLists.txt. Fungsi-fungsi ini kini sudah tidak digunakan lagi, dan kumpulan API target harus ditentukan dalam file konfigurasi yang sesuai. Lihat halaman Aplikasi versi runtime, sysroot, dan API Beta untuk detailnya.

Jika 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 singgahan CMake saat mengubah file konfigurasi

Jika 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:Hapus Singgahan dan Konfigurasi Ulang 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 sudah ada untuk menggunakan fungsi CMake

Jika Anda sudah memiliki aplikasi Azure Sphere yang dibuat dengan CMake sebelum 20.04 SDK, Anda harus mengonversinya untuk menggunakan fungsi baru ini. Anda masih dapat membuat aplikasi tersebut untuk saat ini, tetapi dukungan untuk aplikasi tersebut terbatas dan mungkin 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 ini telah diperbarui dalam sampel Azure Sphere untuk menggunakan nama fungsi huruf kecil, sehingga selaras dengan konvensi CMake.

CMakeLists.txt perubahan konfigurasi

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

Contoh 20.01 SDK CMakeLists.txt file

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 menyusun paket gambar dan secara opsional menentukan file untuk 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 lain. Misalnya, Anda dapat menggunakan file konfigurasi prasetel yang sama untuk memanggil CMake di Visual Studio, Visual Studio Code, pipeline Integrasi Berkelanjutan, atau dari CLI di Windows, Linux, atau macOS.

Mulai rilis 22.07, proyek saat ini menggunakan preset yang ditentukan dalam CMakePresets.json, sementara proyek yang sudah 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 contoh proyek 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 dan ARM_GNU_PATH variabel.

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 Visual Studio CMakePresets.json perubahan konfigurasi.

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

Contoh 20.01 SDK CMakeSettings.json file

{
  "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 menyertakan perubahan berikut:

Di bidang "lingkungan", hanya "Azure Sphere" yang diperlukan.
Dalam bidang "konfigurasi" untuk build Debug dan Rilis:
- Nilai "buildRoot" dan "installRoot" tidak lagi memerlukan pengaturan AzureSphereTargetApiSet.
- Toolchain CMake sekarang ditentukan dalam "cmakeToolChain", bukan dalam "variabel".
- Bidang "variabel" kini hanya menentukan kumpulan API target dan menggunakan nilai "latest-lts" baru untuk menunjukkan bahwa proyek harus dibuat 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 ini sekarang diatur dalam fileCMakeLists.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"
        }
      ]
    }
  ]
}

Visual Studio Code konfigurasi .vscode/settings.json

Contoh berikut ini memperlihatkan 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 20.01 File .vscode/settings.json 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"
}

File .vscode/settings.json yang diperbarui

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

File settings.json yang diperbarui menyertakan perubahan berikut ke bidang "cmake.configureSettings":

Pengaturan AZURE_SPHERE_TARGET_HARDWARE_DEFINITION_DIRECTORY dan AZURE_SPHERE_TARGET_HARDWARE_DEFINITION tidak lagi diperlukan, karena nilai ini sekarang diatur dalam file CMakeLists.txt .
Pengaturan CMAKE_TOOLCHAIN_FILE dan AZURE_SPHERE_TARGET_API_SET tidak lagi diperlukan, karena nilai ini sekarang diatur dalam file CMakePresets.json . Nilai AZURE_SPHERE_TARGET_API_SET sekarang "latest-lts", yang menunjukkan bahwa proyek harus dibuat 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 ini berlaku untuk ekstensi:

"cmake.configureOnOpen": true memberitahu ekstensi alat cmake 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 alat cmake .

{
    "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 akar, seperti sampel IntercoreComms, Anda perlu 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.

Bagikan melalui