使用容器生成 Azure Sphere 应用

项目
08/09/2023

注意

本主题介绍如何使用适用于 Windows 的 Docker Desktop 在容器中生成 Azure Sphere 应用程序。若要在 Linux 上的 Docker 容器中生成应用，可以使用 Microsoft 工件注册表或 MAR (也称为 Microsoft 容器注册表或 MCR) 中的同一 azurespheresdk 容器。

安装 Docker Desktop

可以使用 Docker 运行预安装了 Azure Sphere SDK 的独立 Linux 容器。此映像还可以用作你自己的部署的基础。映像标记是指它包含的 SDK 版本。

必须先在 Windows 或 Linux 上安装 Docker 桌面，然后才能下载并运行 Docker 容器。

安装适用于 Windows 的 Docker Desktop 后，请确保启用 Hyper-V 和容器 Windows 功能。安装后，可能需要重新启动。

安装后，从 Windows“开始”菜单或添加到桌面的快捷方式图标启动 Docker Desktop。

Linux 是 Windows 上的 Docker Desktop 的默认容器类型。 Azure Sphere 使用 Linux 容器。若要运行 Linux 容器，需要确保 Docker 面向正确的守护程序。若要验证 Linux 是否为当前默认类型的容器，请右键单击系统任务栏中的 Docker whale 图标。如果看到 “切换到 Windows 容器”，则表示你已面向 Linux 守护程序。如果使用的是 Windows 容器，则右键单击系统托盘中的 Docker whale 图标时，可以通过从操作菜单中选择“ 切换到 Linux 容器 ”来切换此容器。有关详细信息，请参阅在 Windows 和 Linux 容器之间切换。

注意

等到 Docker 桌面鲸鱼图标动画停止。图标可能位于隐藏的“通知”区域中。将鼠标悬停在图标上可查看 Docker 桌面状态。

使用 Azure Sphere SDK 生成环境容器生成示例应用

可以通过输入容器并发出命令，以交互方式使用容器;但是，在 Docker 可用于基于原始 Azure Sphere 映像生成自定义映像的文件中捕获生成应用程序所需的步骤会更高效。这可确保生成过程可重复且一致。默认情况下，此文件必须命名为 Dockerfile，并且位于运行 docker 命令的$PATH中。

以下步骤概述了如何创建 Dockerfile 以生成 Azure Sphere 示例。可以根据自己的需求调整这些步骤。

基于 mcr.microsoft.com/azurespheresdk 容器创建新的容器。
从 GitHub 克隆 Azure Sphere 示例存储库。
创建一个目录，用于在生成示例时将其存储在其中。
创建环境变量以指定要生成的示例。
运行 CMake 以生成示例并将其置于指定的目录中。

创建用于生成示例的 Dockerfile

若要基于 Azure Sphere 映像生成 Docker 映像，但具有自定义生成功能，请使用以下 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

此文件使用 ENV 环境变量指定要生成的示例。为 ENV 设置一个新值，以生成不同于 HelloWorld/HelloWorld_HighLevelApp 的示例。

使用 Dockerfile 生成默认示例应用

使用自定义 Dockerfile 生成示例应用需要三个步骤：

使用命令行接口（如 PowerShell、Windows 命令提示符或 Linux 命令行界面）从 Dockerfile 生成映像：
```
docker build --target azsphere-sampleapp-build --tag azsphere-sampleapp-build .
```
选项 --target 指定使用多阶段生成的哪个部分。选项 --tag 指定映像的名称，并且只能是小写。 Docker 映像必须始终仅使用小写字母。如果不使用 --tag指定名称，则图像将具有一个 12 位数字，该数字不容易使用。不要忘记命令末尾的句点。可以使用命令列出图像 docker images 。

Docker 将根据名为“Dockerfile”的文件生成名为 azsphere-sampleapp-build 的映像。如果 Dockerfile 命名为其他名称，请使用 --file 选项指定名称。
使用 --name 选项为容器指定更简单的名称。命令 run 将进入容器并生成 由 ENV 环境变量指定的示例。使用命令行接口输入以下命令：
```
docker run --name hello_hl azsphere-sampleapp-build
```
将生成 (HelloWorld/HelloWorld_HighLevelApp) 的示例应用，并将其放置在 /build 容器内的目录中。容器完成运行后，它将退出并将你带回命令行界面。

注意

此命令无需任何交互即可生成应用，并在生成完成后退出容器。退出后，容器仍处于活动状态。这是因为未指定 -it 或 --rm 选项。以后可以在容器上再次使用该 docker run 命令，而无需重新生成它，只要 Docker Desktop 正在运行。
将生成结果从容器内部复制到主机环境。使用命令行接口输入以下命令：
```
docker cp hello_hl:/build .
```
此命令将 hello_h1 容器中的目录内容/build复制到从中发出命令的主机上的目录。目录 /build 指定为将示例编译到的工作目录 (WORKDIR) 。请注意，你仍在容器之外，但使用 docker cp 命令向容器发出命令。不要忘记命令末尾的句点。

使用自定义 Dockerfile 生成其他示例

若要生成其他示例（例如 GPIO 示例），请提供 GPIO 示例的路径。

docker run --name gpio_hl --env sample=GPIO/GPIO_HighLevelApp azsphere-sampleapp-build

生成完成后，将结果从容器内部复制到主机环境：

docker cp gpio_hl:/build .

不要忘记命令末尾的句点。

将包复制到主机环境后，可以使用 Windows 或 Linux 中的 Azure CLI 命令部署应用程序。有关详细信息，请参阅部署应用程序。

不支持从容器通过 USB 进行设备交互。

Dockerfile 指令的逐行讨论

下面介绍了在创建用于生成示例的 Dockerfile 中创建的 Dockerfile 的每个部分。

准备多个生成

FROM mcr.microsoft.com/azurespheresdk AS azsphere-samples-repo

此行基于原始 microsoft.com/azurespheresdk 容器设置新的生成 azsphere-samples-repo。

下载 Azure Sphere 示例

RUN git clone https://github.com/Azure/azure-sphere-samples.git

此行克隆 Azure Sphere 示例存储库中的所有示例。

添加另一个可定向的多阶段生成

FROM azsphere-samples-repo AS azsphere-sampleapp-build

此行基于 azsphere-samples-repo 生成添加新生成。

在容器内设置工作目录

RUN mkdir /build
WORKDIR /build

这些行将创建新的工作目录。

创建默认环境变量以指定示例

ENV sample=HelloWorld/HelloWorld_HighLevelApp

此行创建一个环境变量，指定要生成的示例。在本例中，它是HelloWorld_HighLevelApp示例。可以重写环境变量以指定任何示例名称和路径。

运行 CMake 和 Ninja 以生成包

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

本部分使用 CMake 指定调用 Ninja 生成包时使用的参数。

生成完成后，容器将停止运行。

Docker 提示

这些提示可以帮助你更有效地使用 Docker。

使用 docker run 命令以交互方式浏览基本容器

使用命令行接口输入以下命令：

docker run --rm -it mcr.microsoft.com/azurespheresdk

在此示例中， mcr.microsoft.com/azurespheresdk 是创建容器时所使用的映像的名称。请注意，选项在 --rm 运行后关闭容器， -it 选项指定对容器的交互式访问。

Azure Sphere SDK 生成环境 Docker 容器由 Microsoft 工件注册表 (MAR) 提供，可供公众使用。

如果容器已位于本地计算机上，则不会再次下载该容器。

下载和设置可能需要几分钟时间。生成环境包括使用 Azure Sphere Linux SDK 生成包所需的一切。

run命令完成后，命令提示符将更改为“#”符号。你现在位于基于 Linux 的 Docker 容器中。键入 ls 将显示容器中的当前 Linux 目录，类似于以下列表：

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

键入 exit 以离开容器。容器将不再可供你使用，你需要使用以下命令再次创建它：

docker run --rm -it mcr.microsoft.com/azurespheresdk

如果不使用 --rm 选项，则退出时不会删除容器。

容器标识

生成新容器时，它将具有一个 ID，例如 a250ade97090 (ID) 不同。对于许多 Docker 命令，必须使用 ID 而不是 microsoft.com/azurespheresdk 地址。

下面是有关系统上使用此命令的容器的基本信息的典型列表：

docker ps --all

结果将如下所示：

CONTAINER ID        IMAGE                   COMMAND             CREATED             STATUS              PORTS               NAMES
a250ade97090        microsoft.com/azurespheresdk   "/bin/bash"         15 minutes ago      Up 9 seconds                            pedantic_kilby

你的 ID 将有所不同。请注意，Docker 构成容器所有者的随机名称。请注意，在此示例中，只有一个容器。

在容器内工作

如果要在不使用 run 命令的情况下在计算机上的容器内工作，请键入以下内容，将 exec 命令与容器 ID 和要运行的容器中的脚本一起使用， (/bin/bash) ：

docker exec -t a250ade97090 /bin/bash

命令提示符将更改为“#”符号。你现在位于基于 Linux 的 Docker 容器中。键入 ls 将显示容器中的当前 Linux 目录：

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

若要离开容器，请 exit 键入命令。

Azure Sphere SDK 生成容器限制

Azure Sphere SDK 生成容器设计为仅生成 Azure Sphere 包。它 不适用于 运行 Azure CLI 命令、恢复或旁加载设备或调试。容器无权访问 USB 函数。

Docker Linux 容器限制

Docker Linux 容器与 Linux 的完整安装不同。例如，不能在 Docker Linux 容器中运行 Linux GUI 应用程序。

使用多阶段生成容器减少依赖项

Docker 多阶段生成功能允许在 Dockerfile 中使用多个 FROM 语句来减少依赖项。每个 FROM 指令都可以使用不同的基础，并且每个指令都会开始生成的新阶段。

有关 Docker 多阶段生成的详细信息，请参阅使用多阶段生成。

Docker 建议使用多阶段生成作为最佳做法。有关 Docker 最佳做法的详细信息，请参阅 Dockerfile 最佳做法简介指南。

使用 AS 参数向阶段添加有意义的名称

默认情况下，阶段未命名，但具有 ID 号。可以通过追加 AS 和名称，将有意义的名称添加到阶段，使 Dockerfile 更易于阅读。例如：

FROM mcr.microsoft.com/azurespheresdk AS azsphere-samples-repo

有关在多阶段命令中使用 AS 参数的详细信息，请参阅命名生成阶段。

使用有意义的名称生成目标作为最佳做法

生成目标时，可以使用 --tag 选项为其指定有意义的名称。有意义的名称很有用。例如：

docker build --target azsphere-sampleapp-build --tag azsphere-sampleapp-build .

有关将名称与 Docker 生成命令一起使用的详细信息，请参阅 Docker 生成参考。

通过