Versión del entorno de ejecución de la aplicación, sysroots y API Beta

Artículo
11/05/2024

Importante

Esta es la documentación de Azure Sphere (heredado). Azure Sphere (heredado) se retira el 27 de septiembre de 2027 y los usuarios deben migrar a Azure Sphere (integrado) en este momento. Use el selector de versiones situado encima de la TOC para ver la documentación de Azure Sphere (integrado).

Una versión de Azure Sphere SDK puede contener API de producción y API Beta. Las API de producción se consideran estables a largo plazo (LTS), mientras que las API Beta todavía están en desarrollo y pueden cambiar o quitarse de una versión posterior. En la mayoría de los casos, las nuevas API se marcan como Beta en su primera versión y se mueven a producción en una versión posterior. Las API Beta proporcionan acceso anticipado a las nuevas características, lo que permite la creación de prototipos y comentarios antes de su finalización. Las aplicaciones que usan las API Beta por lo general requerirán modificaciones después de futuras versiones del sistema operativo de Azure y del SDK para seguir funcionando correctamente.

Las características beta se etiquetan con la característica BETA en la documentación. Todas las aplicaciones de alto nivel de Azure Sphere especifican si tienen como destino solo las API de producción o las API de producción y las Beta.

Conjuntos de API de destino, versión del entorno en tiempo de ejecución de la aplicación y sysroots

El conjunto de API de destino indica qué API usa la aplicación: solo las API de producción o las API de producción y las Beta. El valor del conjunto de API de destino puede ser un entero que representa la versión del entorno en tiempo de ejecución de la aplicación o esta versión más una cadena que identifica la versión de la API Beta. El valor numérico por sí solo especifica únicamente las API de producción en la versión del entorno en tiempo de ejecución, mientras que "valor+número de beta" especifica las API de producción y beta en una versión determinada. Por ejemplo, ARV 8 indica la versión 21.01 y "8+Beta2101" especifica las API de producción y beta en la versión 20.01. En las versiones futuras se agregarán versiones del entorno en tiempo de ejecución de la aplicación adicionales.

Azure Sphere SDK implementa varios conjuntos de API mediante el uso de sysroots. Un sysroot especifica las bibliotecas, los archivos de encabezado y las herramientas que se usan para compilar y vincular una aplicación destinada a un conjunto de API determinado. Los sysroots se instalan en el directorio de Microsoft Azure Sphere SDK, en la subcarpeta sysroots.

Establecimiento o actualización del conjunto de API de destino para una aplicación de alto nivel

Si la aplicación se basa en un ejemplo de Azure Sphere, la API de destino establecida de forma predeterminada es el conjunto de API que utiliza el ejemplo. Si el ejemplo solo usa las API de producción, el conjunto de API de destino se establecerá en el valor de ARV actual. Si en el ejemplo se usan las API de producción y beta para la versión actual, el conjunto de API de destino será "Valor+Número_de_Beta" para incluir las API de la versión beta.

Si la aplicación no se basa en un ejemplo, deberá establecer el conjunto de API de destino en las instrucciones de compilación de la aplicación.

Si ya ha creado una aplicación, es posible que deba cambiar el conjunto de API de destino si vuelve a compilar la aplicación para una nueva versión del sistema operativo. Si la aplicación usa las API Beta, debe actualizarla cuando cambien las opciones de configuración de la API de destino, lo que suele ocurrir con cada lanzamiento de características. Las API Beta pueden pasar directamente desde el estado Beta a producción, lo que resulta en una nueva versión del entorno en tiempo de ejecución, o podrían cambiarse y permanecer en Beta. Si actualiza una aplicación que usa api beta para tener como destino un conjunto de API de destino más reciente, puede encontrar errores o advertencias sobre las API eliminadas o retiradas.

Siempre que cambie el conjunto de API de destino, deberá eliminar el archivo CMakeCache.txt antes de compilar la aplicación. Este archivo se almacena en el directorio out\ARM-Debug u out\ARM-Release del proyecto.

Especificación de un conjunto de API de destino

Establezca el conjunto de API de destino en CMakePresets.json:

Use "AZURE_SPHERE_TARGET_API_SET" para configurar el conjunto de API de destino. Por ejemplo:

"AZURE_SPHERE_TARGET_API_SET": "5" o "AZURE_SPHERE_TARGET_API_SET": "5+Beta2004"

Si la aplicación tiene como destino el conjunto de API más reciente, simplemente puede establecer esta variable en "latest-lts", si aún no lo está. Si la aplicación tiene como destino el conjunto de API beta más reciente, puedes establecer esta variable en "latest-beta", si aún no lo está. Sin embargo, si la aplicación tiene como destino un conjunto de API anterior, debe establecer esta variable para que coincida con el valor específico que utiliza.

Para especificar la variable AZURE_SPHERE_TARGET_API_SET externa en un proyecto de Visual Studio, configure lo siguiente en el archivo CMakeSettings.json, en los valores ARM-Debug y ARM-Release:
```
"variables": [
  {
    "name": "AZURE_SPHERE_TARGET_API_SET",
    "value": "latest-beta"
  }
]
```
Para especificar la variable AZURE_SPHERE_TARGET_API_SET externa en un proyecto de Visual Studio Code, configure lo siguiente en el archivo .vscode/settings.json:
```
    "cmake.configureSettings": {
      "AZURE_SPHERE_TARGET_API_SET": "latest-lts"
  },
```
Para especificar la variable AZURE_SPHERE_TARGET_API_SET externa en la línea de comandos, incluya el parámetro al invocar CMake:

-DAZURE_SPHERE_TARGET_API_SET="latest-lts"

Reemplace "latest-lts" por "latest-beta" o un valor anterior específico, como "4" o "5+Beta2004", tal como se ha explicado anteriormente.

Conjuntos de API de destino y compatibilidad del sistema operativo

La compatibilidad de una aplicación con el sistema operativo de Azure Sphere depende del conjunto de la API de destino en que se compiló la aplicación y la versión del entorno en tiempo de ejecución de la aplicación más reciente que admite el SO. Una aplicación o un sistema operativo de nivel inferior utiliza una versión del entorno en tiempo de ejecución de la aplicación anterior (que tiene un número más bajo), y una aplicación o un sistema operativo de nivel superior usa una versión del entorno en tiempo de ejecución de la aplicación más reciente (que tiene un número más alto). Las secciones siguientes describen lo que puede esperar en cada escenario posible.

Aplicaciones de nivel inferior con un sistema operativo de nivel superior

Las imágenes existentes de nivel inferior que usan solo las API de producción se admiten en las versiones de nivel superior del sistema operativo Azure Sphere. Por ejemplo, una aplicación que se compiló con el conjunto de API de destino 1 se ejecuta correctamente en un sistema operativo de Azure Sphere que admita la versión 2 del entorno en tiempo de ejecución de la aplicación. Por lo tanto, las aplicaciones implementadas existentes seguirán funcionando correctamente después de las actualizaciones del SO en la nube. Puede transferir localmente o implementar en la nube las imágenes solo de producción de nivel inferior en un sistema operativo de nivel superior sin errores.

Las imágenes de nivel inferior que usan solo API Beta no se admiten y es posible que no funcionen por diseño en las versiones de nivel superior del sistema operativo Azure Sphere. Por ejemplo, una aplicación que se compiló con el conjunto de API de destino 1+Beta1902 podría no ejecutarse en un sistema operativo de Azure Sphere que tenga la versión 2 del entorno en tiempo de ejecución de la aplicación. Los intentos de transferir localmente esta imagen devuelven un error a menos que use la --force marca en el comando azsphere device sideload deploy. Del mismo modo, el comando azsphere image add requiere la --force marca para cargar dicha imagen. Ninguna comprobación actual impide posteriormente que una imagen de nivel inferior cargada con anterioridad y que use API Beta se implemente junto con un SO de nivel superior que ya no admita esas API Beta.

Aplicaciones de nivel superior con sistema operativo de nivel inferior

No es posible implementar aplicaciones de nivel superior en versiones de nivel inferior del sistema operativo de Azure Sphere, independientemente de si usa las API Beta. Los intentos de transferir localmente dicha imagen producirán un error. La implementación por vía inalámbrica no es actualmente posible porque el SDK y el SO de nivel superior se publican simultáneamente.

Compartir vía