📚 课程目录第3章 Linux主机环境准备

3、Linux主机环境准备：安装依赖包与配置Python虚拟环境

在开始Zephyr OS驱动开发之前，必须为Linux主机安装必要的系统依赖包，并配置隔离的Python虚拟环境。本章将指导你完成从基础工具链安装到环境验证的全过程，确保后续编译与调试环节不会因环境问题中断。

适用环境： 本教程以 Ubuntu 22.04 LTS 为例，其他Debian系发行版命令基本一致。若使用Fedora/Arch，请自行替换包管理器命令。

3.1 安装系统依赖包

Zephyr SDK与构建系统依赖以下核心工具：Python 3.8+、pip、Git、设备树编译器（dtc）、Ninja构建系统、CMake以及部分编译库。请按顺序执行安装。

3.1.1 更新包索引并安装基础工具

sudo apt update
sudo apt upgrade -y
sudo apt install -y \
  python3 \
  python3-pip \
  python3-venv \
  git \
  device-tree-compiler \
  ninja-build \
  cmake \
  gperf \
  ccache \
  libncurses5-dev \
  libssl-dev \
  libelf-dev \
  libudev-dev \
  libpcap-dev \
  libgmp-dev \
  libmpc-dev \
  libmpfr-dev \
  wget \
  curl \
  xz-utils \
  file

  关键包说明：
  device-tree-compiler (dtc)：编译设备树源文件（.dts/.dtsi）为二进制（.dtb），是Zephyr硬件描述的核心工具。
ninja-build：比Make更快的构建系统，Zephyr默认使用Ninja。
gperf：生成完美哈希函数，用于Zephyr内核对象查找。
ccache：编译缓存，大幅加速重复构建。

3.1.2 验证基础工具版本

安装完成后，使用以下命令验证各工具是否可用，并记录版本号以便后续排查。

工具	验证命令	最低版本要求
Python 3	`python3 --version`	≥ 3.8
pip	`pip3 --version`	≥ 21.0
Git	`git --version`	≥ 2.25
dtc	`dtc --version`	≥ 1.6.0
CMake	`cmake --version`	≥ 3.20
Ninja	`ninja --version`	≥ 1.10

常见问题： 若 dtc --version 提示未找到，请检查是否已安装 device-tree-compiler 包。某些Ubuntu旧版本默认dtc版本过低，需从PPA或源码升级。

3.2 配置Python虚拟环境

Zephyr的Python工具链（west、pyelftools、kconfiglib等）依赖特定版本。使用虚拟环境可以避免与系统Python包冲突，并保证项目可复现。

3.2.1 创建并激活虚拟环境

建议将虚拟环境放置在用户目录下，统一管理。

# 创建虚拟环境目录（位置可自定义）
python3 -m venv ~/zephyr_venv

# 激活虚拟环境
source ~/zephyr_venv/bin/activate

# 验证当前Python解释器路径（应指向虚拟环境）
which python3
# 输出示例：/home/yourname/zephyr_venv/bin/python3

提示： 每次打开新终端进行Zephyr开发时，都需要执行 source ~/zephyr_venv/bin/activate 激活虚拟环境。建议将此命令添加到 ~/.bashrc 或使用direnv自动加载。

3.2.2 升级pip并安装west

west是Zephyr的元构建工具，负责管理多仓库、配置构建参数。

# 确保虚拟环境已激活
pip install --upgrade pip setuptools wheel

# 安装west
pip install west

# 验证west版本
west --version
# 输出示例：West version: v1.2.0

3.2.3 安装其他Python依赖

Zephyr构建过程还需要以下Python包，建议提前安装。

pip install pyelftools kconfiglib pyyaml psutil

包名	用途
pyelftools	解析ELF文件，用于Zephyr固件分析
kconfiglib	Kconfig配置解析库，Zephyr菜单配置后端
pyyaml	YAML文件解析，用于设备树绑定
psutil	系统资源监控，用于构建性能分析

3.3 验证基础工具链

完成安装后，执行以下综合验证脚本，确保所有工具就绪。

#!/bin/bash
# 环境验证脚本：check_env.sh
echo "=== Zephyr 开发环境验证 ==="
echo ""

# Python
echo "[Python]"
python3 --version || echo "  FAIL"
echo ""

# pip
echo "[pip]"
pip3 --version || echo "  FAIL"
echo ""

# Git
echo "[Git]"
git --version || echo "  FAIL"
echo ""

# dtc
echo "[Device Tree Compiler]"
dtc --version || echo "  FAIL"
echo ""

# CMake
echo "[CMake]"
cmake --version | head -1 || echo "  FAIL"
echo ""

# Ninja
echo "[Ninja]"
ninja --version || echo "  FAIL"
echo ""

# West
echo "[West]"
west --version || echo "  FAIL"
echo ""

# 虚拟环境
echo "[Virtual Env]"
if [ -n "$VIRTUAL_ENV" ]; then
    echo "  Active: $VIRTUAL_ENV"
else
    echo "  WARNING: No virtual env active"
fi
echo ""

echo "=== 验证完成 ==="

将上述内容保存为 check_env.sh，赋予执行权限并运行：

chmod +x check_env.sh
./check_env.sh

  预期输出： 所有工具均显示版本号，无FAIL提示。若出现FAIL，请根据提示重新安装对应包。

3.4 环境依赖关系总览

下图展示了Linux主机上各工具与Zephyr构建系统的依赖层级关系，帮助你理解每个组件的作用位置。

3.5 常见问题与避坑指南

Python版本冲突： 系统可能同时存在Python 2.7和Python 3，务必使用 python3 命令，而非 python。
虚拟环境未激活： 若 west --version 提示未找到，请检查是否已执行 source ~/zephyr_venv/bin/activate。
dtc版本过低： Ubuntu 20.04默认dtc为1.5.0，需从 ppa:ubuntu-toolchain-r/test 或源码编译升级。
CMake找不到Ninja： 安装ninja-build后，CMake会自动检测。若未检测到，可设置环境变量 CMAKE_MAKE_PROGRAM=/usr/bin/ninja。
权限问题： 不要使用 sudo pip install，这会将包安装到系统目录，破坏虚拟环境隔离性。

重要： 在后续所有Zephyr开发操作中，请始终在虚拟环境激活状态下执行。建议在项目根目录创建 .envrc 文件（配合direnv）自动加载虚拟环境，避免遗忘。

至此，Linux主机环境准备完毕。你已经安装了所有系统依赖包，配置了隔离的Python虚拟环境，并验证了基础工具链的可用性。下一阶段将使用west工具初始化Zephyr工作区并获取源码。