构建和安装适用于 libvirt QEMU 虚拟机的 LineageOS

已知问题

请注意以下 virtio_* 目标尚未解决的已知问题列表

简介

如果您想在没有物理设备的情况下使用 LineageOS、测试通用系统镜像 (GSI) 或体验底层 Android 组件，这是一个不错的选择。

这些说明将帮助您构建适用于在 libvirt QEMU 虚拟机中运行的 LineageOS 镜像。

您需要的

让我们开始吧！

构建 LineageOS

安装 platform-tools

如果您之前没有安装 adb 和 fastboot，您可以从 Google 下载。解压它，运行

unzip platform-tools-latest-linux.zip -d ~

现在您必须将 adb 和 fastboot 添加到您的 PATH。打开 ~/.profile 并添加以下内容

# add Android SDK platform tools to path
if [ -d "$HOME/platform-tools" ] ; then
    PATH="$HOME/platform-tools:$PATH"
fi

然后，运行 source ~/.profile 以更新您的环境。

安装构建包

构建 LineageOS 需要几个软件包。您可以使用您的发行版的软件包管理器安装这些软件包。

要构建 LineageOS，您需要

自 LineageOS 22.0 起，virtio_* 目标使用基于上游仓库的 Mesa。要为 virtio_* 目标构建 LineageOS 22.0 及更高版本，您还需要

对于 Ubuntu 23.10 (mantic)，请从 23.04 (lunar) 安装 libncurses5，如下所示

wget https://archive.ubuntu.com/ubuntu/pool/universe/n/ncurses/libtinfo5_6.3-2_amd64.deb && sudo dpkg -i libtinfo5_6.3-2_amd64.deb && rm -f libtinfo5_6.3-2_amd64.deb
wget https://archive.ubuntu.com/ubuntu/pool/universe/n/ncurses/libncurses5_6.3-2_amd64.deb && sudo dpkg -i libncurses5_6.3-2_amd64.deb && rm -f libncurses5_6.3-2_amd64.deb

而对于早于 23.10 (mantic) 的 Ubuntu 版本，只需安装

此外，对于早于 20.04 (focal) 的 Ubuntu 版本，还要安装

而对于早于 16.04 (xenial) 的 Ubuntu 版本，请安装

Java

不同版本的 LineageOS 需要不同版本的 JDK（Java 开发工具包）。

* Ubuntu 16.04 及更高版本在标准软件包存储库中没有 OpenJDK 1.7。请参阅 Ask Ubuntu 问题“如何在 Ubuntu 16.04 或更高版本上安装 openjdk 7？”。请注意，使用 PPA openjdk-r 的建议已过时（PPA 从未更新其提供的 openjdk-7-jdk，因此缺乏安全修复）；即使它是最受赞同的答案，也请跳过该答案。

Python

不同版本的 LineageOS 需要不同的默认 Python 版本。

如果您的默认版本是 python3，但您正在构建需要 python2 的分支，则有多种方法可以使用它，例如 手动创建符号链接或为其创建 virtualenv。我们推荐后者

使用 virtualenv --python=python2 ~/.lineage_venv 一次性生成 virtualenv。之后，在每个需要 python2 作为默认版本的终端中，通过运行 ~/.lineage_venv/bin/activate 激活它。

路径 ~/.lineage_venv 可以自由选择，这只是一个示例！

创建目录

您需要在构建环境中设置一些目录。

要创建它们

mkdir -p ~/bin
mkdir -p ~/android/lineage

~/bin 目录将包含 git-repo 工具（通常命名为“repo”），~/android/lineage 目录将包含 LineageOS 的源代码。

安装 repo 命令

输入以下内容以下载 repo 二进制文件并使其可执行（可运行）

curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
chmod a+x ~/bin/repo

将 ~/bin 目录添加到您的执行路径中

在最新版本的 Ubuntu 中，~/bin 应该已经在您的 PATH 中。您可以通过使用文本编辑器打开 ~/.profile 并验证以下代码是否存在来检查这一点（如果缺少则添加它）

# set PATH so it includes user's private bin if it exists
if [ -d "$HOME/bin" ] ; then
    PATH="$HOME/bin:$PATH"
fi

然后，运行 source ~/.profile 以更新您的环境。

配置 git

鉴于 repo 要求您标识自己以同步 Android，请运行以下命令来配置您的 git 身份

git config --global user.email "[email protected]"
git config --global user.name "Your Name"

由于其大小，某些仓库配置为 lfs 或 Large File Storage。为确保您的发行版为此做好准备，请运行

git lfs install

为避免在提交消息中重复 Change-Id: 尾部，尤其是在 cherry-picking 更改时，请使 Change-Id: 成为 git 的已知尾部

git config --global trailer.changeid.key "Change-Id"

启用缓存以加速构建

如果您想通过运行 ccache 来加速后续构建，请使用它

export USE_CCACHE=1
export CCACHE_EXEC=/usr/bin/ccache

并将该行添加到您的 ~/.bashrc 文件中。然后，通过键入以下内容来指定您希望 ccache 使用的最大磁盘空间量

ccache -M 50G

其中 50G 对应于 50GB 的缓存。这需要运行一次。25GB-100GB 的任何大小都将显著提高构建速度（例如，典型的 1 小时构建时间可以缩短到 20 分钟）。如果您只为一个设备构建，25GB-50GB 就足够了。如果您计划为多个不共享相同内核源代码的设备构建，则目标是 75GB-100GB。此空间将永久占用您的驱动器，因此请考虑这一点。

您还可以启用可选的 ccache 压缩。虽然这可能会导致轻微的性能下降，但它增加了缓存中可以容纳的文件数量。要启用它，请运行

ccache -o compression=true

初始化 LineageOS 源代码仓库

以下分支当前支持为 libvirt QEMU 虚拟机构建镜像

输入以下内容以初始化仓库

cd ~/android/lineage
repo init -u https://github.com/LineageOS/android.git -b lineage-22.1 --git-lfs --no-clone-bundle

下载源代码

要开始将源代码下载到您的计算机，请键入以下内容

repo sync

LineageOS 清单包含 repo 的合理默认配置，我们强烈建议您使用（即不要向 sync 添加任何选项）。作为参考，我们的默认值是 -j 4 和 -c。-j 4 部分意味着四个并发线程/连接。如果您在同步时遇到问题，您可以将其降低到 -j 3 或 -j 2。另一方面，-c 使 repo 仅拉取当前分支，而不是 GitHub 上可用的所有分支。

选择要构建的目标

设置环境

source build/envsetup.sh

默认情况下使用 Virtual A/B 分区方案。如果您想改用非 A/B 分区方案（需要更少的空间），请在每次构建之前运行以下命令

export AB_OTA_UPDATER=false

要构建下表中的目标之一，请运行以下命令

breakfast <Target>
目标 架构 类型
virtio_arm64 ARM (32 位 + 64 位) PC
virtio_arm64only ARM (仅 64 位) PC
virtio_x86_64 x86 (仅 64 位) PC
virtio_x86_64_car x86 (仅 64 位) 车载
virtio_x86_64_tv x86 (仅 64 位) Android TV

或者，运行以下命令来构建子目标之一

breakfast <Main target>
breakfast <Sub target>
主目标 子目标 架构 类型 可用版本
virtio_arm64only virtio_arm64only_16k ARM (仅 64 位，16KB 页面大小) PC LineageOS 22.0
virtio_arm64only virtio_arm64only_go ARM (仅 64 位) Android Go LineageOS 21.0
virtio_x86_64 virtio_x86_64_go x86 (仅 64 位) Android Go LineageOS 21.0

开始构建

开始构建了！

要构建安装镜像

m espimage-install

如果构建完成且没有错误，安装镜像将出现在 out/target/product/<target>/lineage-*-20250408-UNOFFICIAL-<target>.img。

(可选) 或者，您也可以构建 ISO9660 格式的安装镜像（仅适用于 x86_64 目标）

m isoimage-install

如果构建完成且没有错误，安装镜像将出现在 out/target/product/<target>/lineage-*-20250408-UNOFFICIAL-<target>.iso。

现在，将安装镜像传输到您希望在其上运行的设备。

安装虚拟机软件

在 Debian / Ubuntu 上，安装 virt-manager 软件包将安装 GUI 管理器和 libvirt QEMU 虚拟机的所有必要依赖项。

运行以下命令进行安装

sudo apt install virt-manager

此外，根据您的构建架构安装以下软件包

Android 架构 要安装的软件包
ARM (32 位 + 64 位) qemu-system-arm qemu-efi-aarch64
ARM (仅 64 位) qemu-system-arm qemu-efi-aarch64
x86 (仅 64 位) qemu-system-x86 ovmf

使用 virt-manager 创建和配置虚拟机

启动 virt-manager，方法是从应用程序菜单打开“虚拟机管理器”，或在终端中键入它。

虚拟机创建和常用配置

首先，通过切换 编辑 > 首选项 > 常规 > 启用 XML 编辑 来启用 XML 编辑。

接下来，通过从菜单栏中选择 文件 > 新建虚拟机 来创建新的虚拟机。将出现“新建虚拟机”窗口。

步骤 1

选择 手动安装，展开 架构选项，然后选择为构建镜像选择正确的架构，如下所述

Android 架构 QEMU 架构
ARM (32 位 + 64 位) aarch64
ARM (仅 64 位) aarch64
x86 (仅 64 位) x86_64

选择正确的架构后，单击 前进。

步骤 2

在 选择您要安装的操作系统 字段中搜索并选择 Generic Linux 2022。单击 前进。

步骤 3

指定您愿意分配给虚拟机的 CPU 核心数和内存大小。最小 RAM 要求为 2048 MiB。填写这些字段后，单击 前进。

步骤 4

取消选中 为此虚拟机启用存储，因为我们稍后将为此虚拟机设置存储。完成此操作后，单击 前进。

步骤 5

指定您要分配给虚拟机的名称，并在 网络选择 菜单中选择您希望连接到的网络，单击 前进。

选择 芯片组 或 机器 和 固件

将弹出虚拟机配置窗口。

在 概述 选项卡上，根据架构选择 芯片组 或 机器 和 固件 类型，如下所述

Android 架构 芯片组 / 机器 固件
ARM (32 位 + 64 位) virt (必需) 自定义：/usr/share/AAVMF/AAVMF_CODE.no-secboot.fd
ARM (仅 64 位) virt (必需) 自定义：/usr/share/AAVMF/AAVMF_CODE.no-secboot.fd
x86 (仅 64 位) Q35 (推荐) BIOS 或 UEFI x86_64：/usr/share/OVMF/OVMF_CODE_4M.fd

单击 应用。

在 内存 选项卡上，切换 启用共享内存，单击 应用。

创建虚拟磁盘

  1. 单击左下角的 添加硬件，将出现新窗口 添加新虚拟硬件。
  2. 选择 存储，在 设备类型 菜单上选择 磁盘设备，并在 总线类型 菜单上选择 VirtIO。
  3. 填写磁盘大小。
  4. 单击 完成。
  5. 重复上述步骤，添加用于存储 userdata 的磁盘。建议最小大小为 2 GiB。

附加安装镜像

  1. 单击左下角的 添加硬件，将出现新窗口 添加新虚拟硬件。
  2. 选择 存储。
  3. 如果安装镜像为 ISO9660 格式，请在 设备类型 菜单上选择 CD-ROM 设备，并在 总线类型 菜单上选择 SATA；否则，在 设备类型 菜单上选择 磁盘设备，并在 总线类型 菜单上选择 USB。
  4. 展开 高级，切换 只读。
  5. 选择 选择或创建自定义存储，选择安装镜像。
  6. 单击 完成。
  7. 在 启动选项 选项卡上，切换 SATA CD-ROM 1 或 USB 磁盘 1，单击 应用。

配置虚拟机输入

平板电脑或鼠标

如果您正在使用触摸屏或远程控制虚拟机，请使用平板电脑输入设备。

自 LineageOS 22 起，所有场景都支持平板电脑输入设备。使用平板电脑输入设备，您可以跨越边界移动鼠标光标，而无需抓取鼠标光标。但是，在早于 LineageOS 22.2 的版本中，恢复模式不支持平板电脑输入设备。

否则，请使用鼠标输入设备。

使用鼠标输入设备时，您必须单击显示区域以将鼠标光标抓取到虚拟机中，并按 Ctrl+Alt 以从虚拟机释放鼠标光标。恢复模式也支持它。

键盘

始终需要键盘。确保虚拟机硬件中包含键盘。

配置虚拟机图形

视频

  1. 如果缺少 视频 选项卡，请使用左下角的 添加硬件 按钮添加它。
  2. 在 视频 选项卡上，在 型号 菜单上选择 Virtio，单击 应用。
  3. 如果设备和远程桌面应用程序支持 3D 加速图形，请切换 3D 加速，单击 应用。
  4. (可选) 要指定自定义显示分辨率，请切换到 XML 选项卡，插入 <resolution x="<Width>" y="<Height>"/>，像这样
     <video>
 <model type="virtio" heads="1" primary="yes">
     <acceleration accel3d="yes"/>
     <resolution x="1920" y="900"/>
 </model>
 <alias name="video0"/>
 <address type="pci" domain="0x0000" bus="0x00" slot="0x01" function="0x0"/>
 </video>

显示

  1. 如果缺少 显示 选项卡，请使用左下角的 添加硬件 按钮添加它。
  2. 打开 显示 选项卡。
  3. 在 监听类型 菜单上选择 无。
  4. 如果在 视频 选项卡上启用了 3D 加速，请切换 OpenGL，并从下面的菜单中选择一个活动的主机显卡。
  5. 单击 应用。

配置虚拟机声音

建议使用声卡型号 AC97（这是默认设置）。其他型号也可能有效，但可能存在问题。

创建新的虚拟机

单击左上角的 开始安装，安装过程将继续进行，然后虚拟机将首次启动。

将 LineageOS 安装到虚拟机

虚拟机应启动到安装镜像的启动管理器菜单。

  1. 使用箭头键选择第一个选项，类似于 Install LineageOS，然后按 Enter 键。
  2. 虚拟机应进入 LineageOS Recovery。您可以使用箭头键选择一个选项，然后按 Enter 键输入它。
  3. 选择 Factory reset > Format data/factory reset > Format data。
  4. 选择 Apply update > Choose INSTALL > 选择 lineage-*-20250408-UNOFFICIAL-<target>.zip。

恭喜！您现在已在虚拟机中安装了 LineageOS。

您现在可以选择 Reboot system now 以启动到 LineageOS。

在虚拟机内运行 LineageOS

虚拟机应进入 LineageOS 启动菜单。

选择第一个选项（默认情况下应自动选择）以启动 LineageOS。

在虚拟机内运行通用系统镜像

这里我们将使用来自 Android 开源项目网站的 GSI 作为示例。有三种运行方法

动态系统更新

  1. 启动到启动器后，打开设置应用。
  2. 启用 开发者选项，返回主页，导航到 系统 > 开发者选项。
  3. 打开 DSU 加载器，选择您要安装的 DSU 软件包，单击 同意。
  4. 安装完成后，您可以通过单击 动态系统更新 通知上的 重启 来重启到 GSI。

将 GSI 镜像指定为第三个 VirtIO 磁盘

  1. 从 通用系统镜像版本 下载 GSI 镜像存档（Android 版本等于或高于且架构匹配）。
  2. 从下载的存档中解压 system.img。
  3. 将 system.img 添加为第三个 VirtIO 磁盘。
  4. 将虚拟机启动到恢复模式，执行恢复出厂设置。
  5. 重启到启动菜单，选择 高级选项 > 从 /dev/block/vdc 启动 GSI，使用 LineageOS * (内核版本 *)。

将 GSI 镜像刷入 system 逻辑分区

  1. 从 通用系统镜像版本 下载 GSI 镜像存档（Android 版本等于或高于且架构匹配）。
  2. 从下载的存档中解压 system.img。
  3. 将虚拟机启动到恢复模式，并执行恢复出厂设置。
  4. 通过选择 高级 > 进入 fastboot 进入 fastbootd 模式。
  5. 删除不需要的逻辑分区，并使用 fastboot 刷入 GSI 镜像
     fastboot -s tcp:<IPv4 address that shown on menu header> delete-logical-partition product
 fastboot -s tcp:<IPv4 address that shown on menu header> delete-logical-partition product_a
 fastboot -s tcp:<IPv4 address that shown on menu header> delete-logical-partition product_b
 fastboot -s tcp:<IPv4 address that shown on menu header> delete-logical-partition system_ext
 fastboot -s tcp:<IPv4 address that shown on menu header> delete-logical-partition system_ext_a
 fastboot -s tcp:<IPv4 address that shown on menu header> delete-logical-partition system_ext_b
 fastboot -s tcp:<IPv4 address that shown on menu header> flash system <path to GSI system.img>
  6. 重启到启动菜单，继续第一个选项。

高级用户详情

ADB 连接

这些目标通过以太网或 VirtIO VSOCK 提供 ADB 连接。

要通过以太网连接，请运行以下命令

adb connect <IPv4 address of the virtual machine>

要通过 VirtIO VSOCK 连接，请在虚拟机启动之前添加 VirtIO VSOCK 虚拟硬件，并运行以下命令

adb connect vsock:<Guest CID>:5555

Fastbootd 连接

这些目标通过以太网提供 fastbootd 连接。

以下是如何通过以太网使用 fastbootd

fastboot -s tcp:<IPv4 address that shown on menu header> [fastboot command...]

GPU 直通（对于 virtio_x86_64 目标）

自 LineageOS 22.1 起，virtio_x86_64 目标支持在正常启动模式下通过 GPU 直通在连接到真实 GPU 的显示器上直接显示。

目前，仅支持 Intel GPU（iGPU 或 dGPU）。

Intel Broadwell 及更高版本的 GPU 需要额外的构建依赖项

将 GPU 添加到虚拟机

  1. 在主机 PC 的 BIOS 设置中启用 VT-d (Intel) 或 IOMMU (AMD)。
  2. 阻止任何驱动程序在主机操作系统上使用 GPU。
  3. 使用包含主机操作系统上 GPU 的 PCI ID 的 ids 参数探测 vfio-pci 内核模块。
  4. 在 PCI 总线 0x00 插槽 0x1e 上将 GPU 的 PCI 设备添加到虚拟机。

启动带有 GPU 直通的虚拟机

在启动菜单上，进入 高级选项 (virtio_x86_64 specific) 子菜单，然后选择与 GPU 和/或您的用例对应的选项。

如果在 GPU 直通模式下某些与图形相关的内容无法工作，您可以首先尝试在 SELinux 宽容模式下启动，方法是在启动前在启动菜单上选择 设置 > SELinux > 宽容。

在恢复模式下安装可刷写的 ZIP 文件

ADB 侧载

自 LineageOS 22.1 起，这些目标支持 ADB 侧载（通过以太网或 VirtIO VSOCK）。

要建立连接，请参阅 ADB 连接。

将目录导出为 VirtioFS 共享

添加 文件系统 虚拟硬件，在 源路径 框中指定包含自定义可刷写 ZIP 文件的目录，并在 目标路径 框中指定 share。

在恢复模式下，进入 Apply update > Choose from virtiofs，选择您要安装的自定义可刷写 ZIP 文件。

插入 USB 驱动器

将可刷写的 ZIP 文件放入 USB 驱动器中，并将 USB 驱动器挂载到虚拟机。

在恢复模式下，选择 Apply update，USB 驱动器的卷应出现在菜单上。选择相应的卷，然后选择您要安装的自定义可刷写 ZIP 文件。

文本控制台