Version du runtime d’application, sysroots et API bêta

Article
04/03/2024

Une version du Kit de développement logiciel (SDK) Azure Sphere peut contenir à la fois des API de production et des API bêta. Les API de production sont considérées comme stables à long terme (LTS), tandis que les API bêta sont toujours en cours de développement et peuvent changer ou être supprimées d’une version ultérieure. Dans la plupart des cas, les nouvelles API sont marquées bêta dans leur première version et déplacées en production dans une version ultérieure. Les API bêta fournissent un accès en avant-première aux nouvelles fonctionnalités, ce qui permet le prototypage et les commentaires avant qu’elles ne soient finalisées. Les applications qui utilisent des API bêta nécessitent généralement des modifications après les futures versions du système d’exploitation et du KIT de développement logiciel (SDK) Azure pour continuer à fonctionner correctement.

Les fonctionnalités bêta sont étiquetées Fonctionnalité BÊTA dans la documentation. Chaque application de haut niveau Azure Sphere spécifie si elle cible uniquement les API de production ou les API de production et bêta.

Ensembles d’API cibles, ARV et sysroots

L’ensemble d’API cible indique les API utilisées par l’application : API de production uniquement ou API de production et bêta. La valeur de l’ensemble d’API cible est un entier qui représente la version du runtime d’application (ARV) ou l’ARV plus une chaîne qui identifie la version de l’API bêta. La valeur numérique seule spécifie uniquement les API de production dans l’ARV, tandis que « value+BetaNumber » spécifie les API de production et bêta dans une version particulière. Par exemple, ARV 8 indique la version 21.01 et « 8+Beta2101 » spécifie les API de production et bêta dans la version 20.01. Les versions ultérieures ajouteront des ARV supplémentaires.

Le Kit de développement logiciel (SDK) Azure Sphere implémente plusieurs ensembles d’API à l’aide de sysroots. Un sysroot spécifie les bibliothèques, les fichiers d’en-tête et les outils utilisés pour compiler et lier une application qui cible un jeu d’API particulier. Les sysroots sont installés dans le répertoire du Kit de développement logiciel (SDK) Microsoft Azure Sphere, dans le sous-dossier sysroots.

Définir ou mettre à jour l’ensemble d’API cible pour une application de haut niveau

Si vous basez votre application sur un exemple Azure Sphere, l’ENSEMBLE d’API cible par défaut est l’ensemble d’API utilisé par l’exemple. Si l’exemple utilise uniquement des API de production, l’ensemble d’API cible est défini sur la valeur ARV actuelle. Si l’exemple utilise à la fois les API de production et bêta pour la version actuelle, l’ensemble d’API cible est « value+BetaNumber » pour inclure les API bêta.

Si vous ne basez pas votre application sur un exemple, vous devez définir l’ensemble d’API cible dans les instructions de génération de l’application.

Si vous avez déjà créé une application, vous devrez peut-être modifier l’ensemble d’API cible si vous régénérez l’application pour une nouvelle version du système d’exploitation. Si l’application utilise des API bêta, vous devez la mettre à jour lorsque les options du jeu d’API cible changent, ce qui se produit généralement à chaque version de fonctionnalité. Les API bêta peuvent être déplacées directement de la version bêta status vers la production, ce qui entraîne un nouvel ARV, ou elles peuvent être modifiées et rester en version bêta. Si vous mettez à jour une application qui utilise des API bêta pour cibler un ensemble d’API cible plus récent, vous pouvez rencontrer des erreurs ou des avertissements concernant les API supprimées ou mises hors service.

Chaque fois que vous modifiez l’ensemble d’API cible, vous devez supprimer le fichier CMakeCache.txt avant de générer l’application. Ce fichier est stocké dans le répertoire out\ARM-Debug ou out\ARM-Release pour votre projet.

Spécifier l’ensemble d’API cible

Définissez l’ensemble d’API cible dans CMakePresets.json :

Utilisez « AZURE_SPHERE_TARGET_API_SET » pour configurer l’ensemble d’API cible. Par exemple :

"AZURE_SPHERE_TARGET_API_SET": "5" Ou "AZURE_SPHERE_TARGET_API_SET": "5+Beta2004"

Si votre application cible le dernier ensemble d’API, vous pouvez simplement définir cette variable sur « latest-lts », si ce n’est pas déjà fait. Si votre application cible le dernier ensemble d’API bêta, vous pouvez simplement définir cette variable sur « latest-beta », si ce n’est pas déjà fait. Toutefois, si votre application cible un jeu d’API plus ancien, vous devez définir cette variable pour qu’elle corresponde à la valeur spécifique qu’elle utilise.

Pour spécifier la variable de AZURE_SPHERE_TARGET_API_SET externe dans un projet Visual Studio, définissez la valeur suivante dans le fichier CMakeSettings.json, dans les configurations ARM-Debug et ARM-Release :
```
"variables": [
  {
    "name": "AZURE_SPHERE_TARGET_API_SET",
    "value": "latest-beta"
  }
]
```
Pour spécifier la variable AZURE_SPHERE_TARGET_API_SET externe dans un projet Visual Studio Code, définissez ce qui suit dans le fichier .vscode/settings.json :
```
    "cmake.configureSettings": {
      "AZURE_SPHERE_TARGET_API_SET": "latest-lts"
  },
```
Pour spécifier la variable de AZURE_SPHERE_TARGET_API_SET externe sur la ligne de commande, incluez le paramètre lors de l’appel de CMake :

-DAZURE_SPHERE_TARGET_API_SET="latest-lts"

Remplacez « latest-lts » par « latest-beta » ou une ancienne valeur spécifique telle que « 4 » ou « 5+Beta2004 », comme expliqué précédemment.

Ensembles d’API cibles et compatibilité du système d’exploitation

La compatibilité d’une application avec le système d’exploitation Azure Sphere dépend de l’ensemble d’API cible avec lequel l’application a été générée et du dernier ARV pris en charge par la version du système d’exploitation. Une application de bas niveau ou un système d’exploitation utilise un ARV plus ancien (qui a un nombre inférieur), et une application de niveau supérieur ou un système d’exploitation utilise un ARV plus récent (qui a un nombre plus élevé). Les sections suivantes décrivent ce à quoi s’attendre dans chaque scénario possible.

Applications de bas niveau avec système d’exploitation de niveau supérieur

Les images de bas niveau existantes qui utilisent uniquement les API de production sont prises en charge sur les versions de niveau supérieur du système d’exploitation Azure Sphere. Par exemple, une application créée avec l’ensemble d’API cible 1 s’exécute correctement sur un système d’exploitation Azure Sphere qui prend en charge ARV 2. Ainsi, vos applications déployées existantes continueront à fonctionner correctement après les mises à jour du système d’exploitation cloud. Vous pouvez charger une version test ou déployer dans le cloud des images de bas niveau et de production uniquement vers un système d’exploitation de niveau supérieur sans erreur.

Les images de bas niveau qui utilisent des API bêta ne sont pas prises en charge et peuvent ne pas fonctionner par conception sur les versions de niveau supérieur du système d’exploitation Azure Sphere. Par exemple, une application qui a été créée avec l’ensemble d’API cible 1+Beta1902 peut échouer à s’exécuter sur un système d’exploitation Azure Sphere avec ARV 2. Les tentatives de chargement indépendant d’une telle image retournent une erreur, sauf si vous utilisez l’indicateur --force sur la commande az sphere device sideload deploy . De même, la commande az sphere image add nécessite l’indicateur --force pour charger une telle image. Aucune vérification actuelle n’empêche par la suite le déploiement d’une image de bas niveau précédemment chargée qui utilise des API bêta avec un système d’exploitation de niveau supérieur qui ne prend plus en charge ces API bêta.

Applications de niveau supérieur avec système d’exploitation de bas niveau

Les applications de haut niveau ne peuvent pas être déployées sur des versions de bas niveau du système d’exploitation Azure Sphere, qu’elles utilisent ou non des API bêta. Les tentatives de chargement indépendant d’une telle image échouent avec une erreur. Les tentatives de déploiement ota sont actuellement impossibles, car le KIT de développement logiciel (SDK) et le système d’exploitation de niveau supérieur sont publiés simultanément.