Anwendungsruntimeversion, Sysroots und Beta-APIs

Artikel
04/03/2024

Ein Azure Sphere SDK-Release kann sowohl Produktions-APIs als auch Beta-APIs enthalten. Produktions-APIs gelten als long-term stable (LTS), während Beta-APIs sich noch in der Entwicklung befinden und sich in einem späteren Release ändern oder daraus entfernt werden können. In den meisten Fällen werden neue APIs in ihrem ersten Release als Beta markiert und in einem nachfolgenden Release in die Produktion verschoben. Beta-APIs bieten frühzeitigen Zugriff auf neue Features und ermöglichen Prototypenerstellung und Feedback, bevor sie abgeschlossen sind. Anwendungen, die Beta-APIs verwenden, erfordern in der Regel Änderungen nach zukünftigen Azure-Betriebssystem- und SDK-Releases, damit sie weiterhin ordnungsgemäß funktionieren.

Betafeatures werden in der Dokumentation als BETA-Feature bezeichnet. Jede allgemeine Azure Sphere-Anwendung gibt an, ob sie nur auf Produktions-APIs oder sowohl Produktions- als auch Beta-APIs abzielt.

Ziel-API-Sätze, ARV und Sysroots

Der Ziel-API-Satz gibt an, welche APIs die Anwendung verwendet: entweder nur Produktions-APIs oder Produktions- und Beta-APIs. Der Ziel-API-Satzwert ist entweder eine ganze Zahl, die die Anwendungsruntimeversion (ARV) darstellt, oder die ARV sowie eine Zeichenfolge, die das Beta-API-Release identifiziert. Der numerische Wert allein gibt nur die Produktions-APIs in der ARV an, während "value+BetaNumber" die Produktions- und Beta-APIs in einem bestimmten Release angibt. Arv 8 gibt beispielsweise das Release 21.01 an, und "8+Beta2101" gibt die Produktions- und Beta-APIs im Release 20.01 an. In zukünftigen Versionen werden zusätzliche ARVs hinzugefügt.

Das Azure Sphere SDK implementiert mehrere API-Sätze mithilfe von sysroots. Sysroot gibt die Bibliotheken, Headerdateien und Tools an, die zum Kompilieren und Verknüpfen einer Anwendung verwendet werden, die auf einen bestimmten API-Satz ausgerichtet ist. Die sysroots werden im Verzeichnis des Microsoft Azure Sphere SDK im Unterordner sysroots installiert.

Festlegen oder Aktualisieren des ZIEL-API-Satzes für eine allgemeine App

Wenn Sie Ihre Anwendung auf einem Azure Sphere-Beispiel basieren, ist der Ziel-API-Satz standardmäßig der API-Satz, den das Beispiel verwendet. Wenn im Beispiel nur Produktions-APIs verwendet werden, wird der Ziel-API-Satz auf den aktuellen ARV-Wert festgelegt. Wenn im Beispiel sowohl Produktions- als auch Beta-APIs für das aktuelle Release verwendet werden, lautet der ZIEL-API-Satz "value+BetaNumber", um die Beta-APIs einzuschließen.

Wenn Sie Ihre Anwendung nicht auf einem Beispiel basieren, müssen Sie den Ziel-API-Satz in den Buildanweisungen für die App festlegen.

Wenn Sie bereits eine Anwendung erstellt haben, müssen Sie möglicherweise den ZIEL-API-Satz ändern, wenn Sie die App für ein neues Betriebssystemrelease neu erstellen. Wenn die App Beta-APIs verwendet, sollten Sie sie aktualisieren, wenn sich die Ziel-API-Set-Optionen ändern, was in der Regel bei jedem Featurerelease auftritt. Beta-APIs können direkt aus beta status in die Produktion verschoben werden, was zu einer neuen ARV führt, oder sie werden geändert und verbleiben in der Betaversion. Wenn Sie eine Anwendung aktualisieren, die Beta-APIs verwendet, um auf einen neueren Ziel-API-Satz zu abzielen, können Fehler oder Warnungen zu entfernten oder eingestellten APIs auftreten.

Jedes Mal, wenn Sie den ZIEL-API-Satz ändern, müssen Sie die CMakeCache.txt-Datei löschen, bevor Sie die Anwendung erstellen. Diese Datei wird im Verzeichnis out\ARM-Debug oder out\ARM-Release für Ihr Projekt gespeichert.

Angeben des Ziel-API-Satzes

Legen Sie den Ziel-API-Satz in CMakePresets.json fest:

Verwenden Sie "AZURE_SPHERE_TARGET_API_SET", um den ZIEL-API-Satz zu konfigurieren. Zum Beispiel:

"AZURE_SPHERE_TARGET_API_SET": "5" Oder "AZURE_SPHERE_TARGET_API_SET": "5+Beta2004"

Wenn Ihre App auf den neuesten API-Satz ausgerichtet ist, können Sie diese Variable einfach auf "latest-lts" festlegen, sofern dies noch nicht der Fall ist. Wenn Ihre App auf den neuesten Beta-API-Satz ausgerichtet ist, können Sie diese Variable einfach auf "latest-beta" festlegen, sofern dies noch nicht der Fall ist. Wenn Ihre App jedoch auf einen älteren API-Satz abzielt, müssen Sie diese Variable so festlegen, dass sie mit dem spezifischen Wert übereinstimmt, den sie verwendet.

Um die externe AZURE_SPHERE_TARGET_API_SET Variable in einem Visual Studio-Projekt anzugeben, legen Sie in der CMakeSettings.json-Datei sowohl in der ARM-Debug- als auch in ARM-Release-Konfiguration Folgendes fest:
```
"variables": [
  {
    "name": "AZURE_SPHERE_TARGET_API_SET",
    "value": "latest-beta"
  }
]
```
Um die externe AZURE_SPHERE_TARGET_API_SET Variable in einem Visual Studio Code-Projekt anzugeben, legen Sie Folgendes in der Datei .vscode/settings.json fest:
```
    "cmake.configureSettings": {
      "AZURE_SPHERE_TARGET_API_SET": "latest-lts"
  },
```
Um die externe AZURE_SPHERE_TARGET_API_SET Variable in der Befehlszeile anzugeben, schließen Sie beim Aufrufen von CMake den Parameter ein:

-DAZURE_SPHERE_TARGET_API_SET="latest-lts"

Ersetzen Sie "latest-lts" durch "latest-beta" oder einen bestimmten älteren Wert wie "4" oder "5+Beta2004", wie zuvor erläutert.

Ziel-API-Sätze und Betriebssystemkompatibilität

Die Kompatibilität einer Anwendung mit dem Azure Sphere-Betriebssystem hängt von der Ziel-API-Gruppe ab, mit der die Anwendung erstellt wurde, und der neuesten ARV, die von der Betriebssystemversion unterstützt wird. Eine down-level-Anwendung oder ein Betriebssystem verwendet eine ältere ARV (die eine niedrigere Zahl aufweist), und eine up-Level-Anwendung oder ein Betriebssystem verwendet eine neuere ARV (die eine höhere Zahl aufweist). In den folgenden Abschnitten wird beschrieben, was in den einzelnen möglichen Szenarien zu erwarten ist.

Down-Level-Anwendungen mit up-level-Betriebssystem

Vorhandene down-Level-Images, die nur Produktions-APIs verwenden, werden in up-level-Versionen des Azure Sphere-Betriebssystems unterstützt. Beispielsweise wird eine Anwendung, die mit API-Zielsatz 1 erstellt wurde, erfolgreich auf einem Azure Sphere-Betriebssystem ausgeführt, das ARV 2 unterstützt. Daher funktionieren Ihre vorhandenen bereitgestellten Anwendungen nach Updates des Cloudbetriebssystems weiterhin ordnungsgemäß. Sie können Images, die nur auf produktionsbasierter Ebene erstellt werden, entweder querladen oder in der Cloud auf ein up-level-Betriebssystem ohne Fehler bereitstellen.

Down-Level-Images, die Beta-APIs verwenden, werden in höheren Versionen des Azure Sphere-Betriebssystems nicht unterstützt und funktionieren möglicherweise nicht entwurfsbedingt. Beispielsweise kann eine Anwendung, die mit dem API-Zielsatz 1+Beta1902 erstellt wurde, unter einem Azure Sphere-Betriebssystem mit ARV 2 nicht ausgeführt werden. Versuche, ein solches Image querzuladen, geben einen Fehler zurück, es sei denn, Sie verwenden das --force Flag im Befehl az sphere device sideload deploy . Ebenso erfordert der Befehl az sphere image add das --force Flag, um ein solches Bild hochzuladen. Keine aktuellen Überprüfungen verhindern anschließend, dass ein zuvor hochgeladenes down-Level-Image, das Beta-APIs verwendet, zusammen mit einem übergeordneten Betriebssystem bereitgestellt wird, das diese Beta-APIs nicht mehr unterstützt.

Up-Level-Anwendungen mit down-Level-Betriebssystem

Anwendungen auf höherer Ebene können nicht in downen Versionen des Azure Sphere-Betriebssystems bereitgestellt werden, unabhängig davon, ob sie Beta-APIs verwenden. Versuche, ein solches Image querzuladen, schlagen mit einem Fehler fehl. Over-the-Air-Bereitstellungsversuche sind derzeit nicht möglich, da das up-Level-SDK und das Betriebssystem gleichzeitig veröffentlicht werden.