Versión en tiempo de ejecución de aplicaciones, sysroots y API beta

Artículo
04/03/2024

Una versión del SDK de Azure Sphere 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 siguen en desarrollo y pueden cambiar o eliminarse 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 nuevas características, lo que permite crear prototipos y comentarios antes de finalizar. Por lo general, las aplicaciones que usan API beta requerirán modificaciones después de que las futuras versiones del SO y SDK de Azure sigan funcionando correctamente.

Las características beta están etiquetadas como característica BETA en la documentación. Cada aplicación de alto nivel de Azure Sphere especifica si se centra solo en las API de producción o en las de producción y beta.

Conjuntos de API de destino, ARV y sysroots

El conjunto de API de destino indica qué API usa la aplicación: solo api de producción o de producción y API beta. El valor del conjunto de API de destino es un entero que representa la versión en tiempo de ejecución de la aplicación (ARV) o el ARV más una cadena que identifica la versión de la API beta. Solo el valor numérico especifica las API de producción en el ARV, mientras que el "valor+BetaNumber" especifica la producción y las API 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. Las futuras versiones agregarán arvs adicionales.

El SDK de Azure Sphere implementa varios conjuntos de API mediante sysroots. Una sysroot especifica las bibliotecas, archivos de encabezado y herramientas que se usan para compilar y vincular una aplicación que se centra en un determinado conjunto de API. La sysroots se instala en el directorio SDK de Sphere de Microsoft Azure en la subcarpeta sysroots.

Establecer o actualizar el conjunto de API de destino para una aplicación de alto nivel

Si basa la aplicación en una muestra de Azure Sphere, la API de destino establecida de forma predeterminada es el conjunto de API que usa la muestra. Si en la muestra solo se usan API de producción, el conjunto de API de destino se establecerá en el valor ARV actual. Si la muestra usa api de producción y beta para la versión actual, el conjunto de API de destino será "value+BetaNumber", para incluir las API beta.

Si no basa la aplicación en un ejemplo, tendrá que establecer la 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 LA API de destino si vuelve a crear la aplicación para una nueva versión del sistema operativo. Si la aplicación usa API beta, debes actualizarla cuando cambien las opciones del conjunto de API de destino, que suelen producirse en cada versión de características. Las API beta se pueden mover directamente del estado beta a la producción, lo que produce un nuevo ARV, o pueden cambiarse y permanecer en la versión beta. Si actualizas una aplicación que usa API beta para dirigirte a un conjunto de API de destino más reciente, puedes encontrar errores o advertencias sobre las API eliminadas o retiradas.

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

Especificar el conjunto de API de destino

Establecer la 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 tu aplicación se centra en el conjunto de API más reciente, puedes establecer esta variable en "latest-lts", si aún no lo ha sido. Si tu aplicación se centra en el último conjunto de API beta, puedes establecer esta variable en "latest-beta", si aún no lo está. Sin embargo, si la aplicación se centra en un conjunto de API más antiguo, debe establecer esta variable para que coincida con el valor específico que usa.

Para especificar la variable de AZURE_SPHERE_TARGET_API_SET externa en un proyecto de Visual Studio, establezca lo siguiente en el archivo de CMakeSettings.json, tanto en las configuraciones de ARM-Debug como de ARM-Release:
```
"variables": [
  {
    "name": "AZURE_SPHERE_TARGET_API_SET",
    "value": "latest-beta"
  }
]
```
Para especificar la variable de AZURE_SPHERE_TARGET_API_SET externa en un proyecto de Visual Studio Code, establezca lo siguiente en el archivo .vscode/settings.json:
```
    "cmake.configureSettings": {
      "AZURE_SPHERE_TARGET_API_SET": "latest-lts"
  },
```
Para especificar la variable de 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"

Reemplaza "latest-lts" por "latest-beta" o un valor anterior específico como "4" o "5+Beta2004", como se explicó anteriormente.

Compatibilidad con so y conjuntos de API de destino

La compatibilidad de una aplicación con el SO Azure Sphere depende del conjunto de API de destino con el que se creó la aplicación y del ARV más reciente compatible con la versión del so. Una aplicación de nivel inferior o sistema operativo usa un ARV anterior (que tiene un número inferior) y una aplicación de nivel superior o OS usa un ARV más reciente (que tiene un número más alto). En las siguientes secciones se describe qué esperar en cada posible escenario.

Aplicaciones de nivel inferior con sistema operativo de nivel superior

Las imágenes de nivel inferior existentes que usan solo API de producción son compatibles con las versiones de nivel superior del so Azure Sphere. Por ejemplo, una aplicación que se creó con el conjunto de API de destino 1 se ejecuta correctamente en un sistema operativo Azure Sphere compatible con ARV 2. Por lo tanto, las aplicaciones implementadas existentes seguirán funcionando correctamente después de las actualizaciones del SISTEMA operativo en la nube. Puedes realizar instalaciones de prueba o implementar imágenes de nivel inferior de producción en un sistema operativo de nivel superior sin errores.

Las imágenes de nivel inferior que usan API beta no son compatibles, y es posible que no funcionen por diseño, en las versiones de nivel superior del SO Azure Sphere. Por ejemplo, una aplicación creada con el conjunto de API de destino 1+Beta1902 podría no ejecutarse en un sistema operativo Azure Sphere que tenga ARV 2. Intenta realizar la instalación de prueba de tal imagen devuelven un error a menos que uses la --force marca en el comando az sphere device sideload deploy . De forma similar, el comando az sphere image add requiere que la --force marca cargue dicha imagen. Posteriormente, ninguna comprobación actual impide la implementación de una imagen de nivel inferior cargada anteriormente que use las API beta junto con un sistema operativo de nivel superior que ya no admite dichas API beta.

Aplicaciones de nivel superior con sistema operativo de nivel inferior

Las aplicaciones de nivel superior no se pueden implementar en versiones de nivel inferior del so Azure Sphere, independientemente de si usan las API beta. Los intentos de instalación de prueba de dicha imagen producirán un error. Los intentos de implementación por el aire no son posibles actualmente porque el SDK de nivel superior y el sistema operativo se publican simultáneamente.