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

4. 开发环境搭建

EDK II 的工程化开发离不开一套可复现的构建环境。与普通应用开发不同，UEFI 固件构建同时涉及宿主工具链、目标架构交叉编译、Python 构建脚本、ACPI/ASL 编译器以及平台描述文件（DSC/FDF/DEC）的协同。本节围绕“源码获取—工具链配置—模拟器构建—真实平台构建”这条主线，给出 Windows 与 Linux 双平台的可落地方法。

一、核心原理：EDK II 构建系统的分层结构

EDK II 的构建不是简单的“编译源码”，而是由 BaseTools、构建脚本与平台包三层协作完成。理解这三层，才能定位后续绝大多数构建错误。

BaseTools 层：提供 GenFw、GenFfs、GenFv、Trim、EfiRom 等工具，负责把 PE/COFF 目标文件封装成 FFS/FV，最终生成可烧录固件镜像。
构建脚本层：edksetup 脚本设置工作区环境变量（WORKSPACE、EDK_TOOLS_PATH、PACKAGES_PATH），build 命令解析 DSC/FDF/DEC 并驱动编译。
平台包层：如 OvmfPkg、MdeModulePkg、MdePkg、UefiCpuPkg，提供模块源码、库实例与平台描述文件。

关键点：DSC 决定“编译什么模块、用哪个库实例”，FDF 决定“镜像如何布局”，DEC 声明“包对外暴露哪些头文件与 GUID”。三者缺一不可。

二、源码获取：Windows 与 Linux 的差异处理

edk2 主仓包含大量子模块（如 BaseTools 中的 Brotli、Subhook 等），必须递归拉取，否则构建时会报“找不到头文件”或“子模块为空”。

# Linux / Windows Git Bash 通用
git clone --recursive https://github.com/tianocore/edk2.git
cd edk2
git submodule update --init --recursive

# 若网络受限，可改用镜像并保留子模块
git clone --recursive https://gitee.com/mirrors/edk2.git

Windows 下建议使用 Git for Windows 自带的 Git Bash 执行上述命令，避免 CMD 对符号链接与长路径支持不足。若路径过长，可开启 git config --global core.longpaths true。

三、工具链配置：Linux 与 Windows 对照

Linux 下通常使用 GCC5 工具链，Windows 下可使用 VS2019/VS2022 或 CLANGPDB。无论哪种，都需要先编译 BaseTools，再设置环境变量。

# Linux 环境初始化
export WORKSPACE=$PWD
export PACKAGES_PATH=$WORKSPACE/edk2
export EDK_TOOLS_PATH=$WORKSPACE/edk2/BaseTools
source edk2/edksetup.sh
make -C edk2/BaseTools

# Windows 环境初始化（VS 开发者命令行）
set WORKSPACE=%CD%
set PACKAGES_PATH=%WORKSPACE%\edk2
set EDK_TOOLS_PATH=%WORKSPACE%\edk2\BaseTools
edk2\edksetup.bat Rebuild

项目	Linux	Windows
推荐工具链	GCC5 / CLANGPDB	VS2019 / VS2022 / CLANGPDB
环境脚本	edksetup.sh	edksetup.bat
BaseTools 构建	make -C BaseTools	edksetup.bat Rebuild
ASL 编译器	iasl（需单独安装）	BaseTools 自带 iasl.exe
Python 依赖	python3 + antlr4-python3-runtime	Python 3.x + 同左
常见坑	NASM 版本过低、权限问题	路径含空格、VS 环境未加载

四、模拟器构建：以 OVMF + QEMU 为例

模拟器构建是验证固件逻辑最快的方式。OVMF 是 edk2 官方提供的 UEFI 固件，可直接在 QEMU 中启动，无需真实主板。

# 构建 OVMF（X64）
build -a X64 -t GCC5 -p OvmfPkg/OvmfPkgX64.dsc -b DEBUG

# 产物位置
# Build/OvmfX64/DEBUG_GCC5/FV/OVMF.fd

# QEMU 启动
qemu-system-x86_64 -bios Build/OvmfX64/DEBUG_GCC5/FV/OVMF.fd \
  -m 2048 -serial stdio -net none

若需要调试，可加入 -s -S 让 QEMU 等待 GDB 连接，再用 target remote :1234 加载符号，即可在 DXE 阶段单步跟踪。

五、真实平台构建：从 DSC 到可烧录镜像

真实平台构建与模拟器的最大区别在于：平台 DSC/FDF 中绑定了芯片组初始化、内存初始化与板级 GPIO 配置。以常见的 X64 平台为例，构建命令与模拟器类似，但输出的是可烧录到 SPI Flash 的完整镜像。

build -a X64 -t GCC5 -p Platform/MyBoard/MyBoardPkg.dsc -b RELEASE

# 典型产物
# Build/MyBoard/RELEASE_GCC5/FV/MYBOARD.fd
# 使用 flashrom 烧录
flashrom -p ch341a_spi -w MYBOARD.fd

真实平台构建前务必确认：FDF 中的 Flash 布局与硬件一致、DSC 中的 Pcd 值匹配板级参数、SEC/PEI 阶段的内存初始化代码与芯片组匹配。任何一项不一致都可能导致“上电无输出”。

六、常见误区与复盘

误区一：只编译不清理。切换工具链或修改 DSC 后未执行 build clean，导致旧目标文件混入，出现难以定位的链接错误。
误区二：忽略子模块。BaseTools 子模块缺失时，构建会报“Brotli 头文件不存在”，需重新执行 git submodule update --init --recursive。
误区三：Windows 路径含空格。WORKSPACE 或 EDK_TOOLS_PATH 含空格会导致 BaseTools 调用失败，建议放在 D:\edk2 这类短路径下。
误区四：模拟器通过即认为真实平台通过。模拟器不覆盖芯片组初始化与电源时序，真实平台仍需单独验证。

建议在团队内固化一份环境初始化脚本，把源码路径、工具链版本、Python 依赖与 BaseTools 构建步骤全部脚本化。这样新成员加入时只需执行一条命令，即可获得与 CI 一致的构建环境，从源头减少“我这里能编过”的协作成本。