📚 课程目录第4章构建环境搭建

4. 构建环境搭建

Yocto 构建不是“装个工具就能跑”的轻量任务。一次完整的镜像构建会启动 BitBake 解析数千个配方，调用交叉编译器、打包器、文件系统生成工具，并在 tmp/ 下产生数十 GB 中间产物。因此，构建环境是否稳定、可复现，直接决定量产镜像能否被持续、可靠地产出。本节从主机配置、依赖安装、Docker 容器化到持续集成准备，给出一条可落地的环境搭建路径。

一、核心原理：为什么构建环境必须被“固化”

Yocto 的构建结果对宿主环境高度敏感。宿主的 GCC 版本、Python 版本、locale、文件系统大小写敏感性、可用内存与磁盘，都会影响 do_compile、do_package 等任务的成功率。更隐蔽的是，不同开发者机器上“能编过”的配方，在 CI 机器上可能因缺少某个 Perl 模块而失败。因此，构建环境的核心目标不是“装好”，而是可复现、可版本化、可迁移。

实现这一目标有三条主线：一是明确主机最低配置与内核参数；二是通过发行版包管理器安装 Yocto 所需依赖；三是用 Docker 把依赖、工具链和构建脚本一起封装，使本地与 CI 使用同一镜像。三者关系可用下图表示。

二、主机配置与依赖安装

主机配置的第一原则是“宁大勿小”。BitBake 默认并行度等于 CPU 核数，内存不足会触发 OOM Killer，表现为编译进程被随机杀死。建议至少 8 核、16 GB 内存、200 GB SSD；若构建 Qt 或 Chromium 类重型镜像，内存应提升到 32 GB 以上。磁盘方面，tmp/ 目录会随构建增长，SSD 能显著缩短 do_rootfs 时间。

内核参数需要调整 inotify 监听上限，否则 BitBake 在监控大量文件时会报 inotify watch limit reached：

# 临时生效
sudo sysctl fs.inotify.max_user_watches=524288
sudo sysctl fs.inotify.max_user_instances=512

# 永久生效，写入 /etc/sysctl.d/99-yocto.conf
echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.d/99-yocto.conf
echo "fs.inotify.max_user_instances=512" | sudo tee -a /etc/sysctl.d/99-yocto.conf
sudo sysctl --system

依赖安装以 Ubuntu 22.04 为例，官方文档给出的包列表可直接使用：

sudo apt update
sudo apt install -y gawk wget git diffstat unzip texinfo gcc \
  build-essential chrpath socat cpio python3 python3-pip python3-pexpect \
  xz-utils debianutils iputils-ping python3-git python3-jinja2 \
  libegl1-mesa libsdl1.2-dev pylint xterm zstd liblz4-tool \
  file locales libacl1

安装完成后执行 locale，确保 en_US.UTF-8 可用。Yocto 在解析配方时对 locale 敏感，缺失会导致 UnicodeDecodeError。

三、Docker 容器化构建环境

容器化的价值在于把“主机差异”压缩到镜像内部。推荐做法是：以 ubuntu:22.04 为基础，在 Dockerfile 中一次性安装全部依赖，并创建与宿主同 UID/GID 的构建用户，避免挂载卷后文件属主变成 root。

FROM ubuntu:22.04

ARG USER_ID=1000
ARG GROUP_ID=1000

RUN apt update && apt install -y \
    gawk wget git diffstat unzip texinfo gcc build-essential \
    chrpath socat cpio python3 python3-pip python3-pexpect \
    xz-utils debianutils iputils-ping locales zstd liblz4-tool \
    && rm -rf /var/lib/apt/lists/*

RUN locale-gen en_US.UTF-8
ENV LANG=en_US.UTF-8 LANGUAGE=en_US.UTF-8 LC_ALL=en_US.UTF-8

RUN groupadd -g ${GROUP_ID} builder && \
    useradd -m -u ${USER_ID} -g builder builder
USER builder
WORKDIR /work

CMD ["/bin/bash"]

构建镜像并运行：

docker build --build-arg USER_ID=$(id -u) --build-arg GROUP_ID=$(id -g) \
  -t yocto-builder:kirkstone .

docker run --rm -it \
  -v $PWD/poky:/work/poky \
  -v $PWD/downloads:/work/downloads \
  -v $PWD/sstate-cache:/work/sstate-cache \
  yocto-builder:kirkstone

其中 downloads 与 sstate-cache 必须持久化。前者缓存源码包，后者缓存已编译任务结果，两者复用可将二次构建时间从数小时压缩到十几分钟。

四、持续集成准备与常见误区

CI 阶段应直接复用本地验证过的 Docker 镜像，而不是在 CI 机器上重新 apt install。GitLab CI 的典型配置如下：

build-image:
  stage: build
  image: yocto-builder:kirkstone
  script:
    - cd /work/poky
    - source oe-init-build-env build
    - bitbake core-image-minimal
  artifacts:
    paths:
      - poky/build/tmp/deploy/images/
    expire_in: 1 week
  cache:
    key: yocto-sstate
    paths:
      - downloads/
      - sstate-cache/

环节	关键动作	常见误区
主机配置	调大 inotify、确认磁盘空间	用 4 核 8 GB 机器构建完整镜像，频繁 OOM
依赖安装	按官方列表安装并验证 locale	只装 gcc 和 git，缺少 chrpath、socat 导致打包失败
Docker 化	固定 UID/GID、挂载 downloads 与 sstate	容器内用 root 构建，挂载目录属主错乱
持续集成	镜像版本与 Yocto 版本绑定、缓存 sstate	每次 CI 重新拉取全部源码，构建时间不可控

不要把 downloads 和 sstate-cache 放在容器可写层。容器一旦删除，缓存全部丢失，CI 会退化为“每次全量构建”。

复盘来看，构建环境搭建最容易踩的坑不是技术难度，而是“先跑起来再说”的心态。建议在项目初期就完成三件事：把依赖列表写入 Dockerfile 并提交到仓库；把 downloads 与 sstate-cache 作为独立卷管理；在 CI 中固定镜像 tag，而不是使用 latest。这样，当 BSP 层升级或 Yocto 版本切换时，只需更新镜像 tag，本地与 CI 能同步迁移，量产镜像的构建过程才真正具备可重复性。