Versione del runtime dell'applicazione, sysroots e API Beta

Articolo
04/03/2024

Una versione di Azure Sphere SDK può contenere API di produzione e API Beta. Le API di produzione sono considerate stabili (LTS) a lungo termine, mentre le API beta sono ancora in fase di sviluppo e possono cambiare o essere rimosse da una versione successiva. Nella maggior parte dei casi, le nuove API sono contrassegnate come Beta nella loro prima versione e spostate in produzione in una versione successiva. Le API beta consentono di accedere in anteprima alle nuove funzionalità, abilitando la prototipazione e il feedback prima che vengano finalizzate. Per continuare a funzionare correttamente, le applicazioni che usano API Beta richiedono in genere modifiche dopo le versioni future del sistema operativo Azure e dell'SDK.

Le caratteristiche beta sono etichettate come funzionalità BETA nella documentazione. Ogni applicazione di alto livello Azure Sphere specifica se riguarda solo le API di produzione o sia le API di produzione che beta.

Set DI API di destinazione, ARV e sysroot

Il set di API di destinazione indica quali API vengono utilizzate dall'applicazione: solo API di produzione o API di produzione e Beta. Il valore del set di API di destinazione è un numero intero che rappresenta la versione di runtime dell'applicazione (ARV) o il valore ARV più una stringa che identifica la versione dell'API Beta. Solo il valore numerico specifica solo le API di produzione nell'ARV, mentre il "valore+BetaNumber" specifica le API di produzione e Beta in una determinata versione. Ad esempio, ARV 8 indica la versione 21.01 e "8+Beta2101" specifica le API di produzione e Beta nella versione 20.01. Nelle versioni future verranno aggiunti altri file ARV.

Azure Sphere SDK implementa più set di API tramite sysroots. Una sysroot specifica le librerie, i file di intestazione e gli strumenti usati per compilare e collegare un'applicazione destinata a un particolare set di API. Le sysroot sono installate nella directory Microsoft Azure Sphere SDK nella sottocartella sysroots.

Impostare o aggiornare l'API di destinazione impostata per un'app di alto livello

Se si basa l'applicazione su un esempio Azure Sphere, l'API di destinazione impostata per impostazione predefinita è l'API impostata dall'esempio. Se nell'esempio vengono utilizzate solo API di produzione, il set di API di destinazione verrà impostato sul valore ARV corrente. Se l'esempio usa api di produzione e beta per la versione corrente, il set di API di destinazione sarà "value+BetaNumber", per includere le API Beta.

Se non si basa l'applicazione su un esempio, è necessario impostare l'API di destinazione impostata nelle istruzioni di compilazione per l'app.

Se hai già creato un'applicazione, potrebbe essere necessario modificare il set di API di destinazione se ricompili l'app per una nuova versione del sistema operativo. Se l'app usa API beta, è consigliabile aggiornarle quando cambiano le opzioni del set di API di destinazione, che in genere si verifica in ogni versione delle funzionalità. Le API beta possono essere spostate direttamente dallo stato Beta alla produzione, creando un nuovo ARV, oppure possono essere modificate e rimanere nella versione Beta. Se si aggiorna un'applicazione che usa API beta per un set di API di destinazione più recente, potrebbero verificarsi errori o avvisi relativi alle API rimosse o ritirate.

Ogni volta che si modifica il set di API di destinazione, è necessario eliminare il file CMakeCache.txt prima di compilare l'applicazione. Questo file è archiviato nella directory out\ARM-Debug o out\ARM-Release del progetto.

Specificare il set di API di destinazione

Impostare l'API di destinazione impostata in CMakePresets.json:

Usare "AZURE_SPHERE_TARGET_API_SET" per configurare il set di API di destinazione. Per esempio:

"AZURE_SPHERE_TARGET_API_SET": "5" O "AZURE_SPHERE_TARGET_API_SET": "5+Beta2004"

Se l'app è destinata al set di API più recente, puoi semplicemente impostare questa variabile su "latest-lts", se non lo è già. Se l'app è destinata all'ultimo set di API Beta, puoi semplicemente impostare questa variabile su "latest-beta", se non lo è già. Tuttavia, se l'app è destinata a un set di API meno recente, è necessario impostare questa variabile in modo che corrisponda al valore specifico utilizzato.

Per specificare la variabile AZURE_SPHERE_TARGET_API_SET esterna in un progetto di Visual Studio, impostare quanto segue nel file di CMakeSettings.json, sia all'interno delle configurazioni ARM-Debug che ARM-Release:
```
"variables": [
  {
    "name": "AZURE_SPHERE_TARGET_API_SET",
    "value": "latest-beta"
  }
]
```
Per specificare la variabile AZURE_SPHERE_TARGET_API_SET esterna in un progetto Visual Studio Code, impostare quanto segue nel file con estensione vscode/settings.json:
```
    "cmake.configureSettings": {
      "AZURE_SPHERE_TARGET_API_SET": "latest-lts"
  },
```
Per specificare la variabile AZURE_SPHERE_TARGET_API_SET esterna nella riga di comando, includere il parametro quando si richiama CMake:

-DAZURE_SPHERE_TARGET_API_SET="latest-lts"

Sostituire "latest-lts" con "latest-beta" o un valore meno recente specifico, ad esempio "4" o "5+Beta2004", come spiegato in precedenza.

Set di API di destinazione e compatibilità del sistema operativo

La compatibilità di un'applicazione con il sistema operativo Azure Sphere dipende dal set di API di destinazione con cui è stata creata l'applicazione e dall'ultimo ARV supportato dalla versione del sistema operativo. Un'applicazione o un sistema operativo di livello inferiore usa un ARV precedente (che ha un numero inferiore) e un'applicazione di livello superiore o un sistema operativo usa un ARV più recente (che ha un numero più alto). Le sezioni seguenti descrivono cosa aspettarsi in ogni scenario possibile.

Applicazioni di livello inferiore con sistema operativo superiore

Le immagini esistenti di livello inferiore che usano solo API di produzione sono supportate nelle versioni di livello superiore del sistema operativo Azure Sphere. Ad esempio, un'applicazione creata con il set di API di destinazione 1 viene eseguita correttamente in un sistema operativo Azure Sphere che supporta ARV 2. In questo modo, le applicazioni distribuite esistenti continueranno a funzionare correttamente dopo gli aggiornamenti del sistema operativo cloud. È possibile eseguire il sideload o distribuire nel cloud immagini di livello inferiore solo di produzione in un sistema operativo di livello superiore senza errori.

Le immagini di livello inferiore che usano API Beta non sono supportate e potrebbero non funzionare da progettazione nelle versioni di livello superiore del sistema operativo Azure Sphere. Ad esempio, un'applicazione creata con l'API di destinazione impostata 1+Beta1902 potrebbe non funzionare in un sistema operativo Azure Sphere con ARV 2. I tentativi di sideload di un'immagine di questo tipo restituiscono un errore a meno che non usi il --force comando di distribuzione sideload della sfera az . Analogamente, il comando az sphere image add richiede che la --force bandiera carichi tale immagine. Nessun controllo corrente impedisce successivamente la distribuzione di un'immagine di livello inferiore precedentemente caricata che usa API Beta insieme a un sistema operativo di livello superiore che non supporta più tali API Beta.

Applicazioni di livello superiore con sistema operativo inferiore

Le applicazioni di livello superiore non possono essere distribuite nelle versioni di livello inferiore del sistema operativo Azure Sphere, indipendentemente dal fatto che usino o meno API Beta. I tentativi di sideload di un'immagine di questo tipo non riusciranno con un errore. I tentativi di distribuire in modalità aerea non sono attualmente possibili perché l'SDK di livello superiore e il sistema operativo vengono rilasciati contemporaneamente.