零基础搭建Zephyr开发环境：Docker到首次编译完整指南

零基础搭建Zephyr开发环境：Docker到首次编译完整指南

【免费下载链接】zephyr-cnzephyr-cn is a collection of original work of SIG-Zephyr项目地址: https://gitcode.com/openeuler/zephyr-cn

读完这篇指南，你的电脑上将多出一个完整的Zephyr（一款面向嵌入式设备的开源实时操作系统）工程：它能在容器里被 west（Zephyr 自带的多仓库项目管理工具）命令驱动编译，编译产物会直接在 QEMU（开源的硬件模拟器，用来虚拟一块 CPU 而不需要真实开发板）上跑起来，终端里滚动着"哲学家们思考、吃饭"的日志。整个过程不需要真实硬件，一台装好 Docker Desktop 的 Windows 机器就够了。下面是你最终会看到的运行画面，先睹为快：

动手前，用这张表核对你手头的前置条件：

这些资源都可以通过 openEuler 社区的 zephyr-cn 仓库获取。

🐳 一条流水线搭建Zephyr开发容器

搭建过程其实就是一条流水线：拉镜像 → 起容器 → 铺项目 → 装 SDK，四步首尾相接，中间任何一步"卡住不动"都不要慌，先对照每步末尾的验证提示确认状态再往下走。

1. 先给 Docker 换个国内镜像源。打开 Docker Desktop 的 Settings → Docker Engine，在 JSON 配置里加上registry-mirrors字段并指向一个国内加速地址，保存后 Docker 会自动重启。这一步不做，后面的镜像拉取大概率慢得让人怀疑人生。

2. 拉取官方 Zephyr 构建镜像。下面这条命令从镜像仓库下载zephyr-build镜像，它预装了编译 Zephyr 所需的全部工具链：

   docker pull zephyrprojectrtos/zephyr-build:latest

   执行后你应看到逐层滚动Pull complete，最后一行停在Status: Downloaded newer image，耗时取决于带宽，耐心等待即可：

3. 创建容器并挂上本地目录。下面这条命令启动一个名为SIG_Zephyr的容器，同时把 Windows 上的D:\Workspace\SIG_Zephyr文件夹挂进容器的/workdir——这样你在 Windows 资源管理器里放的文件，容器内随手可见，省去了来回传文件的麻烦：

   docker run -it --name SIG_Zephyr -v /d/Workspace/SIG_Zephyr:/workdir zephyrprojectrtos/zephyr-build:latest

   执行后命令行提示符会变成user@容器ID:/workdir$，说明你已经坐在容器里面了：

4. 把两个压缩包放进挂载目录，然后在容器里解压并校验。先在 Windows 侧把项目包和 SDK 安装器复制到D:\Workspace\SIG_Zephyr，回到容器内解压，再用west update按清单同步各子仓库（这一步同时能验证工程目录结构是否完整，正常会看到一串仓库被检出）：

   tar -xvzf sig_zephyr_v2.7.4.tar.gz west update

   解压后/workdir下会多出.west、bootloader、modules、tools、zephyr等目录，这就是一个标准 Zephyr 工作区的样子。

5. 安装 SDK。给安装器加上执行权限后运行，按默认路径一路回车：

   chmod +x zephyr-sdk-0.13.1-linux-x86_64-setup.run ./zephyr-sdk-0.13.1-linux-x86_64-setup.run

   安装结束时若提示把 SDK 加入PATH，选默认即可，容器镜像里的 west 构建流程会自动找到它。

至此环境就绪，真正让 Zephyr 跑起来只需要两条命令。

⚙️ 用west在QEMU上编译运行哲学家示例

构建 Zephyr 应用的核心命令是west build，其中-b指定板级目标。这里选qemu_cortex_m3——它是一块"虚拟开发板"，对应一颗 Cortex-M3 内核，编译和运行全程不需要任何实物。我们用它来构建 Zephyr 自带的 philosophers（哲学家问题）示例，这是一个经典的多线程同步演示程序。

先进入 zephyr 源码目录，然后执行下面这条命令完成一次干净的配置加编译（-p auto表示自动清理旧构建缓存）：

cd zephyr west build -p auto -b qemu_cortex_m3 samples/philosophers

编译成功的标志有两处：[130/130] Linking C executable zephyr/zephyr.elf说明可执行文件已生成，末尾的 Memory 表格显示 FLASH 占用约 7.39%、SRAM 约 14.60%，说明一个几 KB 量级的嵌入式程序被装进了"芯片"：

编译产物已经就位，现在让它在虚拟硬件上跑起来。下面这条命令复用刚才的构建目录，把 elf 文件送进 QEMU 执行：

west build -t run

看到Booting Zephyr OS build v2.7.4后，五个哲学家会轮流在 THINNING（思考）、EATING（进食）、HOLDING ONE FORK（握着叉子）三种状态间切换——这些跳动的状态行就是五个线程在并发调度下的真实写照。按Ctrl+C或Ctrl+A, X即可退出仿真，到这里其实已经可以跑了：

命令行闭环已经打通，接下来把日常开发搬进图形界面，体验会舒适很多。

🔌 让VSCode理解Zephyr代码：插件与工作区配置

Zephyr 社区主流玩法是纯命令行，但 VSCode 加上几个插件后，代码浏览、构建、调试都能图形化完成。推荐安装：C/C++（智能提示与调试）、CMake（构建脚本支持）、kconfig（内核配置语法支持）、nRF DeviceTree（设备树文件支持）、Arm Assembly（汇编高亮）。配置前后的差异如下表：

其中跳转功能的关键是compile_commands.json——构建系统每次配置 CMake 后都会生成这个文件，记录了参与编译的文件和编译器参数。因为 Zephyr 代码量很大，插件默认索引扛不住，必须靠它划定范围（注意它只覆盖本次构建用到的文件，没启用的子系统的代码不会纳入提示）。

工作区建议用 multi-root 布局，把zephyr源码、build构建目录和按需的 modules 一起挂进来，配置文件不超过 15 行，可直接复制使用：

{ "folders": [ { "path": "zephyr" }, { "path": "build" } ], "settings": { "C_Cpp.default.compileCommands": "${workspaceFolder}/../build/compile_commands.json", "C_Cpp.default.cStandard": "c99" } }

构建任务和 GDB 调试器分别由build/.vscode/tasks.json与launch.json接管，zephyr-cn 仓库的vscode/目录下有现成参考，拷进你的 build 目录即可生效。理解代码跳转为什么能跨文件生效，看看 Zephyr 的分层结构会更有感觉——从平台层到内核、再到网络等子系统，配置完成后各层代码的声明与定义都能互相跳转：

体验升级到位了，但再顺滑的流程也绕不开几个高频故障，下面逐个给出解法。

🛠 一行命令修好：高频问题与对应处理

接下来可以去翻一翻samples/下其他示例（比如hello_world），把-b换成别的目标板体验不同平台；想上真机时，只需把板级目标换成你的开发板、接上调试器即可。延伸阅读：

• West 工具入门：doc/source/develop/west/basic.rst
• Windows Docker 环境完整说明：doc/source/develop/windows_docker.rst
• VSCode 开发工作流详解：doc/source/develop/vscode.rst

【免费下载链接】zephyr-cnzephyr-cn is a collection of original work of SIG-Zephyr项目地址: https://gitcode.com/openeuler/zephyr-cn