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

Les versions du SDK Azure Sphere peuvent contenir des API bêta et des API de production. Les API de production sont considérées comme étant stables à long terme (LTS), alors que les API bêta sont encore en phase de développement et sont susceptibles d’être modifiées ou supprimées dans une version ultérieure. Dans la plupart des cas, les nouvelles API sont désignées comme API bêta dans leur première version et sont appelées API de production dans les versions ultérieures. Les API bêta fournissent un accès en avant-première aux nouvelles fonctionnalités, permettant ainsi le prototypage et les commentaires avant qu’elles soient finalisées. Les applications qui utilisent des API bêta nécessitent souvent des changements après la mise à disposition de nouvelles versions du système d’exploitation et du SDK Azure pour continuer à fonctionner correctement.

Les fonctionnalités bêta sont étiquetées fonctionnalité BÊTA dans la documentation. Chaque application générale Azure Sphere spécifie si elle cible uniquement des API de production ou à la fois des API bêta et de production.

Ensembles d’API cibles, ARV et sysroots

L’ensemble d’API cibles indique quelles API sont utilisées par l’application : des API de production uniquement ou à la fois des API bêta et de production. La valeur définissant l’ensemble d’API cibles est un entier représentant la version du runtime d’application (ARV) ou bien l’ARV et une chaîne qui identifient la version de l’API bêta. La valeur numérique seule spécifie uniquement les API de production dans l’ARV, tandis que la valeur « 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. D’autres ARV seront ajoutés dans des versions futures.

Le 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 qui sont utilisés pour compiler et lier une application qui cible un ensemble particulier d’API. Les sysroots sont installés dans le répertoire du SDK Microsoft Azure Sphere dans le sous-dossier sysroots.

Définir ou mettre à jour l’ensemble d’API cibles pour une application générale

Si vous basez votre application sur un exemple Azure Sphere, l’API cible définie 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 cibles est défini sur la valeur ARV actuelle. Si l’exemple utilise à la fois des API de production et des API bêta pour la version actuelle, l’ensemble d’API cibles 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 cibles dans les instructions de génération de l’application.

Si vous avez déjà créé une application et que vous la regénérez pour une nouvelle version du système d’exploitation, vous devrez peut-être changer l’ensemble d’API cibles. Si l’application utilise les API bêta, vous devez la mettre à jour quand les options de l’ensemble d’API cibles évoluent, ce qui intervient généralement à chaque publication de fonctionnalités. Les API bêta peuvent être directement transférées de l'état bêta à l'état de production, ce qui se traduit par une nouvelle version du runtime d'application, ou rester à l'état 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 supprimées.

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

Spécifier l’ensemble d’API cibles

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. En revanche, si votre application cible un ensemble d’API d’une version antérieure, vous devez définir cette variable sur la valeur spécifique qu’elle utilise.

• Pour spécifier la variable AZURE_SPHERE_TARGET_API_SET externe dans un projet Visual Studio, définissez les éléments suivants dans le fichier CMakeSettings.json, à la fois 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 les éléments suivants dans le fichier .vscode/settings.json :

      "cmake.configureSettings": {
        "AZURE_SPHERE_TARGET_API_SET": "latest-lts"
    },
  

• Pour spécifier la variable 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 valeur antérieure particulière telle que « 4 » ou « 5+Beta2004 », comme expliqué précédemment.

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

La compatibilité d’une application avec le système d’exploitation Azure Sphere dépend de l'ensemble d'API cibles avec lequel l’application a été générée et de la dernière version du runtime d'application que la version du système d’exploitation prend en charge. Une application ou un système d'exploitation de niveau inférieur utilise une ancienne version du runtime d'application (portant un numéro moins élevé) et une application ou un système d'exploitation de niveau supérieur utilise une version du runtime d'application plus récente (portant un numéro plus élevé). Les sections suivantes expliquent à quoi s'attendre dans chaque scénario possible.

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

Les images de niveau inférieur existantes utilisant exclusivement des 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 qui a été générée avec l’ensemble d’API cibles 1 s’exécute correctement sur un système d’exploitation Azure Sphere prenant en charge ARV 2. Ainsi, vos applications déployées existantes continuent de fonctionner correctement après les mises à jour du système d’exploitation cloud. Vous pouvez effectuer un chargement indépendant (sideloading) ou un déploiement cloud des images de production de niveau inférieur vers un système d’exploitation de niveau supérieur sans erreur.

Les images de niveau inférieur existantes utilisant exclusivement des API bêta ne sont pas prises en charge et peuvent ne pas fonctionner de par leur conception sur les versions de niveau supérieur du système d’exploitation Azure Sphere. Par exemple, une application qui a été générée avec l’ensemble d’API cibles 1+Beta1902 peut ne pas 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 azsphere device sideload deploy. De même, la commande azsphere image add exige que l’indicateur --force charge une telle image. Aucune vérification actuelle n’empêche ensuite le déploiement d'une image de niveau inférieur précédemment chargée et utilisant les API bêta d'être en même temps qu'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 niveau inférieur

Les applications de niveau supérieur ne peuvent pas être déployées sur des versions de niveau inférieur du système d'exploitation Azure Sphere, qu'elles utilisent ou non des API bêta. Les tentatives visant à charger indépendamment une telle image échoue avec une erreur. Les tentatives de déploiement OTA ne sont actuellement pas possibles car le kit de développement logiciel (SDK) et le système d'exploitation de niveau supérieur sont publiés simultanément.