📚 课程目录第4章 QEMU源码编译与安装

4. QEMU 源码编译与安装：从源码编译 QEMU（版本 7.2+）

QEMU 是搭建虚拟化调试环境的核心组件。为了支持 PCIe 设备模拟、virtio 前端驱动以及 GDB 源码级调试，建议从源码编译 QEMU 7.2 及以上版本。本章将详细讲解编译配置、构建流程与安装验证步骤。

4.1 为什么选择源码编译

发行版自带的 QEMU 通常版本较旧，且默认编译选项可能未开启 PCIe 扩展、GDB stub 或特定设备模型。源码编译可以精确控制以下特性：

特性	发行版默认	源码编译（推荐）
PCIe 支持（pcie-root-port）	部分开启	完全开启
virtio-net / virtio-pci	通常开启	可定制设备列表
GDB 调试 stub	开启但可能被剥离	强制保留
设备模型数量	有限	全量编译
调试符号（-g）	无	可加入

建议： 使用 QEMU 7.2.0 或 8.0.0 稳定版。7.2 引入了更完善的 PCIe 拓扑模拟，对网卡驱动调试非常友好。

4.2 编译前置依赖

在编译前需要安装基础构建工具和 QEMU 依赖库。以下为 Ubuntu 22.04/24.04 环境下的安装命令：

sudo apt update
sudo apt install -y \
    build-essential \
    git \
    python3 \
    python3-pip \
    ninja-build \
    pkg-config \
    libglib2.0-dev \
    libpixman-1-dev \
    libslirp-dev \
    libfdt-dev \
    libaio-dev \
    libcap-ng-dev \
    libattr1-dev \
    libbrlapi-dev \
    libsasl2-dev \
    libseccomp-dev \
    libssh-dev \
    libzstd-dev \
    liblzo2-dev \
    libbz2-dev \
    libgcrypt20-dev \
    libgnutls28-dev \
    libnfs-dev \
    libusb-1.0-0-dev \
    libspice-server-dev \
    libvirglrenderer-dev \
    libdrm-dev \
    libgbm-dev \
    libepoxy-dev \
    libsdl2-dev \
    libgtk-3-dev \
    libvte-2.91-dev \
    libxkbcommon-dev \
    libpipewire-0.3-dev \
    libjack-jackd2-dev \
    libpulse-dev \
    libasound2-dev \
    libcacard-dev \
    libu2f-server-dev \
    libu2f-host-dev \
    libusbredirparser-dev \
    libspice-protocol-dev \
    libvirglrenderer-dev \
    libdaxctl-dev \
    libndctl-dev \
    libkeyutils-dev \
    libudev-dev \
    libjson-c-dev \
    libcurl4-openssl-dev \
    libbpf-dev \
    libselinux1-dev \
    libnuma-dev \
    libpmem-dev \
    libdaxctl-dev \
    libslirp-dev

注意： 如果编译时提示缺少某个库，请根据错误信息单独安装对应的 -dev 包。ninja 构建系统需要 Python 3.6+ 支持。

4.3 下载 QEMU 源码

从 QEMU 官方 Git 仓库或发布页面获取源码：

# 方式一：克隆 Git 仓库（推荐，方便切换分支）
git clone https://gitlab.com/qemu-project/qemu.git
cd qemu
git checkout stable-7.2

# 方式二：直接下载 tar 包
wget https://download.qemu.org/qemu-7.2.0.tar.xz
tar -xf qemu-7.2.0.tar.xz
cd qemu-7.2.0

4.4 配置编译选项

QEMU 使用 configure 脚本进行构建配置。以下配置开启 PCIe、virtio、GDB 调试以及常用设备模型：

mkdir build && cd build

../configure \
    --target-list=x86_64-softmmu \
    --enable-debug \
    --enable-debug-info \
    --enable-gdb \
    --enable-virtio \
    --enable-pcie \
    --enable-slirp \
    --enable-kvm \
    --enable-spice \
    --enable-gtk \
    --enable-sdl \
    --enable-vnc \
    --enable-curses \
    --enable-tcg \
    --enable-fdt \
    --enable-linux-aio \
    --enable-libnfs \
    --enable-bzip2 \
    --enable-lzo \
    --enable-snappy \
    --enable-zstd \
    --enable-seccomp \
    --enable-libssh \
    --enable-gnutls \
    --enable-numa \
    --enable-pmem \
    --enable-virglrenderer \
    --enable-opengl \
    --enable-xkbcommon \
    --enable-pa \
    --enable-alsa \
    --enable-pipewire \
    --enable-jack \
    --enable-usb-redir \
    --enable-libusb \
    --enable-usb-host \
    --enable-smartcard \
    --enable-u2f \
    --enable-curl \
    --enable-bpf \
    --enable-rbd \
    --enable-vhost-user \
    --enable-vhost-kernel \
    --enable-vhost-net \
    --enable-vhost-vsock \
    --enable-vhost-user-blk-server \
    --enable-virtfs \
    --enable-mpath \
    --enable-xfsctl \
    --enable-modules \
    --enable-module-upgrades \
    --audio-drv-list=pa,alsa,pipewire,jack \
    --extra-cflags="-g -O0"

  关键选项说明：
  --target-list=x86_64-softmmu：仅编译 x86_64 系统模拟，减少编译时间。
--enable-debug 和 --enable-debug-info：保留调试符号。
--enable-gdb：启用 GDB stub，支持远程调试客户机。
--enable-virtio 和 --enable-pcie：显式开启 virtio 和 PCIe 支持。
--extra-cflags="-g -O0"：关闭优化，保留完整调试信息。

4.5 编译与安装

配置完成后，使用 ninja 进行并行编译，然后安装到系统目录：

# 编译（使用 -j 参数加速，根据 CPU 核心数调整）
ninja -j$(nproc)

# 安装到 /usr/local 目录
sudo ninja install

编译过程通常需要 10~30 分钟，取决于机器性能。安装完成后，QEMU 可执行文件位于 /usr/local/bin/ 下。

4.6 验证安装

通过以下步骤验证 QEMU 是否正确安装并包含所需特性：

4.6.1 版本检查

qemu-system-x86_64 --version

输出示例：

QEMU emulator version 7.2.0 (v7.2.0)
Copyright (c) 2003-2022 Fabrice Bellard and the QEMU Project developers

4.6.2 PCIe 设备列表检查

qemu-system-x86_64 -M q35 -device help | grep -i pcie

应能看到 pcie-root-port、pcie-pci-bridge 等设备。

4.6.3 virtio 设备列表检查

qemu-system-x86_64 -M q35 -device help | grep -i virtio

应包含 virtio-net-pci、virtio-blk-pci、virtio-scsi-pci 等。

4.6.4 GDB stub 功能验证

qemu-system-x86_64 -M q35 -s -S -nographic -vnc :0 \
    -drive file=/dev/null,format=raw,if=none,id=null \
    -device virtio-net-pci,netdev=net0 \
    -netdev user,id=net0 \
    -serial none \
    -parallel none \
    -monitor none \
    -qmp tcp:127.0.0.1:4444,server,nowait &
sleep 2
echo "QEMU started with GDB stub on port 1234"
# 检查端口是否监听
ss -tlnp | grep 1234

如果看到 1234 端口被 qemu 进程监听，说明 GDB stub 正常工作。

4.7 编译配置与特性矩阵

下表总结了不同编译配置对应的功能支持情况：

配置选项	功能	调试网卡驱动必要性
`--enable-debug`	启用 QEMU 内部断言和调试日志	高
`--enable-gdb`	GDB stub 远程调试	高
`--enable-virtio`	virtio 设备支持	高
`--enable-pcie`	PCIe 总线与设备模拟	高
`--enable-kvm`	KVM 硬件加速	中
`--enable-slirp`	用户态网络栈	中
`--extra-cflags="-g -O0"`	保留完整调试符号，关闭优化	高

4.8 QEMU 编译与调试架构图

下图展示了从源码编译到调试环境搭建的整体架构：

4.9 常见编译问题与解决

错误信息	原因	解决方法
`ERROR: glib-2.56 gthread-2.0 is required to compile QEMU`	glib 版本过低或未安装	`sudo apt install libglib2.0-dev`
`ERROR: pixman >= 0.21.8 required`	pixman 库缺失	`sudo apt install libpixman-1-dev`
`ERROR: ninja not found`	ninja 构建工具未安装	`sudo apt install ninja-build`
`ERROR: slirp not found`	slirp 库缺失	`sudo apt install libslirp-dev`
`../configure: line 86: python3: command not found`	Python 3 未安装	`sudo apt install python3`

4.10 编译后目录结构

编译完成后，关键文件分布如下：

/usr/local/bin/
├── qemu-system-x86_64      # 主模拟器
├── qemu-img                # 磁盘镜像工具
├── qemu-io                 # 块设备 I/O 测试
├── qemu-nbd                # 网络块设备
└── qemu-storage-daemon     # 存储守护进程

/usr/local/share/qemu/
├── bios-256k.bin           # BIOS 固件
├── edk2-x86_64-code.fd     # UEFI 固件
├── kvmvapic.bin            # KVM vAPIC
├── linuxboot.bin           # Linux 启动
├── multiboot.bin           # Multiboot
├── pxe-e1000.rom           # PXE ROM
├── vgabios.bin             # VGA BIOS
└── virtio-net.rom          # virtio-net ROM

提示： 如果后续需要调试网卡驱动，建议保留编译目录中的 build 文件夹，其中包含完整的调试符号文件（.o、.a），便于使用 GDB 跟踪 QEMU 设备模拟代码。