Versi runtime aplikasi, sysroots, dan API Beta

Artikel
09/27/2024

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

Rilis Azure Sphere SDK 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. Dalam kebanyakan kasus, API baru ditandai Beta dalam rilis pertama mereka dan dipindahkan ke produksi dalam rilis berikutnya. API Beta menyediakan akses awal ke fitur baru, memungkinkan prototipe dan umpan balik sebelum diselesaikan. Aplikasi yang menggunakan API Beta umumnya akan memerlukan modifikasi setelah rilis Azure OS dan SDK di masa mendatang untuk 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 sysroots

Set API target menunjukkan API mana yang digunakan aplikasi: baik 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. Sysroot menentukan pustaka, file header, dan alat yang digunakan untuk mengkompilasi dan menautkan aplikasi yang menargetkan set API tertentu. Sysroot diinstal di direktori Microsoft Azure Sphere SDK di subfolder sysroots.

Mengatur atau memperbarui API target yang ditetapkan untuk aplikasi tingkat tinggi

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

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

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

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

Tentukan set API target

Tetapkan API target yang ditetapkan di CMakePresets.json:

Gunakan "AZURE_SPHERE_TARGET_API_SET" untuk mengonfigurasi set API target. Contohnya:

"AZURE_SPHERE_TARGET_API_SET": "5" atau "AZURE_SPHERE_TARGET_API_SET": "5+Beta2004"

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

Untuk menentukan variabel AZURE_SPHERE_TARGET_API_SET eksternal dalam proyek Visual Studio, atur yang berikut ini dalam file CMakeSettings.json, 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 yang berikut ini 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.

Set API target dan kompatibilitas OS

Kompatibilitas aplikasi dengan OS Azure Sphere bergantung pada api target yang ditetapkan aplikasi yang dibuat dan ARV terbaru yang didukung versi OS. Aplikasi atau OS tingkat bawah 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 menjelaskan apa yang diharapkan dalam setiap skenario yang mungkin.

Aplikasi tingkat bawah dengan OS tingkat atas

Gambar tingkat bawah yang ada yang hanya menggunakan API produksi yang didukung pada versi tingkat atas Azure Sphere OS. Misalnya, aplikasi yang dibangun dengan API Set 1 target berhasil berjalan pada OS Azure Sphere yang mendukung ARV 2. Dengan demikian, aplikasi yang Anda sebarkan akan terus beroperasi dengan baik setelah pembaruan OS cloud. Anda dapat melakukan sideload atau cloud-deploy gambar tingkat bawah, khusus produksi ke OS tingkat atas tanpa kesalahan.

Gambar tingkat bawah yang menggunakan API Beta tidak didukung, dan mungkin tidak berfungsi berdasarkan desain, pada versi tingkat atas Os Azure Sphere. Misalnya, aplikasi yang dibangun dengan API Set target 1+Beta1902 mungkin gagal berjalan pada OS Azure Sphere yang memiliki ARV 2. Mencoba untuk membungkus gambar seperti itu mengembalikan kesalahan kecuali Anda menggunakan --force bendera pada perintah penyebaran sideload perangkat azsphere. Demikian pula, perintah azsphere image add memerlukan --force bendera untuk mengunggah gambar tersebut. Tidak ada pemeriksaan saat ini yang kemudian mencegah gambar tingkat bawah yang diunggah sebelumnya yang menggunakan API Beta agar tidak disebarkan bersama OS tingkat atas yang tidak lagi mendukung API Beta tersebut.

Aplikasi tingkat atas dengan OS tingkat bawah

Aplikasi tingkat atas tidak dapat disebarkan ke versi tingkat bawah OS Azure Sphere, terlepas dari apakah mereka menggunakan API Beta. Upaya untuk melakukan sideload gambar seperti itu 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