01 · Fedora 开发环境
目标：准备编译 Zephyr 固件所需的主机工具。本页是给后续实验使用的操作说明；当前搭建文档站并未替你安装这些系统包。
先保持目录清晰
~/Projects/
├── zephyr-docs/ # 当前中文文档站
└── zephyr-workspace/ # 后续实际执行 west init 时创建
├── .venv/ # Python 虚拟环境
├── .west/ # west 元数据
├── zephyr/ # Zephyr 源码
├── modules/ # west 管理的依赖
└── applications/ # 自己的固件应用
SDK 后续放在 ~/.local/opt/；不要把大型源码树、SDK、串口日志或虚拟环境塞进文档仓库。
安装工具：按包名安装并验证
Fedora 版本之间的软件组名称可能不同。本教程直接列出所需包，避免软件组安装失败后继续执行，遗漏 C 编译器。
sudo dnf install git gcc gcc-c++ make cmake ninja-build gperf ccache \
dfu-util dtc wget which python3-pip python3-tkinter python3-devel \
xz file SDL2-devel libusb1-devel systemd-devel pkgconf-pkg-config
这是在 Zephyr v4.2.0 官方 Fedora 依赖列表基础上，结合本机安装错误补全后的包清单。
| 依赖 | 用途 |
|---|---|
gcc、gcc-c++、make | 主机程序及 Python 原生扩展的源码编译 |
python3-devel | 与 Fedora 系统 Python 配套的开发头文件 |
libusb1-devel | libusb 头文件与 pkg-config 元数据 |
systemd-devel | libudev 开发文件 |
pkgconf-pkg-config | 帮助构建脚本定位系统开发库 |
主机 GCC 与 Zephyr SDK 中面向 ESP32 的交叉编译器用途不同。安装 SDK 不等于系统中已经有可供 pip 使用的 gcc。
安装后必须检查
rpm -q gcc gcc-c++ make python3-devel libusb1-devel systemd-devel pkgconf-pkg-config
command -v gcc g++ make cmake ninja python3 pkg-config
gcc --version
g++ --version
cmake --version
python3 --version
dtc --version
ninja --version
pkg-config --modversion libusb-1.0 libudev
若有包未安装、命令找不到或 pkg-config 报错，先解决，再执行 Python 依赖安装。 不要只检查 USB 库而遗漏编译器。
记录主机版本和架构：
cat /etc/fedora-release
uname -m
Python 版本选择
Zephyr v4.2.0 入门指南的最低要求是 CMake 3.20.5、Python 3.10、DTC 1.4.6；最低版本不是对任意更高版本的完整兼容承诺。
本次 Fedora 系统 Python 为 3.14.7，pip 为 hidapi 0.14.0.post4 选择了源码包。先遇到 libusb 开发文件缺失，补齐后又遇到 gcc 不存在。这两个错误都有明确的系统依赖原因，不能据此认定 Python 3.14 本身无法使用。
本次新建的 Python 3.12.14 环境已通过完整 Python 依赖安装。如果新建学习环境，可以优先选择 Python 3.12，降低旧依赖缺少预编译 wheel 的概率；仍应保留上面的编译器和开发库检查。已有环境则先补齐依赖，不要未经确认就删除重建。若使用其他版本 Python，源码编译所需头文件必须与该解释器匹配。
下一页会显式检查虚拟环境解释器，避免误用系统 pip。详细错误链见 hidapi 排错。
检查点
- 记录 Fedora 版本和主机架构。
-
gcc、g++、cmake、python3、dtc、ninja都能正常输出版本。 - libusb 和 libudev 的 pkg-config 检查均成功。
- 明确文档目录和固件工作区是两个目录。
下一步：创建 west 工作区。
官方来源
基于 Zephyr v4.2.0 官方资料整理的中文学习笔记，非逐字翻译；命令及说明作了学习场景适配。