Uso de contenedores para compilar aplicaciones de Azure Sphere
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).
Nota:
En este tema se describe cómo usar Docker Desktop para Windows para compilar aplicaciones de Azure Sphere en un contenedor. Para compilar aplicaciones en un contenedor de Docker en Linux, puede usar el mismo contenedor de azurespheresdk desde el Registro de artefactos Microsoft o MAR (también conocido como Microsoft Container Registry o MCR).
Instalar Docker Desktop
Puede usar Docker para ejecutar un contenedor de Linux independiente con el SDK de Azure Sphere preinstalado. Esta imagen también se puede usar como base para sus propias implementaciones. La etiqueta de imagen hace referencia a la versión del SDK que contiene.
Para poder descargar y ejecutar un contenedor de Docker, debe instalar Docker Desktop en Windows o Linux.
Después de instalar Docker Desktop para Windows, asegúrese de habilitar las características de Windows de Hyper-V y Contenedores. Es posible que tenga que reiniciar después de la instalación.
Una vez instalado, inicie Docker Desktop desde el menú Inicio de Windows o desde el icono de acceso directo agregado al escritorio.
Linux es el tipo de contenedor predeterminado para Docker Desktop en Windows. Azure Sphere usa contenedores de Linux. Para poder ejecutar contenedores de Linux, debe asegurarse de que Docker tenga como destino el demonio correcto. Para comprobar que Linux es el tipo predeterminado actual de contenedor, haga clic con el botón derecho en el icono de ballena de Docker en la bandeja del sistema. Si ve Cambiar a contenedores de Windows, ya tiene como destino el demonio de Linux. Si está en el contenedor de Windows, puede activar esta opción si selecciona Cambiar a contenedores de Linux en el menú de acción al hacer clic con el botón derecho en el icono de ballena de Docker en la bandeja del sistema. Para más información, consulte Switch between Windows and Linux containers (Cambio entre contenedores de Windows y Linux).
Nota:
Espere hasta que se detenga la animación del icono de ballena de Docker Desktop. El icono puede estar en el área Notificaciones ocultas. Mantenga el puntero sobre el icono para ver el estado de Docker Desktop.
Uso del contenedor de entornos de compilación del SDK de Azure Sphere para compilar aplicaciones de ejemplo
Puede usar un contenedor de forma interactiva escribiendo y emitiendo un comando; Sin embargo, es más eficaz capturar los pasos necesarios para compilar las aplicaciones en un archivo que Docker puede usar para compilar una imagen personalizada basada en la imagen original de Azure Sphere. Esto garantiza que el proceso de compilación sea repetible y coherente. De forma predeterminada, este archivo debe denominarse Dockerfile y estar en el $PATH donde se ejecuta el comando docker.
Los pasos siguientes proporcionan un esquema para crear instrucciones de Dockerfile para compilar ejemplos de Azure Sphere. Puede ajustar estos pasos para sus propias necesidades.
Cree un contenedor basado en el contenedor de mcr.microsoft.com/azurespheresdk.
Clone el repositorio de ejemplos de Azure Sphere desde GitHub.
Cree un directorio para almacenar el ejemplo en cuando se compila.
Cree una variable de entorno para especificar el ejemplo que desea compilar.
Ejecute CMake para compilar el ejemplo y colocarlo en el directorio especificado.
Creación de un Dockerfile para compilar ejemplos
Para compilar una imagen de Docker basada en la imagen de Azure Sphere, pero con la funcionalidad de compilación personalizada, cree un archivo de texto (sin extensión de archivo) con las siguientes instrucciones de Docker:
FROM mcr.microsoft.com/azurespheresdk AS azsphere-samples-repo
RUN git clone https://github.com/Azure/azure-sphere-samples.git
FROM azsphere-samples-repo AS azsphere-sampleapp-build
RUN mkdir /build
WORKDIR /build
ENV sample=HelloWorld/HelloWorld_HighLevelApp
CMD cmake -G "Ninja" \
-DCMAKE_TOOLCHAIN_FILE="/opt/azurespheresdk/CMakeFiles/AzureSphereToolchain.cmake" \
-DAZURE_SPHERE_TARGET_API_SET="latest-lts" \
-DCMAKE_BUILD_TYPE="Debug" \
/azure-sphere-samples/Samples/${sample} && \
ninja
Este archivo usa la variable de entorno ENV para especificar el ejemplo que se va a compilar. Establezca un nuevo valor para ENV para compilar un ejemplo diferente de HelloWorld/HelloWorld_HighLevelApp.
Consulte Descripción de línea a línea de las instrucciones de Dockerfile para obtener más información sobre las instrucciones de Dockerfile.
Compilación de la aplicación de ejemplo predeterminada mediante Dockerfile
Hay tres pasos necesarios para compilar una aplicación de ejemplo mediante un Dockerfile personalizado:
Compile la imagen a partir del Dockerfile mediante una interfaz de línea de comandos, como PowerShell, símbolo del sistema de Windows o shell de comandos de Linux:
docker build --target azsphere-sampleapp-build --tag azsphere-sampleapp-build .La
--targetopción especifica qué parte de una compilación de varias fases se va a usar. La--tagopción especifica un nombre de la imagen y solo debe estar en minúsculas. Las imágenes de Docker siempre deben usar solo letras minúsculas. Si no especifica un nombre con--tag, la imagen tendrá un número de 12 dígitos con el que no es fácil trabajar. No olvide el punto al final del comando. Puede enumerar las imágenes con eldocker imagescomando .Docker compilará una imagen denominada azsphere-sampleapp-build basada en el archivo denominado "Dockerfile". Si el Dockerfile se denomina algo más, use la
--fileopción para especificar el nombre.Asigne al contenedor un nombre más sencillo mediante la
--nameopción . Elruncomando escribirá el contenedor y compilará el ejemplo especificado por la variable de entorno ENV . Use la interfaz de la línea de comandos para escribir este comando:docker run --name hello_hl azsphere-sampleapp-buildLa aplicación de ejemplo (HelloWorld/HelloWorld_HighLevelApp) se compilará y se colocará en el
/builddirectorio dentro del contenedor. Cuando el contenedor haya terminado de ejecutarse, se cerrará y volverá a la interfaz de la línea de comandos.Nota:
Este comando compila la aplicación sin ninguna interacción y sale del contenedor una vez finalizada la compilación. El contenedor sigue activo después de salir. Esto se debe a que no especificó las
-itopciones o--rm. Más adelante puede usar eldocker runcomando de nuevo en el contenedor sin volver a generarlo, siempre y cuando se ejecute Docker Desktop.Copie los resultados de la compilación desde dentro del contenedor en el entorno del equipo host. Use la interfaz de la línea de comandos para escribir este comando:
docker cp hello_hl:/build .Este comando copia el contenido del
/builddirectorio dentro del contenedor de hello_h1 en el directorio del equipo host desde el que emite el comando. El/builddirectorio se especifica como el directorio de trabajo (WORKDIR) en el que se va a compilar el ejemplo. Tenga en cuenta que todavía está fuera del contenedor, pero que emite comandos para él mediante el comando docker cp . No olvide el punto al final del comando.
Compilación de un ejemplo diferente mediante el Dockerfile personalizado
Para compilar un ejemplo diferente, por ejemplo, el ejemplo de GPIO, proporcione la ruta de acceso al ejemplo de GPIO.
docker run --name gpio_hl --env sample=GPIO/GPIO_HighLevelApp azsphere-sampleapp-build
Una vez completada la compilación, copie el resultado desde dentro del contenedor en el entorno del equipo host:
docker cp gpio_hl:/build .
No olvide el punto al final del comando.
Una vez copiado el paquete en el entorno de la máquina host, puede usar comandos de la CLI de Azure Sphere desde Windows o Linux para implementar la aplicación. Para obtener más información, consulte Implementación de la aplicación.
No se admite la interacción del dispositivo a través de USB desde un contenedor.
Explicación de línea a línea de las instrucciones de Dockerfile
A continuación se explica cada parte del Dockerfile creado en Creación de un Dockerfile para compilar ejemplos .
Preparación para varias compilaciones
FROM mcr.microsoft.com/azurespheresdk AS azsphere-samples-repo
Esta línea configura una nueva compilación, azsphere-samples-repo, basada en el contenedor de microsoft.com/azurespheresdk original.
Descarga de los ejemplos de Azure Sphere
RUN git clone https://github.com/Azure/azure-sphere-samples.git
Esta línea clona todos los ejemplos del repositorio de ejemplos de Azure Sphere.
Adición de otra compilación de varias fases de destino
FROM azsphere-samples-repo AS azsphere-sampleapp-build
Esta línea agrega una nueva compilación basada en la compilación azsphere-samples-repo .
Establecimiento del directorio de trabajo dentro del contenedor
RUN mkdir /build
WORKDIR /build
Estas líneas crean un nuevo directorio de trabajo.
Creación de una variable de entorno predeterminada para especificar el ejemplo
ENV sample=HelloWorld/HelloWorld_HighLevelApp
Esta línea crea una variable de entorno que especifica el ejemplo que se va a compilar. En este caso, es el HelloWorld_HighLevelApp ejemplo. La variable de entorno se puede invalidar para especificar cualquier nombre de ejemplo y ruta de acceso.
Ejecución de CMake y Ninja para compilar un paquete
CMD cmake -G "Ninja" \
-DCMAKE_TOOLCHAIN_FILE="/opt/azurespheresdk/CMakeFiles/AzureSphereToolchain.cmake" \
-DAZURE_SPHERE_TARGET_API_SET="latest-lts" \
-DCMAKE_BUILD_TYPE="Debug" \
/azure-sphere-samples/Samples/${sample} && \
ninja
En esta sección se usa CMake para especificar parámetros usados al invocar Ninja para compilar el paquete.
Una vez finalizada la compilación, el contenedor dejará de ejecutarse.
Sugerencias de Docker
Estas sugerencias pueden ayudarle a trabajar con Docker de forma más eficaz.
Uso del comando docker run para explorar el contenedor base de forma interactiva
Use la interfaz de la línea de comandos para escribir este comando:
docker run --rm -it mcr.microsoft.com/azurespheresdk
En este ejemplo, mcr.microsoft.com/azurespheresdk es el nombre de la imagen a la que se crea el contenedor. Tenga en cuenta que la --rm opción cierra el contenedor una vez que se ejecuta y la -it opción especifica el acceso interactivo al contenedor.
El contenedor docker del entorno de compilación del SDK de Azure Sphere lo proporciona el Registro de artefactos Microsoft (MAR) y está disponible para el público.
Si el contenedor ya está en el equipo local, no se volverá a descargar.
La descarga y la configuración pueden tardar varios minutos. El entorno de compilación incluye todo lo necesario para compilar un paquete mediante el SDK de Linux de Azure Sphere.
Una vez completado el run comando, el símbolo del sistema cambiará a un signo "#". Ahora está dentro de un contenedor de Docker basado en Linux. Al escribir ls , se mostrará el directorio de Linux actual dentro del contenedor, similar a este listado:
bin cmake-3.14.5-Linux-x86_64 etc lib makeazsphere.sh mnt opt root sbin sys usr
boot dev home lib64 media ninja proc run srv tmp var
Escriba exit para dejar el contenedor. El contenedor ya no estará disponible para usted y tendrá que volver a crearlo con este comando:
docker run --rm -it mcr.microsoft.com/azurespheresdk
Si no usa la --rm opción , el contenedor no se eliminará al salir.
Identificación de contenedor
Al compilar un nuevo contenedor, tendrá un identificador como a250ade97090 (el identificador será diferente). Para muchos comandos de Docker, debe usar el identificador en lugar de la dirección microsoft.com/azurespheresdk .
Esta es una lista típica de información básica sobre los contenedores del sistema mediante este comando:
docker ps --all
El resultado tendrá un aspecto similar al siguiente:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
a250ade97090 microsoft.com/azurespheresdk "/bin/bash" 15 minutes ago Up 9 seconds pedantic_kilby
El identificador será diferente. Tenga en cuenta que Docker compone nombres aleatorios para el propietario del contenedor. Tenga en cuenta que en este ejemplo, solo hay un contenedor.
Trabajar dentro del contenedor
Si desea trabajar dentro de un contenedor en el equipo sin usar el comando run, use el comando exec con el identificador de contenedor y el script en el contenedor que desea ejecutar (/bin/bash) escribiendo:
docker exec -t a250ade97090 /bin/bash
El símbolo del sistema cambiará a un signo "#". Ahora está en un contenedor de Docker basado en Linux. Al escribir ls , se mostrará el directorio de Linux actual dentro del contenedor:
bin cmake-3.14.5-Linux-x86_64 etc lib makeazsphere.sh mnt opt root sbin sys usr
boot dev home lib64 media ninja proc run srv tmp var
Para dejar el contenedor, escriba el exit comando .
Limitaciones del contenedor de compilación del SDK de Azure Sphere
El contenedor de compilación del SDK de Azure Sphere está diseñado solo para compilar paquetes de Azure Sphere. No está diseñado para ejecutar comandos de la CLI de Azure Sphere, recuperar o transferir localmente dispositivos o depurar. El contenedor no tiene acceso a las funciones USB.
Limitaciones del contenedor de Docker Linux
Un contenedor de Docker Linux no es el mismo que una instalación completa de Linux. Por ejemplo, no puede ejecutar aplicaciones de GUI de Linux en un contenedor de Docker Linux.
Uso de contenedores de compilación de varias fases para reducir las dependencias
La característica de compilación de varias fases de Docker permite usar varias instrucciones FROM en el Dockerfile para reducir las dependencias. Cada instrucción FROM puede usar una base diferente y cada una de ellas comienza una nueva fase de la compilación.
Para más información sobre las compilaciones de varias fases de Docker, consulte Uso de compilaciones de varias fases.
Docker recomienda compilar varias fases como procedimiento recomendado. Para obtener más información sobre los procedimientos recomendados de Docker, consulte Guía de introducción a procedimientos recomendados de Dockerfile.
Agregar un nombre descriptivo a la fase con el argumento AS
De forma predeterminada, las fases no se denominan, pero tienen un número de identificador. Puede hacer que el Archivo Dockerfile sea más legible agregando un nombre descriptivo a la fase anexando AS y un nombre. Por ejemplo:
FROM mcr.microsoft.com/azurespheresdk AS azsphere-samples-repo
Para obtener más información sobre el uso del argumento AS en comandos de varias fases, vea Asignar un nombre a las fases de compilación.
Creación del destino con un nombre descriptivo como procedimiento recomendado
Al compilar un destino, puede asignarle un nombre significativo mediante la opción --tag . Los nombres significativos son útiles. Por ejemplo:
docker build --target azsphere-sampleapp-build --tag azsphere-sampleapp-build .
Para obtener más información sobre el uso de nombres con el comando de compilación de Docker, consulte la referencia de compilación de Docker.