Versi runtime aplikasi, sysroot, dan API Beta

Artikel
04/03/2024

Rilis SDK Azure Sphere mungkin berisi API produksi dan API Beta. API produksi dianggap stabil jangka panjang (LTS), sedangkan API Beta masih dalam pengembangan dan dapat berubah atau dihapus dari rilis selanjutnya. Biasanya, API baru ditandai Beta dalam rilis pertamanya dan dipindahkan ke produksi dalam rilis berikutnya. API Beta menyediakan akses awal ke fitur baru, memungkinkan prototiping dan umpan balik sebelum difinalisasi. Aplikasi yang menggunakan API Beta umumnya memerlukan modifikasi setelah rilis Azure OS dan SDK di masa mendatang agar terus berfungsi dengan benar.

Fitur Beta diberi label fitur BETA dalam dokumentasi. Setiap aplikasi tingkat tinggi Azure Sphere menentukan apakah hanya menargetkan API produksi atau API produksi dan Beta.

Set API target, ARV, dan sysroot

Rangkaian API target menunjukkan API mana yang digunakan oleh aplikasi: API produksi saja atau produksi dan API Beta. Nilai set API target adalah bilangan bulat yang mewakili versi runtime aplikasi (ARV) atau ARV ditambah string yang mengidentifikasi rilis API Beta. Nilai numerik saja hanya menentukan API produksi di ARV, sedangkan "value+BetaNumber" menentukan produksi dan API Beta dalam rilis tertentu. Misalnya, ARV 8 menunjukkan rilis 21.01, dan "8+Beta2101" menentukan produksi dan API Beta dalam rilis 20.01. Rilis mendatang akan menambahkan ARV tambahan.

Azure Sphere SDK mengimplementasikan beberapa set API dengan menggunakan sysroot. A sysroot menentukan pustaka, file header, dan alat yang digunakan untuk mengkompilasi dan menautkan aplikasi yang menargetkan kumpulan API tertentu. Sysroots diinstal di direktori SDK Microsoft Azure Sphere di subfolder sysroots.

Mengatur atau memperbarui rangkaian API target untuk aplikasi tingkat tinggi

Jika Anda mendasarkan aplikasi Anda pada sampel Azure Sphere, API target yang ditetapkan secara default adalah kumpulan API yang digunakan sampel. Jika sampel hanya menggunakan API produksi, kumpulan API target akan diatur ke nilai ARV saat ini. Jika sampel menggunakan API produksi dan Beta untuk rilis saat ini, kumpulan API target akan berupa "value+BetaNumber", untuk menyertakan API Beta.

Jika tidak mendasarkan aplikasi pada sampel, Anda harus mengatur api target yang ditetapkan dalam instruksi build untuk aplikasi.

Jika sudah membuat aplikasi, Anda mungkin perlu mengubah kumpulan API target jika menyusun ulang aplikasi untuk rilis OS baru. Jika aplikasi menggunakan API Beta, Anda harus memperbaruinya saat opsi kumpulan API target berubah, yang biasanya terjadi pada setiap rilis fitur. API Beta dapat dipindahkan langsung dari status Beta ke produksi, menghasilkan ARV baru, atau mungkin diubah dan tetap berada di Beta. Jika Anda memperbarui aplikasi yang menggunakan API Beta untuk menargetkan kumpulan API target yang lebih baru, Anda mungkin mengalami kesalahan atau peringatan tentang API yang dihapus atau dihentikan.

Kapan saja Anda mengubah kumpulan API target, Anda perlu menghapus file CMakeCache.txt sebelum Anda membuat aplikasi. File ini disimpan di direktori out\ARM-Debug atau out\ARM-Release untuk proyek Anda.

Tentukan kumpulan API target

Tetapkan set API target di CMakePresets.json:

Gunakan "AZURE_SPHERE_TARGET_API_SET" untuk mengonfigurasi kumpulan API target. Misalnya:

"AZURE_SPHERE_TARGET_API_SET": "5" Atau "AZURE_SPHERE_TARGET_API_SET": "5+Beta2004"

Jika aplikasi menargetkan kumpulan API terbaru, Anda dapat mengatur variabel ini ke "latest-lts", jika belum. Jika aplikasi menargetkan kumpulan API Beta terbaru, Anda dapat mengatur variabel ini ke "latest-beta", jika belum. Namun, jika aplikasi menargetkan kumpulan API yang lebih lama, Anda perlu mengatur variabel ini agar sesuai dengan nilai tertentu yang digunakan.

Untuk menentukan variabel AZURE_SPHERE_TARGET_API_SET eksternal dalam proyek Visual Studio, atur hal berikut dalam file CMakeSettings.json, di dalam konfigurasi ARM-Debug dan ARM-Release:
```
"variables": [
  {
    "name": "AZURE_SPHERE_TARGET_API_SET",
    "value": "latest-beta"
  }
]
```
Untuk menentukan variabel AZURE_SPHERE_TARGET_API_SET eksternal dalam proyek Visual Studio Code, atur hal berikut dalam file .vscode/settings.json:
```
    "cmake.configureSettings": {
      "AZURE_SPHERE_TARGET_API_SET": "latest-lts"
  },
```
Untuk menentukan variabel AZURE_SPHERE_TARGET_API_SET eksternal pada baris perintah, sertakan parameter saat memanggil CMake:

-DAZURE_SPHERE_TARGET_API_SET="latest-lts"

Ganti "latest-lts" dengan "latest-beta" atau nilai lama tertentu seperti "4" atau "5+Beta2004" seperti yang dijelaskan sebelumnya.

Rangkaian API target dan kompatibilitas OS

Kompatibilitas aplikasi dengan AZURE Sphere OS bergantung pada rangkaian API target yang digunakan untuk membuat aplikasi dan ARV terbaru yang didukung versi OS. Aplikasi tingkat bawah atau OS menggunakan ARV yang lebih lama (yang memiliki angka lebih rendah), dan aplikasi tingkat atas atau OS menggunakan ARV yang lebih baru (yang memiliki angka lebih tinggi). Bagian berikut ini menjelaskan apa yang diharapkan dalam setiap skenario yang memungkinkan.

Aplikasi tingkat bawah dengan OS tingkat atas

Gambar tingkat bawah yang sudah ada yang hanya menggunakan API produksi didukung pada versi tingkat atas Azure Sphere OS. Misalnya, aplikasi yang dibuat dengan API Target Set 1 berhasil berjalan di Azure Sphere OS yang mendukung ARV 2. Dengan demikian, aplikasi yang sudah digunakan akan terus beroperasi dengan benar setelah pembaruan OS cloud. Anda dapat menggunakan sideload atau cloud-deploy down-level, gambar produksi saja ke OS tingkat atas tanpa kesalahan.

Gambar tingkat bawah yang menggunakan API Beta tidak didukung, dan mungkin tidak berfungsi secara desain, pada versi tingkat atas Azure Sphere OS. Misalnya, aplikasi yang dibuat dengan API target Set 1+Beta1902 mungkin gagal dijalankan pada OS Azure Sphere yang memiliki ARV 2. Mencoba untuk memuat sisi seperti gambar mengembalikan kesalahan kecuali Anda menggunakan --force bendera pada perintah penyebaran sideload perangkat bola az . Demikian pula, perintah tambahkan gambar bola az memerlukan bendera untuk mengunggah gambar seperti itu --force . Tidak ada pemeriksaan saat ini yang kemudian mencegah gambar tingkat bawah yang diunggah sebelumnya yang menggunakan API Beta agar tidak digunakan bersama OS tingkat atas yang tidak lagi mendukung API Beta tersebut.

Aplikasi tingkat atas dengan OS tingkat bawah

Aplikasi tingkat atas tidak dapat digunakan ke versi tingkat bawah Azure Sphere OS, terlepas apakah mereka menggunakan API Beta. Upaya untuk memuat sisi seperti gambar akan gagal dengan kesalahan. Upaya untuk menyebarkan over-the-air saat ini tidak dimungkinkan karena SDK dan OS tingkat atas dirilis secara bersamaan.

Bagikan melalui