Application Runtime-versie, sysroots en bèta-API's

Artikel
03/27/2024

Een Azure Sphere SDK-release kan zowel productie-API's als bèta-API's bevatten. Productie-API's worden beschouwd als langetermijn stabiel (LTS), terwijl bèta-API's nog in ontwikkeling zijn en kunnen veranderen in of worden verwijderd uit een latere release. In de meeste gevallen worden nieuwe API's in de eerste release gemarkeerd als Bèta en in een volgende release verplaatst naar productie. Bèta-API's bieden vroege toegang tot nieuwe functies, waardoor prototypen en feedback mogelijk zijn voordat ze zijn voltooid. Toepassingen die bèta-API's gebruiken, moeten over het algemeen worden gewijzigd na toekomstige versies van het Azure-besturingssysteem en de SDK om correct te blijven werken.

Bètafuncties worden in de documentatie aangeduid als BETA-functie . Elke Azure Sphere-toepassing op hoog niveau geeft aan of deze alleen is gericht op productie-API's of zowel productie- als bèta-API's.

Doel-API-sets, ARV en sysroots

De doel-API-set geeft aan welke API's de toepassing gebruikt: alleen productie-API's of productie- en bèta-API's. De waarde van de doel-API-set is een geheel getal dat de Application Runtime-versie (ARV) vertegenwoordigt of de ARV plus een tekenreeks die de bèta-API-release identificeert. Alleen de numerieke waarde geeft alleen de productie-API's in de ARV op, terwijl de 'value+BetaNumber' de productie- en bèta-API's in een bepaalde release aangeeft. ARV 8 geeft bijvoorbeeld de 21.01-release aan en '8+Beta2101' geeft de productie- en bèta-API's in de 20.01-release aan. In toekomstige versies worden extra AGV's toegevoegd.

De Azure Sphere SDK implementeert meerdere API-sets met behulp van sysroots. Een sysroot geeft de bibliotheken, headerbestanden en hulpprogramma's op die worden gebruikt voor het compileren en koppelen van een toepassing die is gericht op een bepaalde API-set. De sysroots worden geïnstalleerd in de map Microsoft Azure Sphere SDK in de submap sysroots.

De doel-API-set voor een app op hoog niveau instellen of bijwerken

Als u uw toepassing baseert op een Azure Sphere-voorbeeld, is de doel-API die standaard is ingesteld de API-set die in het voorbeeld wordt gebruikt. Als het voorbeeld alleen productie-API's gebruikt, wordt de doel-API-set ingesteld op de huidige ARV-waarde. Als in het voorbeeld zowel productie- als bèta-API's worden gebruikt voor de huidige release, is de doel-API-set 'value+BetaNumber' om de bèta-API's op te nemen.

Als u uw toepassing niet baseert op een voorbeeld, moet u de doel-API instellen die is ingesteld in de build-instructies voor de app.

Als u al een toepassing hebt gemaakt, moet u mogelijk de doel-API-set wijzigen als u de app opnieuw bouwt voor een nieuwe versie van het besturingssysteem. Als de app bèta-API's gebruikt, moet u deze bijwerken wanneer de opties voor de doel-API-set worden gewijzigd. Dit gebeurt meestal bij elke functierelease. Bèta-API's kunnen rechtstreeks van de bètastatus naar de productie worden verplaatst, wat resulteert in een nieuwe ARV, of ze kunnen worden gewijzigd en in bèta blijven. Als u een toepassing bijwerkt die gebruikmaakt van bèta-API's voor een recentere doel-API-set, kunnen er fouten of waarschuwingen optreden over verwijderde of buiten gebruik gestelde API's.

Telkens wanneer u de doel-API-set wijzigt, moet u het CMakeCache.txt-bestand verwijderen voordat u de toepassing bouwt. Dit bestand wordt opgeslagen in de map out\ARM-Debug of out\ARM-Release voor uw project.

Doel-API-set opgeven

Stel de doel-API-set in CMakePresets.json:

Gebruik 'AZURE_SPHERE_TARGET_API_SET' om de doel-API-set te configureren. Bijvoorbeeld:

"AZURE_SPHERE_TARGET_API_SET": "5" Of "AZURE_SPHERE_TARGET_API_SET": "5+Beta2004"

Als uw app is gericht op de nieuwste API-set, kunt u deze variabele gewoon instellen op 'latest-lts', als dit nog niet is gebeurd. Als uw app is gericht op de meest recente bèta-API-set, kunt u deze variabele gewoon instellen op 'latest-beta', als deze nog niet is ingesteld. Als uw app echter is gericht op een oudere API-set, moet u deze variabele zo instellen dat deze overeenkomt met de specifieke waarde die wordt gebruikt.

Als u de externe AZURE_SPHERE_TARGET_API_SET variabele in een Visual Studio-project wilt opgeven, stelt u het volgende in het CMakeSettings.json-bestand in, zowel in de ARM-Debug- als ARM-Release-configuraties:
```
"variables": [
  {
    "name": "AZURE_SPHERE_TARGET_API_SET",
    "value": "latest-beta"
  }
]
```
Als u de variabele externe AZURE_SPHERE_TARGET_API_SET in een Visual Studio Code-project wilt opgeven, stelt u het volgende in het bestand .vscode/settings.json in:
```
    "cmake.configureSettings": {
      "AZURE_SPHERE_TARGET_API_SET": "latest-lts"
  },
```
Als u de variabele externe AZURE_SPHERE_TARGET_API_SET op de opdrachtregel wilt opgeven, neemt u de parameter op bij het aanroepen van CMake:

-DAZURE_SPHERE_TARGET_API_SET="latest-lts"

Vervang 'latest-lts' door 'latest-beta' of een specifieke oudere waarde, zoals '4' of '5+Beta2004', zoals eerder is uitgelegd.

Doel-API-sets en compatibiliteit van het besturingssysteem

De compatibiliteit van een toepassing met het Azure Sphere-besturingssysteem is afhankelijk van de doel-API-set waarmee de toepassing is gebouwd en de meest recente ARV die de versie van het besturingssysteem ondersteunt. Een toepassing op lager niveau of besturingssysteem maakt gebruik van een oudere ARV (met een lager getal) en een toepassing op hoger niveau of besturingssysteem gebruikt een recentere ARV (met een hoger getal). In de volgende secties wordt beschreven wat u in elk mogelijk scenario kunt verwachten.

Toepassingen op lager niveau met een hoger besturingssysteem

Bestaande installatiekopieën op lager niveau die alleen productie-API's gebruiken, worden ondersteund in versies op hoger niveau van het Azure Sphere-besturingssysteem. Een toepassing die is gebouwd met doel-API-set 1 wordt bijvoorbeeld uitgevoerd op een Azure Sphere-besturingssysteem dat ARV 2 ondersteunt. Uw bestaande geïmplementeerde toepassingen blijven dus correct werken na updates van het cloudbesturingssysteem. U kunt installatiekopieën op een lager niveau zonder fouten sideloaden of in de cloud implementeren in een hoger besturingssysteem.

Installatiekopieën op lager niveau die gebruikmaken van bèta-API's worden niet ondersteund en werken mogelijk niet standaard op versies van het Azure Sphere-besturingssysteem. Een toepassing die is gebouwd met de doel-API-set 1+Beta1902 kan bijvoorbeeld niet worden uitgevoerd op een Azure Sphere-besturingssysteem met ARV 2. Pogingen om een dergelijke installatiekopieën te sideloaden, retourneren een fout, tenzij u de --force vlag op de opdracht az sphere device sideload deploy gebruikt . Op dezelfde manier vereist de opdracht az sphere image add de --force vlag om een dergelijke afbeelding te uploaden. Geen huidige controles verhinderen vervolgens dat een eerder geüploade installatiekopie op lager niveau die gebruikmaakt van bèta-API's, wordt geïmplementeerd naast een hoger besturingssysteem dat deze bèta-API's niet meer ondersteunt.

Toepassingen op het hoogste niveau met een lager besturingssysteem

Toepassingen op het hoogste niveau kunnen niet worden geïmplementeerd in lagere versies van het Azure Sphere-besturingssysteem, ongeacht of ze bèta-API's gebruiken. Pogingen om een dergelijke afbeelding te sideloaden, mislukken met een fout. Pogingen om over-the-air te implementeren zijn momenteel niet mogelijk omdat de SDK en het besturingssysteem op het hoogste niveau tegelijkertijd worden uitgebracht.