Android源码第一章:AOSP 源码入门——让一次修改真正跑进系统

31 阅读29分钟

从一行日志出发,走通源码到运行系统的路径。

第一次学习 Android 源码,最容易卡住的往往是几个很具体的问题:需要什么样的电脑?源码从哪里下载?下载后这么多目录应该先看哪个?找到一个 Java 文件后,又怎样把它编译进系统?

源码从工作站进入运行系统

1.1 准备 Linux 环境与基础工具

操作前需会使用终端和基本文件命令。下文命令后的输出描述为预期结果,历史实测另行注明。

学习源码先要有一台能存放、构建和运行它的工作站。本节只准备工作环境,不开始编译;完成后应能确认系统、资源与基础工具,并知道后续文件保存在哪里。

先区分工作站与 Android 设备

执行下载、编辑和编译的电脑称为 Host,也就是工作站;生成的 Android 系统运行于 Target,即目标设备。本文先在 Linux Host 上构建,再使用虚拟设备运行 Target。它们可以位于同一台物理电脑中,但不是同一个运行环境。

后文没有 adb 前缀的命令在 Host 的 Bash 终端执行;adb ... shell 后面的命令在 Android 设备中执行。现在还没有启动设备,先完成 Host 准备。

为什么先检查系统 内存和磁盘

构建 Android 需要处理大量源文件、中间文件与镜像,CPU 影响并发计算,内存影响多个任务能否同时工作,磁盘既保存源码也保存构建结果。只估计源码下载大小,容易在编译中途用完空间。

官方当前列出的要求包括 64 位 x86 工作站、64 位 Linux、至少 400 GB 空闲磁盘和 64 GB RAM。本文使用 Ubuntu 作为命令示例;资源要求应按所学 Android 分支核对。官方环境要求

工作站的磁盘和内存预算

先执行以下检查,不需要源码已经存在:

uname -m
cat /etc/os-release
nproc
free -h
df -h "$HOME"
bash --version

uname 的架构应与所选 Host 工具匹配,本文预期为 x86_64;os-release 显示发行版;nproc 显示逻辑 CPU 数;free 和 df 分别看可用内存与所在分区空间。这里检查 HOME 所在分区,源码放在其他磁盘时改查对应挂载点。Bash 用于后续环境脚本和日志记录命令。

并发不是越高越好。后面完整构建先使用 -j2,用于限制部分构建任务的并发;即使并发较低,单个任务仍可能大量占用内存。Swap 通过换出缓解部分内存压力,延迟和带宽与物理内存不同,不能把容量简单相加来判断是否满足构建要求。

安装基础依赖并确认工具可用

Ubuntu 新环境可安装下面的依赖;已有环境先检查缺失项。它们提供 Git、编译所需的基础系统库和工具、压缩与 XML 处理等能力;ripgrep 用于后文搜索源码。apt 命令会改变 Host 软件包。

sudo apt-get update
sudo apt-get install git-core gnupg flex bison build-essential zip curl \
  zlib1g-dev libc6-dev-i386 x11proto-core-dev libx11-dev lib32z1-dev \
  libgl1-mesa-dev libxml2-utils xsltproc unzip fontconfig repo ripgrep
git --version
python3 --version
repo version
rg --version

预期 Git、Python、Repo launcher 和 rg 均能输出版本信息;源码尚未初始化时,Repo 工具本体的信息可能还未齐全,下载后再检查一次。软件包名称随发行版可能不同,按实际缺包信息处理。

当前发布分支带有部分预编译构建工具,例如 JDK。Host 的基础依赖与源码树里的预编译工具是两类材料,不必一上来手动安装旧教程中的全部 Java 工具链。官方依赖与预编译工具说明

约定源码路径与操作记录位置

后续步骤在同一个 Host Bash 终端中连续执行。先定义源码位置,再为本次学习建立独立记录目录:

chapter1_top="$HOME/aosp"
chapter1_run=$(mktemp -d "$HOME/aosp-chapter1.XXXXXX")
printf 'source=%s\nrecord=%s\n' "$chapter1_top" "$chapter1_run"

$HOME 是当前用户主目录;chapter1_top 指向将要下载或已经存在的源码;mktemp 创建唯一记录目录。现在不要求源码目录存在,所以先不 cd 进去。记下输出的 record 路径,后续日志、备份与虚拟设备数据保存在那里。

已有源码时,把第一行改成实际路径。换终端后需要重新设置这些变量,并把 chapter1_run 设为同一个记录目录;再运行一次 mktemp 会新建另一个目录。本文默认构建输出在源码下的 out,改变 OUT_DIR 后需要同步调整后面的显式工具路径。

虚拟化检查放在什么时候

下载和编译本身不依赖 KVM。后面要运行 x86_64 虚拟设备时,再检查 Host 是否提供硬件虚拟化接口:

id
ls -l /dev/kvm
test -r /dev/kvm && test -w /dev/kvm
printf 'kvm_access_check=%s\n' "$?"

id 显示用户与组,ls 显示设备权限,最后为 0 表示当前用户通过读写权限检查。设备不存在或无权限时,核对 BIOS/UEFI 虚拟化、Host 支持与组权限;启动前还要使用运行器的加速检查。此处先知道运行需要这项条件即可,1.6 再使用它。

至此,Host 工具、存储位置和记录目录已准备好,下一步才开始获取源码。

1.2 下载 AOSP 源码并固定版本

源码不是一个普通压缩包。先理解下载工具管理的对象,再执行初始化和同步,最后保存当前版本。已有源码时可跳过新目录中的 init/sync,直接核实工作区,避免重复下载。

先理解项目与清单的关系

AOSP 不是一个装着全部代码的普通 Git 仓库。frameworks/base、build/soong、packages/apps/Settings 等目录分别属于不同项目,可以拥有不同的提交历史。进入其中一个项目运行 Git,只会操作这个项目。

Repo 在 Git 之上协调多个项目。manifest 则告诉 Repo:项目从哪里下载、放在哪里、检出哪个 revision。Repo 相当于执行统一操作的工具,manifest 是操作依据;真正的源文件与提交仍由 Git 管理。官方工具说明

初始化工作区并同步项目

创建新工作区并初始化。repo init 主要初始化 Repo 与 manifest;大规模项目下载在 sync 阶段发生。

mkdir -p "$chapter1_top"
cd "$chapter1_top"
repo init -u https://android.googlesource.com/platform/manifest \
  -b android-latest-release --partial-clone --no-use-superproject

-u 指定 manifest 仓库,-b 选择 manifest 分支或标签;partial clone 减少初始获取的部分 Git 对象,后续读取仍可能触发下载;no-use-superproject 按该官方流程禁用 superproject 模式。预期出现初始化完成消息和 .repo 目录,此时并不表示全部源文件已就绪。官方下载流程

接着同步项目,并把输出和退出状态保存在 1.1 的记录目录:

set -o pipefail
repo sync -c -j4 2>&1 | tee "$chapter1_run/sync.log"
chapter1_sync_status=("${PIPESTATUS[@]}")
printf 'repo=%s tee=%s\n' "${chapter1_sync_status[0]}" \
  "${chapter1_sync_status[1]}" | tee "$chapter1_run/sync-exit.txt"

-c 限定当前 manifest 分支相关获取,-j4 控制同步并发。管道中 Repo 和 tee 有各自退出码,紧接着保存 Bash 的 PIPESTATUS,避免下一条命令覆盖它。两者均为 0 才表示同步命令和日志保存均成功;若 Repo 非 0,在日志中找失败项目及具体错误,而不只看末尾几行。

新下载的移动分支不保证与本章提交完全相同。若要严格复现已有实验,应在新工作区配置保存的精确 manifest,再补齐本地改动与素材;不要把旧快照直接覆盖进一个仍有开发修改的工作区。

实际踩坑 TLS 与 promisor remote 报错怎样连起来看

以下下载、编译和运行案例来自历史任务记录,所用资源、目标与验证范围在各案例中分别说明。案例来源与证据

现象。 下载 HiKey Kernel 时出现以下两种诊断,原始日志含具体对象哈希,这里只保留关键消息:

GnuTLS, handshake failed: The TLS connection was non-properly terminated.
could not fetch … from promisor remote

原因。 本次工作区启用了 blob:none 部分克隆;某些文件内容需要检出时再下载。promisor remote 是承诺提供缺失对象的远端,所以第二条错误可能是 TLS 中断造成补下载失败的后果,不能仅凭它认定仓库损坏。Git 部分克隆原理

实际踩坑 TLS 与 promisor remote 报错怎样连起来看(过程或对象关系)

处理。 先等原同步退出,检查代理链路,再在 AOSP 根目录单独重试失败项目。下面的 HTTP/1.1 只传给这次命令及其子进程,不改全局 Git 配置:

cd "$chapter1_top"
set -o pipefail
GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=http.version \
GIT_CONFIG_VALUE_0=HTTP/1.1 \
repo sync -c -j1 --retry-fetches=3 --no-tags --no-clone-bundle \
  --no-manifest-update device/linaro/hikey-kernel \
  2>&1 | tee "$chapter1_run/hikey-retry.log"
chapter1_retry_status=("${PIPESTATUS[@]}")
printf 'repo=%s tee=%s\n' "${chapter1_retry_status[0]}" "${chapter1_retry_status[1]}"

关键不是某个 HTTP 参数,而是失败项目能否完成获取与检出。 HTTP/1.1 是连接兼容性排查手段,不能保证所有代理故障消失;仍失败时先处理连接,不盲目增加 http.postBuffer。

历史结果。 后续整树同步中 external/coreboot 也曾出现 TLS 错误,但自动重试后记录了 repo sync has finished successfully,用户同时记录 Repo 退出码为 0。中间出现过 fatal 与整次同步最终失败不是一回事,必须结合最终状态与检出检查判断。

实际踩坑 sync 后目录为空 不一定是部分克隆的正常状态

现象。 下载后的部分目录为空,用户尝试用恢复脚本补回文件。历史检查将 1084 个项目分开看:12 个项目有大量已跟踪文件删除,7 个项目当前提交本来就为空;不能用“所有目录都非空”判断完整性。

原因。 部分克隆减少的是预先获取的对象,成功检出当前版本后,当前提交要求的文件仍应存在。检出被中断、索引异常与提交本来为空,是不同情况。先选日志中的具体失败项目查看:

chapter1_project=prebuilts/sdk
git -C "$chapter1_project" status --short
git -C "$chapter1_project" ls-tree --name-only HEAD | head -20
git -C "$chapter1_project" diff --name-status HEAD --

看 HEAD 期望有什么,再看工作目录缺了什么。 ls-tree 展示当前提交的顶层条目;没有条目可能是空树,还需结合退出状态确认命令本身成功。D 说明跟踪内容存在删除状态,但不能自行判断删除是误删还是主动修改。

处理。 正常重试先用定向 repo sync。历史上,用户已明确“从未修改源码”,且检查确认异常删除,才使用了 -d --force-checkout 重新检出 manifest 指定版本;该选项可能覆盖未提交工作。如今本工程已有产品配置与 Settings 改动,不能照搬当时的全树强制检出命令。应先保存 1.2 的提交、补丁和未跟踪素材,再限定需修复的项目。Repo 参数说明

恢复脚本依据当前 HEAD 或索引恢复删除,不负责重新获取整份 manifest 范围、校正所有项目版本,也可能因部分克隆触发联网。脚本结束不等于整树同步完整。 同理,repo init --no-partial-clone 改变后续策略,不会自动补齐所有已有子仓库的历史对象。

验证。 当时最终同步退出码为 0,随后检查未发现已跟踪文件缺失;剩余 .gradle/、build/ 等生成目录按内容判断,不当作源码损坏。现在自己操作后,也应分别保存同步退出码、失败项目状态与 manifest,不能复用历史结论。

实际踩坑 没有输出与 index.lock 是两类问题

现象一:长时间停在提示行。 历史输出停在 Repo 更新提醒与 Skipping update of local manifest project,看起来没有进展;检查却发现正在处理的项目依次从 libbpf 变为 libusb、licenseclassifier。

判断与处理。 --no-manifest-update 跳过清单项目更新,不是跳过所有源码;静默拉取也可能长时间不打印进度。可以在另一终端看相关进程;下次启动加 -v,不因一段安静输出立刻重启下载:

pgrep -af 'repo/main.py|git fetch|git-remote-https|index-pack'
tail -n 30 "$chapter1_run/sync.log"

进程存在只是线索,还要间隔观察项目、I/O 或日志是否推进;不能反过来把“有 PID”当成永远正常。历史上先用低并发排障,稳定后采用下载 4、检出 2,再尝试下载 8。当前 Repo 的 --jobs-network、--jobs-checkout 需配合 --no-interleaved 才分别生效;按本机 repo help sync 核对,不直接套用旧硬件的并发数字。

现象二:明确报 index.lock 已存在。 GCC 与 misc 子仓库检出失败,历史检查确认是约 8 天前残留、无人使用的锁。这不同于“下载没有输出”。先停止或等现有同步完全退出,再针对一个项目检查:

chapter1_lock_project=prebuilts/misc
chapter1_lock=$(git -C "$chapter1_lock_project" rev-parse \
  --path-format=absolute --git-path index.lock)
stat -- "$chapter1_lock"
fuser -v -- "$chapter1_lock"
pgrep -af 'repo/main.py|git|index-pack'

清理前必须确认没有仍在写这个仓库的进程。 fuser 未报告打开者也不能单独排除进程短暂使用锁。确认残留后仅移走这个旧锁,再重试相应项目;不要对 .repo 或整树批量删除锁。历史后续成功同步恢复了 GCC、misc 和 Clang 的检出。

下载后读一段 manifest

例如,下面从本章提交快照摘出一个 project 元素,省略外围 XML。它是清单数据,不是命令:

<project name="device/generic/goldfish" revision="296e55aa0244e8929e393e00e34471fef2a5d662" upstream="android17-release" dest-branch="android17-release" groups="pdk"/>

name 是远端项目名称。此项没有显式 path,工作区路径采用 name;其他项目也可以用 path 指定不同位置。revision 是要检出的版本,这里已经固定成提交哈希。upstream 和 dest-branch 是相关分支信息,不能替代 revision 中的精确提交。完整工作区应另外保存全部项目的提交快照。

分支 标签 提交分别表示什么

分支名标记一条持续演进的开发线,其指向会变化;标签通常标记发布节点,仍应核实实际解析到的提交;提交哈希标识某个项目的一次具体 Git 提交。android-latest-release 是跟随发布的下载入口,不是永远固定的一份源码。

本文示例的默认 revision 为 android17-release,但只记住这个名字不够。相隔一段时间同步后,各项目可能已经前进。要回答“当时究竟构建了什么”,需保存当时每个项目的提交,以及提交之外的改动。

先核实当前工作区

同步结束后,或者开始检查已有工作区时,运行以下只读命令。路径使用 1.1 中设置的 chapter1_top。

cd "$chapter1_top"
repo list > "$chapter1_run/projects.txt"
repo status > "$chapter1_run/repo-status.txt"
git -C build/make rev-parse HEAD
git -C packages/apps/Settings status --short

projects.txt 回答项目与目录的对应,repo-status.txt 回答本地变化。git -C 指定要操作的 Git 项目,不要求先切换当前目录。status --short 没有输出表示该项目在 Git 所报告的范围内无变化;M 表示修改,?? 表示未跟踪文件。

Repo 中的 NO BRANCH 常表示 detached HEAD,即当前检出直接指向提交。Repo 可以使用这种方式管理项目,不能据此认定同步失败。真正需要编辑某个项目时,可使用 repo start 分支名 项目路径 为它建立开发分支;分支名按自己的任务选择。

历史上 development 在界面里显示“领先远端”,但核对后 HEAD 与 manifest 要求一致,界面比较的是另一条默认分支。判断是否偏离版本应比较 manifest 指定 revision,不直接拿 main 当基准。 .gradle 等未跟踪缓存也不等于已跟踪源码被修改;当时定向清理缓存,没有回退提交。

保存提交 本地改动与素材

在当前 AOSP 根目录执行:

repo manifest -r -o "$chapter1_run/manifest-pinned.xml"
repo diff > "$chapter1_run/local-changes.patch"
repo status > "$chapter1_run/repo-status.txt"

第一份文件固定各项目 Git 提交;第二份保存 Repo 输出的已跟踪文件差异;第三份帮助识别改动归属和未跟踪材料。Repo diff 不是覆盖整个多项目工作区的一条普通 Git patch,不能直接在 AOSP 根目录执行一次 git apply 就恢复全部内容;恢复时应按项目分配差异并核对基线。

未跟踪动画、脚本和二进制素材不在上述补丁里,应根据状态清单另存所需文件,并记录相对路径和摘要。.gradle 缓存与实验依赖素材用途不同,不必把全部缓存当作源码输入。

例如,产品配置中引用的未跟踪开机动画 ZIP 会影响构建结果,却不会出现在固定提交的 manifest 中。保存快照后,还要核对这类素材及其摘要。

本节应该得到什么

你应能拿出项目清单、精确提交快照、本地状态、所需补丁和素材,而不是只说“我下载了 Android 17”。接下来先认识这些项目在磁盘上怎样组织,再进入产品与编译配置。

自测:只保存 manifest-pinned.xml,再把未提交的动画文件删除,能否完全复现旧镜像?不能;快照固定 Git 提交,不包含工作区之外或未提交的素材。

1.3 读懂源码目录并找到第一个模块

现在源码已经出现在磁盘上。先不要急着执行构建命令:我们先回答“哪些目录负责什么”“怎样从一个功能找到源码”“源码文件由哪里声明参与构建”。这一步完成后,编译命令才有具体对象。

先看根目录 区分源码与工作区文件

在 Host 终端进入刚才的源码目录:

cd "$chapter1_top"
pwd
ls -a
repo list -p | sed -n '1,15p'

pwd 确认当前位置,ls -a 同时显示隐藏目录,repo list -p 显示 manifest 管理的项目路径;sed 仅展示前十五项,不表示项目总数。一个顶层目录下面可能包含多个 Git 项目,因此“目录数量”与“项目数量”不同。

下面是本文版本的重点目录示意,省略了其他项目。out 需要经过配置或构建才会生成。

aosp/
├── .repo/               Repo 的 manifest、项目元数据与 Git 对象等
├── build/               构建脚本与构建系统
├── packages/            系统应用、模块与提供者等
├── frameworks/          Framework API、系统服务及 Native 框架
├── system/              基础系统服务、库与工具
├── hardware/            HAL 接口、兼容层及部分设备相关实现
├── art/                 Android Runtime
├── bionic/              C 库、数学库与动态链接器
├── device/              产品与设备配置
├── kernel/              本 manifest 中主要包含 Kernel 相关预编译材料
├── prebuilts/           预编译工具与部分目标产物
├── external/            引入的第三方项目
└── out/                 配置与构建产生的输出

.repo 属于 Repo 的管理数据,out 属于生成结果。后续学习时编辑相应项目内的源码和配置;直接修改 out 中的 APK、生成代码或缓存,可能在下一次构建时被覆盖,也难以通过源码提交复现。

按职责理解当前版本的顶层目录

下表覆盖本文 manifest 中出现的 25 个顶层源码目录。它用于建立位置感,不要求第一次就逐个深入;具体子项目会随版本和 manifest 改变。

目录主要职责开始时怎样使用
packages系统应用、可更新平台模块、Provider 等先找 packages/apps/Settings,认识一个完整系统应用
frameworksFramework API、系统服务、图形和 Binder 等框架实现从 API 类或系统服务入口追踪机制
system基础系统组件、Native 服务、库和命令工具例如 system/core/init 的启动实现
artAndroid Runtime 的运行时、编译与相关工具后续学习执行 Java 字节码与内存管理
libcoreAndroid 核心 Java 类库及配套实现区分标准类库与 Android Framework API
libnativehelperJNI 相关辅助接口与工具阅读 Java 与 Native 交互时定位辅助代码
bionicAndroid 的 C 库、数学库和动态链接器阅读 Native 基础与库加载时使用
hardwareHAL 接口、兼容层和设备相关用户空间实现看 hardware/interfaces;不要把整个目录当作 Linux Driver
device产品、板级与设备相关配置后面查 Goldfish、Cuttlefish 的产品入口
kernel本版本的 Kernel 相关预编译产物等项目先核对实际内容,不能据目录名认定有完整内核源码
bootablerecovery、引导与历史 OTA 相关项目启动、恢复与升级章节再展开
trustyTrusty 安全运行环境相关源码与构建材料安全章节区分 Android 与安全环境的实现边界
build产品构建配置、入口脚本与 Soong 等构建系统后面阅读 envsetup.sh 和 build/soong
prebuilts预编译编译器、Host 工具与部分 Target 产物区分工具本体与要编译的 Android 代码
external第三方库、工具和其他上游项目追踪系统依赖时结合具体项目阅读
toolchain本 manifest 主要包含 PGO profile 等工具链材料实际编译器还需到对应 prebuilts 项目核实
sdkSDK 相关工具、构建和兼容材料不等于工作站上安装的整个 Android SDK
tools开发、签名、测试及设备操作等工具项目按具体工具查询,不把它当作单一模块
development平台开发辅助程序、脚本与资料查找辅助操作和开发示例
developers示例与相关构建项目按示例需要阅读
dalvikDEX 工具、文档及历史相关材料当前运行时重点是 ART,目录保留不等于仍使用 Dalvik VM
ctsCompatibility Test Suite 相关项目学习兼容性验证与对应测试用例
test测试基础设施、VTS 等项目按功能查实际测试入口
platform_testing平台测试、库、脚本与工具查测试组织及性能等场景
pdk平台开发包相关的应用、构建与辅助材料按具体设备开发需要阅读

目录按职责和项目历史组织,不是简单按 Java、C++、Rust 分区。frameworks 中也有 Native 代码,system 中也包含不同语言的实现;同一条功能链会跨过多个目录。AOSP 架构概览

Git 项目 源码文件 构建模块分别是什么

在继续搜索前,先把三个尺度分开:

对象回答的问题Settings 示例
Git 项目哪组文件一起维护版本历史packages/apps/Settings
源码文件某段类、函数或资源在哪里定义src/.../SettingsHomepageActivity.java
构建模块构建系统按什么名称组织源码、依赖与产物Android.bp 声明的 Settings 应用模块

一个 Git 项目可以有多个构建模块,一个模块通常包含许多源码文件。文件存在于项目中,也不表示所有产品都会构建或安装它;后面的产品配置和模块依赖会进一步决定。

Git 项目 源码文件和构建模块的区别

Android.bp 是 Soong 的模块声明文件,Android.mk 是仍在使用的 Make 模块描述文件之一。它们描述模块怎样构建,不是应用运行时配置。init 的 .rc 文件、应用的 AndroidManifest.xml、产品的 .mk 文件则承担另外的职责,不能只看后缀相似就混为一类。

跟着 Settings 找到源码 模块与入口

第一步,看应用项目的顶层内容:

ls packages/apps/Settings
git -C packages/apps/Settings rev-parse --show-toplevel

预期能找到 Android.bp、AndroidManifest.xml、src、res 等。Git 命令显示项目根位置,帮助确认当前位置属于哪个版本管理单位。

第二步,用 rg 查找目标文件。rg --files 用于列出候选路径,-g 限定文件名模式:

rg --files packages/apps/Settings/src -g 'SettingsHomepageActivity.java'
rg --files packages/apps/Settings -g 'Android.bp' -g 'AndroidManifest.xml'

本文版本首页 Activity 位于 src/com/android/settings/homepage/SettingsHomepageActivity.java。目录名说明它属于 Settings 的首页功能,但真正的职责还要看代码与声明。

第三步,在已定位的文件中查具体符号;不必一开始就搜索整棵源码:

rg -n 'class SettingsHomepageActivity|protected void onCreate' \
  packages/apps/Settings/src/com/android/settings/homepage/SettingsHomepageActivity.java
rg -n 'homepage.SettingsHomepageActivity' packages/apps/Settings/AndroidManifest.xml
rg -n 'name: "Settings"|name: "Settings-core"|static_libs:|srcs:' \
  packages/apps/Settings/Android.bp

-n 显示行号。第一条定位类与生命周期入口,第二条定位组件声明,第三条找到应用模块及其源码、依赖声明的位置。搜索结果只是阅读入口,多个匹配不自动构成调用顺序;阅读时需要看所在模块和代码上下文。

现在得到一个初步关系:Java 文件提供行为,AndroidManifest.xml 声明应用组件,Android.bp 把文件和依赖组织成构建模块。后面的 1.7 会回到这些位置,加入一行日志验证它怎样到达运行系统。

再定位一个 Framework 类和一个 Native 实现

为了认识不同目录的职责,尝试定位两个文件:

rg --files frameworks/base/core/java/android/os -g 'Handler.java'
rg --files frameworks/native/libs/binder -g 'IPCThreadState.cpp'

前者位于 Framework 的 Java API 代码区域,后者属于 Native Binder 实现。现在只需要找到并识别它们所在项目,不要求立刻读通机制。ActivityManagerService 的一个重要位置是 frameworks/base/services/core/java/com/android/server/am/ActivityManagerService.java,系统启动的 Native 入口则可从 system/core/init 继续探索。

packages/modules 下的平台模块与 Kernel 的可加载模块也不是同一概念。前者属于平台组件组织与更新范围,后者是内核实现的装载单位;看见 modules 一词时先确认上下文。

从源码位置过渡到编译对象

到这里,应该能独立完成三件事:找到 Settings 的源码文件、定位它的模块声明、确认它属于哪个 Git 项目。接下来才回答“选择哪种产品”“这个产品采用哪些配置”“构建结果写到哪里”。这正是下一节的任务。

1.4 选择产品与构建配置

本章示例采用 Linux x86_64 工作站、android17-release 的固定提交和 SDK Emulator 产品,具体提交列于文末;其他版本需核对对应目录、产品与工具行为。

前面已经找到源码与模块;现在需要告诉构建系统,要把它们组合成哪种 Android 产品。这里的选择影响设备配置、功能开关、调试特征和输出位置。

三个配置回答三个不同问题

配置决定什么本章选择
TARGET_PRODUCT产品模块、设备定义、资源与分区设置sdk_phone64_x86_64
TARGET_RELEASE某组发布配置及相关 feature launch flagsaosp_current
TARGET_BUILD_VARIANT构建及调试特征userdebug

release configuration 不是下载源码时的 Git 分支。前者在同一份源码里选择构建配置,后者决定取得哪个项目版本。aosp_current 是否可用,要在当前产品和分支上查询。

user 面向发布环境,调试访问受限;userdebug 用于设备开发与调试;eng 面向开发迭代,某些优化和调试行为与发布版不同。学习时显式选 userdebug,后续若研究性能,还要说明所用构建类型对测量的影响。官方构建配置说明

加载脚本 查询并选择配置

在同一个 Host Bash 终端执行:

cd "$chapter1_top"
source build/envsetup.sh
lunch --help
list_products > "$chapter1_run/products.txt"
list_releases sdk_phone64_x86_64 > "$chapter1_run/releases.txt"
list_variants
cat "$chapter1_run/releases.txt"

source 在当前 shell 中执行脚本,因此脚本定义的函数和环境能够留给后续命令;直接用 bash 执行脚本会进入子进程,不能给父 shell 保留同一套设置。

预期帮助列出 lunch TARGET_PRODUCT [TARGET_RELEASE [TARGET_BUILD_VARIANT]];variants 列出 user、userdebug、eng。检查 products.txt 有本章产品,releases.txt 有 aosp_current 后再选择。产品与 release 查询会解析构建配置,可能生成 out 内的工具或缓存,需要等待;它们不等同于完整构建。

lunch sdk_phone64_x86_64 aosp_current userdebug
printf '%s\n' "$TARGET_PRODUCT / $TARGET_RELEASE / $TARGET_BUILD_VARIANT"
printf '%s\n' "$ANDROID_PRODUCT_OUT"

预期三项与所选配置相同,产品输出目录以 emu64x 结尾。若出现无效配置或命令失败,先处理该错误,不要继续用上一轮残留环境构建。换终端后需要重新 source 和 lunch;out/.leftovers 只是已有选择记录,不能独立证明当前 shell 的配置。

lunch 源码怎样补默认值

本版本不再提供无参数交互菜单。阅读 envsetup.sh 的 lunch 函数,可看到无参数时返回错误,以及新格式的默认赋值。下面是新格式分支的连续原文:

        product=$1
        release=$2
        if [[ -z $release ]]; then
            release=trunk_staging
        fi
        variant=$3
        if [[ -z $variant ]]; then
            variant=eng
        fi

$1、$2、$3 是三个位置参数,-z 检查是否为空。省略第二项会选择 trunk_staging,省略第三项会选择 eng。因此,“只写产品名”与“显式选择本章三项”不等价。旧式三段连字符格式仍兼容,但参数解析分支不同。

接着阅读 _lunch_meat() 中的这一段原文:

    TARGET_PRODUCT=$product \
    TARGET_RELEASE=$release \
    TARGET_BUILD_VARIANT=$variant \
    TARGET_BUILD_APPS= \
    build_build_var_cache
    if [ $? -ne 0 ]
    then
        if [[ "$product" =~ .*_(eng|user|userdebug) ]]
        then
            echo "Did you mean -${product/*_/}? (dash instead of underscore)"
        fi
        return 1
    fi
    export TARGET_PRODUCT=$(_get_build_var_cached TARGET_PRODUCT)
    export TARGET_BUILD_VARIANT=$(_get_build_var_cached TARGET_BUILD_VARIANT)
    export TARGET_RELEASE=$release

前三个赋值为 build_build_var_cache 提供目标条件;缓存构建失败时函数返回,避免继续设置无效配置。验证通过后读取规范化变量并 export,后续构建子进程才能继承。完整函数还会设置工具路径、输出路径等环境。

源码属于 build/make,固定提交 envsetup.sh。官方教程中可能仍出现无参数菜单的历史描述,本章用此提交的实现解释实际行为。

为什么产品名和输出目录不同

本章产品定义末尾的连续原文是:

PRODUCT_NAME := sdk_phone64_x86_64
PRODUCT_DEVICE := emu64x
PRODUCT_MODEL := Android SDK built for x86_64

PRODUCT_NAME 是配置名称,PRODUCT_DEVICE 是设备名称。该产品把设备名设为 emu64x,所以选择 sdk_phone64_x86_64 后,常见产品输出是 out/target/product/emu64x。产品文件还通过 inherit-product 引入设备、通用系统和功能配置;这就是一份产品定义能组合大量模块的原因。

固定提交产品定义。产品文件如有本地改动,实际镜像也会受其影响,复现时需要同时保留。

1.5 理解构建流程并执行编译

环境、源码、目录和产品都已经明确,现在再看构建系统怎样把它们连接起来。先理解规则与执行的分工,再真正发起构建;等待构建时,可以沿着入口阅读后面的源码。

编译 链接 打包与构建是什么关系

平时说“编译 Android”,往往包含多个阶段。先把这些动作分开,才能理解为什么修改一个文件后,并不一定需要从头处理全部源码。

动作解决的问题典型结果
编译把源码转换为后续工具或运行环境使用的代码形式Java 字节码、C/C++ 目标文件等
链接把 Native 目标文件和库的符号依赖连接起来Native 可执行文件或共享库
应用打包组合应用代码、资源和清单等材料APK,即 Android 应用安装包
镜像生成按产品配置组织分区内容与相关启动材料分区镜像及运行器使用的组合产物
构建管理以上动作的依赖、顺序与是否需要重做所请求模块或产品的产物集合

镜像可以理解为用于保存分区或组合磁盘内容的文件,具体格式取决于用途。APK 是应用产物,系统镜像还可能容纳许多应用、库与服务,因此“APK 已更新”和“设备启动所用镜像已更新”是不同判断。

先分清描述规则与执行规则

Android.bp 主要声明 Soong 模块,例如模块名称、源码、依赖和安装属性;Android.mk 及产品 Make 配置属于仍需兼容的构建输入。Soong 和 Kati 参与解析这些输入并生成构建规则,具体动作由 Clang 等 C/C++ 编译工具、Java 工具链和资源处理工具等完成。

Ninja 或本版本默认选择的 Siso,根据依赖安排这些动作。生成规则回答“需要做什么、先后关系是什么”,执行器回答“实际怎样调度并运行”。修改一个 Java 文件通常触发受影响模块及后续打包,依赖未变的任务可以复用已有结果,这就是增量构建的基础。

源码不会直接变成正在运行的程序

以 Settings 为例,SettingsHomepageActivity.java 是源文件。构建系统根据模块声明找到源码与依赖,执行编译、资源处理和打包,生成 APK;产品配置再决定把它放进什么系统分区。镜像由匹配的运行器加载,Android 启动后,Activity 才会在应用进程中执行。

因此,“修改源码”“生成 APK”“重新生成镜像”“启动新镜像”“进入修改过的 Activity”是不同动作。任一环节仍使用旧内容,设备上的行为就可能没有变化。这也是本章选择一行日志作为最终实验的原因:用一个容易识别的结果检查整条工程路径。

一行改动从源码到设备日志的构建与运行路径

SHA256 摘要可理解为文件内容的“内容指纹”,用于核对文件内容是否变化;摘要相同不证明本轮启动已经加载该文件,更不证明目标代码已经执行。文件比对还要与构建退出码、启动参数和新一轮设备日志共同判断。

下面是工程关系图,表示主要输入输出,不是逐函数调用图。

源码不会直接变成正在运行的程序(过程或对象关系)

从上往下看,先决定“拿哪些代码”,再决定“构建哪种设备”,最后才是执行任务与运行。从下往上看,运行属性、APK 路径和日志应能反查本次产物与源码。这两个方向都能连起来,后续分析 Binder、WindowManager、Camera 时才知道自己在读哪份实现。

四类对象不要混淆

源码工作区保存文本、资源和各个 Git 项目;构建配置决定选择哪些模块、功能开关和设备设置;构建产物是 APK、可执行文件、库和镜像;运行状态是设备里的进程、已加载代码、属性和持久数据。

例如,repo sync 改变源码工作区,lunch 设置构建配置,m Settings 请求构建模块,emulator 创建或启动虚拟设备,adb logcat 观察设备中的日志。把这些工具放回各自阶段,比孤立记忆命令更容易排查问题。

真正执行一次系统构建

前提是 lunch 已成功,源文件与产品依赖齐全,Host 空间和资源足够。先记录配置,再构建。此步骤可能持续很久并大量写入 out;不要同时对同一输出目录启动另一轮构建。

printf 'product=%s\nrelease=%s\nvariant=%s\nproduct_out=%s\n' \
  "$TARGET_PRODUCT" "$TARGET_RELEASE" "$TARGET_BUILD_VARIANT" \
  "$ANDROID_PRODUCT_OUT" > "$chapter1_run/build-config.txt"
printf 'command=m -j2\n' > "$chapter1_run/build-command.txt"
set -o pipefail
m -j2 2>&1 | tee "$chapter1_run/build.log"
chapter1_build_status=("${PIPESTATUS[@]}")
printf 'build=%s tee=%s\n' "${chapter1_build_status[0]}" \
  "${chapter1_build_status[1]}" | tee "$chapter1_run/build-exit.txt"

预期构建成功退出,并生成该产品的默认目标。tee 也需成功,否则日志可能不完整。出现错误时先找本次日志的首次实质性诊断,修复后通常沿用同一目标增量构建;改变参数、配置或代码时同时补记日志。

已有历史镜像只能说明过去存在对应产物。本章跟做以本次退出状态和输出为准;不要求删除既有 out 来证明“全量”,m 会按依赖检查并构建默认目标。

实际踩坑 signal 9 与 Soong 长时间分析 先看内存证据

现象。 最早编译 aosp_cf_arm64_auto 时终端被结束,出现 signal 9。历史日志明确记录 systemd-oomd 在内存压力下结束了所在会话;当时约 26 GiB RAM、4 GiB Swap。后续增加 Swap 并降到 -j2,仍曾被 oomd 提前终止。

原因。 signal 9 只表示被强制结束;本案例的 oomd 日志才把原因指向内存压力。out/ 是磁盘中间产物,不是持续占据物理内存的“上次编译”;清空它通常只会增加下次重建工作。另一次停在 analyzing Android.bp files 时,进程仍在执行,但软限制附近频繁回收且已有大量换页,所以进展很慢。

实际踩坑 signal 9 与 Soong 长时间分析 先看内存证据(过程或对象关系)

检查。 在另一 Host 终端查看;日志时间范围缩小到本次失败时段更准确:

free -h
swapon --show
journalctl -u systemd-oomd --since '1 hour ago' --no-pager
journalctl -k --since '1 hour ago' --no-pager | rg -i 'out of memory|oom|killed process'

关键是把时间、PID、构建范围对齐。 其他进程的 OOM、单独一条 memory stall 都不足以证明这次构建被内存终止。Soong 分析自身可能使用多个线程,m -j2 不等于每阶段都只用两个线程。

处理。 先确认物理内存与交换空间满足本次产品构建所需,减少其他进程占用,降低构建并发后继续增量构建。历史上增加 Swap、降低并发仍未立即解决问题,后续还调整了构建进程的资源限制;这些措施不能替代足够的可用内存,也不能保证每个产品都能成功构建。

保留 out,不因内存问题清理中间产物。 继续使用本节前面的构建与日志命令,以最终退出状态及本次目标产物判断结果。Soong 长时间分析时,先根据资源与日志判断是否仍有进展,反复停止重启可能重复分析工作。

历史结果。 后续记录包含 ARM64 Cuttlefish 镜像产物,以及 SDK Emulator 指定镜像目标的成功构建与运行报告;这不表示所有产品、所有完整构建都逐一验证。资源发生变化时重新记录,不能把不同阶段的内存、vCPU 与 Swap 数字合成同一台固定配置。

实际踩坑 nsjail 的沙箱警告与构建失败要分开判断

现象。 lunch 曾打印 Build sandboxing disabled due to nsjail error,但配置成功;后面某个生成动作又真正因 nsjail 失败退出,涉及 trusty_security_vm_arm64.bin。其关键错误为历史日志摘录:

initCloneNs(): mount('/', '/', NULL, MS_REC|MS_PRIVATE, NULL): Permission denied
runChild(): Launching child process failed

原因。 第一条是某处构建沙箱探测退化,不能推断后续所有动作都不再调用 nsjail。本案例系统日志还记录 AppArmor 拒绝,才将失败定位到 Ubuntu 的用户命名空间限制;其他环境中同样的 Permission denied 仍要检查其实际限制。

先检查本次日志:

journalctl -k --since '1 hour ago' --no-pager \
  | rg -i 'apparmor|DENIED|nsjail|userns'

历史处理。 当时准备了绑定到这个 nsjail 可执行路径的 AppArmor 配置。以下为该文件原文;其他源码路径需要调整附着路径,适用于支持这些规则的 Ubuntu/AppArmor 环境:

abi <abi/5.0>,
include <tunables/global>

profile aosp-nsjail /home/ajie/aosp/prebuilts/build-tools/linux-x86/bin/nsjail flags=(unconfined) {
  userns,
  @{exec_path} mr,
}

userns, 允许这个已命名程序使用用户命名空间,flags=(unconfined) 表示这不是一份完整的文件访问限制策略。 这是针对本次阻断的配置,不能称为完整沙箱加固。Ubuntu 对此类配置的说明

历史配置仍保存在 out/aosp-nsjail.apparmor。自己操作时,将上面内容保存为 $chapter1_run/aosp-nsjail.apparmor,核对内容和程序路径;先只检查语法,再安装加载:

apparmor_parser -Q -T "$chapter1_run/aosp-nsjail.apparmor"
sudo install -m 644 "$chapter1_run/aosp-nsjail.apparmor" /etc/apparmor.d/aosp-nsjail
sudo apparmor_parser -r /etc/apparmor.d/aosp-nsjail

验证范围。 当时记录到配置已准备、语法检查通过,并提示用户加载;该任务没有保留加载后原失败动作的独立复测输出。应重跑对应失败动作并检查本轮退出码与审计日志,不能把“文件写好”写成“原问题已实测解决”。

实际踩坑 编译大多完成 却在 super.img 打包时失败

现象。 历史末尾只显示 110640 done, 1 failed 和 Siso/Ninja 失败,容易误判成编译器出错。进一步查看失败动作后,定位到动态分区空间不足。

原因。 本产品当时动态分区容量配置为 1800 MiB,任务记录的镜像合计约 1886 MiB。容器必须满足分区、对齐与元数据约束;Host 磁盘还有空闲,不代表目标镜像布局足够大。不能用稀疏镜像占用的宿主机磁盘块数代替逻辑分区容量。

先从本轮构建日志找具体失败动作;有生成时再查看 out/siso_output、out/siso.INFO 或 out/siso_failed_commands.sh,不把旧文件误认成新一轮诊断。配置位置是 device/generic/goldfish/64bitonly/product/sdk_phone64_x86_64.mk。

历史将其中容量调整为 3072 MiB。下面是本地修改后的配置片段,不是上游默认值:

BOARD_EMULATOR_DYNAMIC_PARTITIONS_SIZE ?= $(shell expr 3072 \* 1048576 )
BOARD_SUPER_PARTITION_SIZE := $(shell expr $(BOARD_EMULATOR_DYNAMIC_PARTITIONS_SIZE) + 8388608 )  # +8M

第一行设置动态分区容量,第二行按该值加 8 MiB 得到 super 容量。 ?= 只在变量未定义时赋值,因此还要查看当前产品最终解析值;不能只编辑一个同名变量就认定生效:

get_build_var BOARD_EMULATOR_DYNAMIC_PARTITIONS_SIZE
get_build_var BOARD_SUPER_PARTITION_SIZE

在本文这组配置未被其他输入覆盖时,分别应为 3221225472 与 3229614080 字节。验证顺序:配置生效 → 失败打包动作通过 → 本轮所需镜像成功生成 → 冷启动验证。 历史任务确认已有镜像打包检查通过,后续还有 Emulator 运行报告;本次整理没有再次构建。

保留 out,按本章同一产品目标继续增量构建。真实设备的分区尺寸还受硬件、Bootloader 与刷写布局约束,不能照搬这次虚拟设备的 3 GiB 配置。

第一个入口 m 主要负责转交参数

本地 build/soong/bin/m 的关键连续原文:

require_top

_wrap_build "$TOP/build/soong/soong_ui.bash" --build-mode --all-modules --dir="$(pwd)" "$@"

exit $?

require_top 确认源码根位置。--build-mode 指定构建入口模式,--all-modules 选择可按模块目标构建的动作范围;它不表示“每次都强制重编译所有模块”。--dir 传入调用时目录,"$@" 将用户参数原样继续传下去,例如 Settings 与 -j2。_wrap_build 执行传入命令并汇总耗时、结果,完整定义在 shell_utils.sh。

第二个入口 soong_ui.bash 准备并进入 Go 程序

soong_ui.bash末尾的连续原文:

soong_build_go soong_ui android/soong/cmd/soong_ui
soong_build_go mk2rbc android/soong/mk2rbc/mk2rbc
soong_build_go rbcrun rbcrun/rbcrun
soong_build_go release-config android/soong/cmd/release_config/release_config

cd ${TOP}
exec "$(getoutdir)/soong_ui" "$@"

这里先构建所需的 Host Go 工具,再切换到源码根目录。exec 用构建出的 soong_ui 替换当前脚本进程,继续传入原参数。shell 脚本本身不是用来编译全部 Java/C++ 文件的,它是进入构建调度程序的桥梁。

Go 入口 cmd/soong_ui/main.go将 --build-mode 映射到配置解析和 runMake,后者调用 build.Build(ctx, config)。继续深入时,应阅读 ui/build/build.go 中各阶段组织,而不把名字里的 make 当成“只运行传统 Make”。

为什么日志写 ninja 实际却运行 Siso

config.go中的默认值原文:

var NINJA_DEFAULT ninjaCommandType = NINJA_SISO

同一文件读取 SOONG_NINJA 来选择实现;下面是该 switch 的连续原文:

	switch os.Getenv("SOONG_NINJA") {
	case "ninja":
		ret.ninjaCommand = NINJA_NINJA
	case "n2":
		ret.ninjaCommand = NINJA_N2
	case "siso":
		ret.ninjaCommand = NINJA_SISO
	case "ninjago":
		ret.ninjaCommand = NINJA_NINJAGO
	default:
		ret.ninjaCommand = NINJA_DEFAULT
	}

没有命中显式选项时使用默认值。本文所选 Linux 源码版本因此默认走 Siso;环境覆盖会改变选择,不能只记住默认值。

实际执行点在 ninja.go 的 runNinja。Siso 分支开头的连续摘录如下,完整分支还会追加配置:

	case NINJA_SISO:
		executable = config.SisoBin()
		args = []string{
			"--log_dir", config.LogsDir(), // for glog, e.g. siso.*INFO*
			"ninja",
			// TODO: implement these features, or remove them.
			//"-d", "trace",
			"-d", "keepdepfile",
			"-d", "keeprsp",
			//"-d", "stats",
			"--frontend_file", fifo,
			"--local_jobs", strconv.Itoa(config.Parallel()),
			"--log_dir", config.LogsDir(),
		}

它选择 config.SisoBin,并以 ninja 子命令调用,local_jobs 接收配置中的并发数。调度阶段的 trace 标签仍可能叫 ninja,因此日志标签与实际可执行文件名不必相同。判断一次具体构建使用哪个执行器,应进一步查看该次日志的实际可执行文件与参数。

上述四份 Soong 源码属于提交 6722dd8833db7482df1a2543ca3fcf67ddf0f7b1,可查 m、soong_ui.bash、配置与 执行点。

从模块到分区再到 Emulator 镜像

产物理解方式本章重点
APK / so / 可执行文件供 Android 用户空间使用的模块产物Settings APK
system.imgsystem 分区内容Framework 等系统内容,具体由产品决定
system_ext.imgsystem_ext 分区内容本版本 Settings 模块声明安装在此
vendor.img设备相关用户空间内容与产品设备实现匹配
super.img动态分区的容器镜像可包含多个逻辑分区,不等于一个独立文件系统
vbmeta.imgAndroid Verified Boot 校验元数据与参与校验的镜像对应
system-qemu.img本产品为 Emulator 生成的组合镜像不能只按文件名理解成 system.img 的复制
kernel-ranchu / ramdisk.imgKernel 与启动期材料与运行后端配套
userdata.img初始化 data 分区的材料与可写运行数据区分

关键证据在 build/make/core/Makefile:本版本 system-qemu 配置把 vbmeta 和 super 交给组合镜像工具。以下为连续原文:

$(INSTALLED_SYSTEM_QEMU_CONFIG): $(INSTALLED_SUPERIMAGE_TARGET) $(INSTALLED_VBMETAIMAGE_TARGET)
	@echo "$(PRODUCT_OUT)/vbmeta.img vbmeta 1" > $@
	@echo "$(INSTALLED_SUPERIMAGE_TARGET) super 2" >> $@
$(INSTALLED_QEMU_SYSTEMIMAGE): $(INSTALLED_VBMETAIMAGE_TARGET) $(MK_COMBINE_QEMU_IMAGE) $(SGDISK) $(SIMG2IMG) \
    $(INSTALLED_SUPERIMAGE_TARGET) $(INSTALLED_SYSTEM_QEMU_CONFIG)
	@echo Create system-qemu.img now
	(export SGDISK=$(SGDISK) SIMG2IMG=$(SIMG2IMG); \
     $(MK_COMBINE_QEMU_IMAGE) -i $(INSTALLED_SYSTEM_QEMU_CONFIG) -o $@)

systemimage: $(INSTALLED_QEMU_SYSTEMIMAGE)

这里的依赖意味着上游 super 或 vbmeta 更新时,组合镜像需要跟着重新生成。后面的 systemimage 目标还依赖 VerifiedBootParams.textproto,所以改动后的构建不能只更新一个 APK 后直接期待旧镜像带上它。固定提交打包规则

构建成功后检查主路径所需产物并保存摘要:

ls -lh "$ANDROID_PRODUCT_OUT"/{system.img,system_ext.img,super.img,vbmeta.img,system-qemu.img,kernel-ranchu,ramdisk.img,userdata.img,VerifiedBootParams.textproto}
sha256sum "$ANDROID_PRODUCT_OUT/system-qemu.img" \
  "$ANDROID_PRODUCT_OUT/system_ext.img" "$ANDROID_PRODUCT_OUT/vbmeta.img" \
  "$ANDROID_PRODUCT_OUT/kernel-ranchu" \
  "$ANDROID_PRODUCT_OUT/VerifiedBootParams.textproto" \
  > "$chapter1_run/images-before.sha256"

摘要用于比较文件内容是否变化,不是构建成功或运行正确的替代品。缺失某项时,先确认本次目标与构建结果,再按本产品规则补建;下一节将利用这些路径启动 Android。

1.6 启动 Emulator 并核对运行版本

Emulator 运行的也是一套 Android 系统

Android Emulator 在 Host 上提供虚拟设备运行环境,Android 系统在 guest 中启动。guest 里面仍有 Kernel、init、system_server、应用进程和设备服务,只是部分设备由虚拟硬件和 Host 后端实现。官方架构说明

ADB 是 Host 与设备间的调试通道。Host 的 adb 客户端通过服务端与设备侧 adbd 通信,提供 shell、安装、文件传输和日志访问。它能发现设备,和 Android 是否已完成启动,是两个不同判断。

下面先使用无窗口、软件渲染模式,减少显示环境差异。软件渲染便于工程验证,不能拿来代表物理 GPU 的性能。

终端 A 负责构建启动,终端 B 检查设备

第一步 检查运行器与本次输入

在已成功 lunch 的 Host Bash 中运行:

chapter1_emulator="$chapter1_top/prebuilts/android-emulator/linux-x86_64/emulator"
chapter1_adb="$chapter1_top/out/host/linux-x86/bin/adb"
"$chapter1_emulator" -version
"$chapter1_emulator" -accel-check
"$chapter1_emulator" -help-build-images
"$chapter1_adb" version
printf '%s\n' "$ANDROID_PRODUCT_OUT"

预期二进制可执行,加速检查可用,产品输出指向本次 emu64x。若工具不存在,回到构建输出与所选产品核实;若 KVM 不可用,先检查权限、硬件虚拟化和 Host 环境。不要因为创建了 /dev/kvm 文件名就认为虚拟化可用。

本文所用运行器的帮助说明:build mode 通过 ANDROID_PRODUCT_OUT 识别产品镜像目录。帮助中的通用历史文件名不一定覆盖当前产品的全部细节,当前 Goldfish 的 kernel-ranchu 与组合镜像仍以产品和打包规则为准。这里使用的是工程自带的 emulator 二进制,而非假设系统 PATH 中另一个版本与它一致。

上一节产物检查应包含 VerifiedBootParams.textproto。若历史产物缺失或发现镜像与参数批次不一致,应回到同一产品配置,通过构建依赖更新:

m systemimage systemextimage -j2

只有构建成功后再启动。也可对照 vbmeta 摘要与启动参数中的 digest 排查:

avbtool calculate_vbmeta_digest --image "$ANDROID_PRODUCT_OUT/vbmeta.img"
rg 'androidboot.vbmeta.digest' "$ANDROID_PRODUCT_OUT/VerifiedBootParams.textproto"

avbtool 应来自本次构建环境。摘要一致是局部一致性检查,不替代整个镜像的构建与启动验证。

实际踩坑 No AVD specified 是环境问题还是镜像问题

现象。 历史中执行 emulator,得到 No AVD specified. Use '@foo' or '-avd foo',但系统刚在独立服务里构建过。

原因。 服务中的 lunch 不会传回原终端。当前 shell 没有产品输出环境时,Emulator 不一定进入 AOSP build mode,而会要求指定命名 AVD。先在自己启动运行器的 Host 终端重新加载:

cd "$chapter1_top"
source build/envsetup.sh
lunch sdk_phone64_x86_64 aosp_current userdebug
printf 'product=%s\nout=%s\n' "$TARGET_PRODUCT" "$ANDROID_PRODUCT_OUT"

关键检查:输出必须指向本次 sdk_phone64_x86_64 的 emu64x。 历史当时镜像还在编译,环境修好也不能代替等待构建成功。ARM64 Cuttlefish 车载产物、x86_64 Cuttlefish 产物和 SDK Emulator 产物要分开,CPU 架构相同也不表示运行器可以混用。

实际踩坑 新镜像配旧校验参数 GPU 弹窗可能只是同时出现

现象。 修改开机动画并更新镜像后,出现 GPU 提醒、看不到新动画且 Android 无法完成启动。后续排查将无法开机的根因定位为新镜像搭配了旧 VerifiedBootParams.textproto,不能仅凭同时出现的弹窗归因 GPU。

原理与源码。 启动参数携带 vbmeta 校验摘要;镜像内容变化后,相关元数据与启动参数需要对应。先在同一产品配置下运行前面的摘要对照,再让构建规则更新配套产物,避免用手工写入一个新 digest 掩盖其他不一致。

下面两段均来自 build/make/core/Makefile 的固定提交,分别阅读。

参数文件依赖参与计算的镜像与生成工具。

QEMU_VERIFIED_BOOT_PARAMS := $(PRODUCT_OUT)/VerifiedBootParams.textproto
$(QEMU_VERIFIED_BOOT_PARAMS): $(INSTALLED_VBMETAIMAGE_TARGET) $(INSTALLED_SYSTEMIMAGE_TARGET) \
    $(MK_VBMETA_BOOT_KERNEL_CMDLINE_SH) $(AVBTOOL)

systemimage 把它纳入构建目标。

systemimage: $(QEMU_VERIFIED_BOOT_PARAMS)

生成脚本 device/generic/goldfish/build/tools/mk_vbmeta_boot_params.sh 用 avbtool 计算摘要并写入参数;组合镜像规则还负责 super 与 vbmeta 的更新。只更新模块或某个组合镜像路径,不能未经核对就假设所有启动输入已同步。

处理与验证。 在本文环境中按前面的 m systemimage systemextimage -j2 更新,成功后关闭旧 Emulator 进程,再使用 -no-snapshot 冷启动;继续核对摘要、boot_completed 与运行版本。历史曾用脚本补齐参数并记录两次冷启动成功、保留 userdata;本次采用构建依赖作为主路径,不要求读者依赖那份个人启动脚本。

实际踩坑 ADB 未找到与 GPU 提醒怎样分别确认

ADB 现象。 Emulator 界面提示找不到 ADB,但不表示 Android 一定没启动。历史中指定 AOSP 自带 ADB 后连接正常。显式指定路径便于确认使用哪一个版本,后文 ADB 操作统一使用该绝对路径:

"$chapter1_adb" version
"$chapter1_adb" devices -l

GPU 现象。 软件渲染已生效,仍可能显示 GPU Driver Issue 提醒。历史默认启动报告确认使用 swiftshader_indirect 且系统完成开机,所以判断要分别看所用渲染器、图形输出和 boot_completed。这个渲染参数是本章所带运行器的历史可用配置;其他版本先检查 emulator -help-gpu,不假定支持相同模式名。

验证。 不把弹窗是否消失当作唯一标准。下一步按正文冷启动、等待 ADB、查询属性并核对模块;要看新动画,应关闭旧 Emulator 并重新启动。adb reboot 重启的是正在运行的 guest,不能据此认定 Host 刚生成的基础镜像已被重新加载。

第二步 使用独立 data 并冷启动

在 Host 终端 A 中继续操作。先确认 5556/5557 端口未被其他 Emulator 使用,可用 ss -ltn 检查;已有设备时另选可用的偶数端口,后面 serial 也需对应修改。

chapter1_runtime=$(mktemp -d "$chapter1_run/runtime.XXXXXX")
cp --sparse=always "$ANDROID_PRODUCT_OUT/userdata.img" \
  "$chapter1_runtime/userdata.img"
export ANDROID_BUILD_TOP="$chapter1_top"
printf 'product_out=%s\nruntime=%s\nport=5556\n' \
  "$ANDROID_PRODUCT_OUT" "$chapter1_runtime" \
  > "$chapter1_run/emulator-config.txt"
set -o pipefail
"$chapter1_emulator" -port 5556 -no-snapshot -no-window \
  -gpu swiftshader_indirect -no-audio \
  -data "$chapter1_runtime/userdata.img" \
  -cache "$chapter1_runtime/cache.img" \
  2>&1 | tee "$chapter1_run/emulator-before.log"

这条启动命令保持前台运行,终端 A 暂时不会返回提示符;后面的设备操作在终端 B 进行。

-no-snapshot 禁用启动时恢复与退出时保存快照,让这次从启动流程运行;它不等于擦除 data。-data 指向独立复制的可写数据镜像,避免直接使用已有实验的用户数据。-no-window 不显示窗口,swiftshader_indirect 选择所选工程二进制支持的软件渲染模式。日志写入本次记录目录。命令参数说明

若需要观察界面,在下一次启动时去掉 no-window,并根据 Host 显示条件调整;同一轮修改前后比较保持渲染与数据条件一致。不要同时启动两台虚拟设备写同一份 data。

第三步 等待 ADB 与 Android 启动完成

在 Host 终端 B 中重新定义记录目录,填入终端 A 实际输出的路径。产品输出目录取自本轮已经保存的 build-config.txt 的 product_out 行;终端之间不会共享构建环境变量。然后设置工具与 serial:

read -r -p '输入终端 A 的源码目录完整路径:' chapter1_top
read -r -p '输入终端 A 输出的 record 目录完整路径:' chapter1_run
test -d "$chapter1_run"
read -r -p '输入本轮 build-config.txt 中 product_out 的完整路径:' chapter1_product_out
test -d "$chapter1_product_out"
chapter1_adb="$chapter1_top/out/host/linux-x86/bin/adb"
chapter1_serial=emulator-5556
"$chapter1_adb" devices -l
timeout 120 "$chapter1_adb" -s "$chapter1_serial" wait-for-device

设备列表中的 serial 必须与选定端口对应。wait-for-device 超时表示未在该时间内建立可用通道,先检查启动日志和设备状态,再继续。它成功后只表示 ADB 通道就绪,接着等待 Android 的启动完成属性:

chapter1_boot_ready=0
for chapter1_attempt in $(seq 1 120); do
  chapter1_boot=$(timeout 5 "$chapter1_adb" -s "$chapter1_serial" shell \
    getprop sys.boot_completed 2>/dev/null | tr -d '\r')
  if [ "$chapter1_boot" = 1 ]; then
    chapter1_boot_ready=1
    break
  fi
  sleep 2
done
printf 'boot_completed_check=%s\n' "$chapter1_boot_ready"

预期最后为 1。最多检查 120 次,每次读取最多等待 5 秒,两次检查之间等待 2 秒;仍未完成则保存启动日志和可取得的 logcat,按卡住阶段分析;不要把延长等待当作根因修复。首次启动可能比后续启动慢,时间界限只是本次检查窗口。

第四步 核对正在运行的版本与模块

终端 B 中把 chapter1_run 设置为本次实际记录目录后采集:

"$chapter1_adb" -s "$chapter1_serial" shell getprop \
  > "$chapter1_run/device-before.properties"
"$chapter1_adb" -s "$chapter1_serial" shell uname -a \
  > "$chapter1_run/kernel-before.txt"
"$chapter1_adb" -s "$chapter1_serial" shell pm path com.android.settings
"$chapter1_adb" -s "$chapter1_serial" shell dumpsys package com.android.settings \
  > "$chapter1_run/settings-before.txt"
"$chapter1_adb" -s "$chapter1_serial" logcat -b all -d \
  > "$chapter1_run/logcat-before.txt"

重点查看 ro.build.fingerprint、ro.build.id、ro.product.device、ro.build.type、ro.build.version.sdk 等属性,并与本次配置和产物中的 build.prop 对照。pm path 应显示 Settings 的实际安装位置;若有 data 下的更新包覆盖系统包,仅重建系统内 APK 可能仍不会使用它,需要先解释覆盖关系。

版本属性不能独立证明镜像每个字节都匹配。把启动参数、镜像摘要、属性与后面的唯一日志标记一起对照,才能建立足够清晰的实验依据。

Cuttlefish 路线怎样切换

Cuttlefish 同样运行 Android guest,但它有自己的产品配置、Host 组件、虚拟硬件后端和启动工具。SDK Emulator 使用的 Goldfish 产品、kernel-ranchu 与启动参数,不能直接交给 launch_cvd。

项目本章主路径Cuttlefish 对照
产品示例sdk_phone64_x86_64aosp_cf_x86_64_only_phone
产品配置目录device/generic/goldfishdevice/google/cuttlefish
运行器工程内的 emulator同批构建的 launch_cvd / cvd 等工具
底层材料Goldfish Kernel 与模块Cuttlefish Kernel、虚拟模块与 Host 后端
Host 准备本次 Emulator 可执行且 KVM 可用还需匹配的 Host 依赖、用户组与网络等配置

切换时在独立 Bash 终端重新 source,查询该产品支持的 release,再 lunch 对应三项、构建并启动。下载预构建包时,Host package 与设备镜像要取同一个 build;源码构建时也要保留同一套构建配置与工具来源。官方 Cuttlefish 准备与运行指南

本章先完成一条 SDK Emulator 主路径,后续比较 Cuttlefish 时可以复用版本采集方法,但启动步骤和底层材料需要按该后端单独建立。

运行以后 怎样为底层源码学习准备材料

系统已经能启动,也能显示自己的动画和 FallbackHome 页面。接下来容易遇到一个问题:正在阅读的 Kernel、HAL 和 Driver,是否就是当前系统使用的实现? 仅有 AOSP 目录或一个相近版本号,还不能回答这个问题。需要从运行对象反查配置、产物和源码,把它们连接起来。

本节以当前 SDK Emulator 为例,沿 Kernel、存储 Driver 与 Graphics Composer HAL 三条代表路径建立来源关系。2026-10-19 已在独立实例 emulator-5572 上完成只读核对,保存完整 Kernel 配置、模块、服务、文件摘要与启动参数;本轮使用现有镜像和新建的临时 userdata/cache,结束后已关闭。它是本节的来源验证,与前面的动画修改实测分别记录。本轮设备证据

先分清 HAL Kernel Driver 与 Host

HAL 将某类硬件能力表达为 Android 可调用的接口,具体实现通常位于独立服务或库中。Kernel 提供进程、内存、调度和 I/O 等机制;Driver 是操作某种设备或虚拟接口的内核实现。虚拟设备还需要 Host 运行器和后端配合,guest 中的设备节点不能直接等同于 Host 上的一块物理硬件。

第一章要先知道这些实现在哪里、怎样选中、如何核对版本;具体函数调用与数据传递在后续功能章节展开。下面的箭头表示来源追溯关系,不是运行时调用顺序。

先分清 HAL Kernel Driver 与 Host(过程或对象关系)

来源追溯图 SVG · PNG

先认对象,再找产物,最后追源码。版本号说明版本系列,Git 提交定位代码,SHA256 用于比较具体文件。 三种信息分别回答问题,最好一起记录。

先固定正在研究的系统

沿用本节终端 B 中的 chapter1_adb、chapter1_serial 和 chapter1_run。在 Host 执行:

"$chapter1_adb" -s "$chapter1_serial" shell getprop ro.build.fingerprint
"$chapter1_adb" -s "$chapter1_serial" shell getprop ro.product.cpu.abilist
"$chapter1_adb" -s "$chapter1_serial" shell uname -r

本轮设备的实际值是:

Android/sdk_phone64_x86_64/emu64x:17/CP2A.260605.016/eng.ajie:userdebug/test-keys
x86_64
6.12.58-android16-6-gccafb60de224-ab14828483

第一行描述 Android 用户空间,第三行描述运行 Kernel。Android 17 与 Kernel 名称中的 android16 分别来自不同版本体系,不要求数字一致。Kernel 的 gccafb60de224 提供源码提交线索;它还需要与配置、产物和模块共同核对,不能只找到一个 6.12 分支就认定完全对应。

Kernel 从哪来 产品配置怎样选中它

本产品通过 sdk_phone64_x86_64.mk继承 emu64x 的 details.mk,再进入 board/kernel/x86_64.mk。下面是 x86_64.mk 中的连续源码:

TARGET_KERNEL_USE ?= 6.12
KERNEL_ARTIFACTS_PATH := prebuilts/qemu-kernel/x86_64/$(TARGET_KERNEL_USE)
KERNEL_MODULES_ARTIFACTS_PATH := $(KERNEL_ARTIFACTS_PATH)/gki_modules
VIRTUAL_DEVICE_KERNEL_MODULES_PATH := $(KERNEL_ARTIFACTS_PATH)/goldfish_modules

?= 设置的是可被覆盖的默认值。 这段配置说明默认从 6.12 目录选择预编译 Kernel 与模块,不表示系统构建重新编译了全部 Kernel 源码。文件后面用 EMULATOR_KERNEL_FILE 选出 Kernel,接着 emu64x/details.mk把它复制进产品输出。以下是该文件中的连续源码:

PRODUCT_COPY_FILES += \
    $(EMULATOR_KERNEL_FILE):kernel-ranchu \
    device/generic/goldfish/board/fstab/x86:$(TARGET_COPY_OUT_VENDOR_RAMDISK)/first_stage_ramdisk/fstab.ranchu \
    device/generic/goldfish/board/fstab/x86:$(TARGET_COPY_OUT_VENDOR)/etc/fstab.ranchu \

$(EMULATOR_KERNEL_FILE):kernel-ranchu 把选中的输入文件与产品产物连起来。 为了确认当前产物确实对应它,在 Host 的 AOSP 根目录比较摘要:

sha256sum prebuilts/qemu-kernel/x86_64/6.12/kernel-6.12 \
    out/target/product/emu64x/kernel-ranchu

本轮两份文件的大小均为 22,770,688 字节,SHA256 相同,完整值见来源清单。运行 uname 中的短提交则对应 kernel/common 的固定提交 ccafb60de224d35a8bc14de33e1cd47caaaa786b。至此,配置选择、当前产物和运行版本线索已有对应关系。

配置与模块 怎样判断实现内建还是动态加载

Kernel 的功能可以内建进镜像,也可以生成 .ko 模块。配置中的 =y 表示内建,=m 表示按模块构建;/proc/modules 列出当前加载的模块。因此,模块列表里没有某个名字,不能独立证明 Kernel 没有这项能力。

可以从运行系统保存实际配置,再在 Host 读取。本轮 /proc/config.gz 可读,涉及模块参数或受限进程文件时,仅在本次独立 userdebug 实例中使用了 adb root;其他设备按实际权限处理。

"$chapter1_adb" -s "$chapter1_serial" exec-out cat /proc/config.gz \
    > "$chapter1_run/kernel.config.gz"
gzip -dc "$chapter1_run/kernel.config.gz" > "$chapter1_run/kernel.config"
rg 'CONFIG_ANDROID_BINDER|CONFIG_VIRTIO_BLK' "$chapter1_run/kernel.config"

下面是本轮配置的选定行,省略了其他配置项:

CONFIG_VIRTIO_BLK=m
CONFIG_ANDROID_BINDER_IPC=y
CONFIG_ANDROID_BINDERFS=y
CONFIG_ANDROID_BINDER_IPC_RUST=m

先用 VirtIO block 连接配置和运行状态:配置说明它按模块构建;/proc/modules 中实际出现 virtio_blk;/data 的挂载来源为 dm-6,底层设备为 vdc,vdc 的 sysfs Driver 链接指向 virtio_blk。分别检查:

"$chapter1_adb" -s "$chapter1_serial" shell cat /proc/modules
"$chapter1_adb" -s "$chapter1_serial" shell cat /proc/mounts
"$chapter1_adb" -s "$chapter1_serial" shell ls -l /sys/class/block/dm-6/slaves
"$chapter1_adb" -s "$chapter1_serial" shell readlink -f /sys/class/block/vdc/device/driver

本轮最后一条返回 /sys/bus/virtio/drivers/virtio_blk。dm-6、vdc 是这个实例中的设备名,换设备后先重新核对挂载关系。源码入口由此落到同一 Kernel 提交的 drivers/block/virtio_blk.c,以后学习存储时可以继续向队列和 Host 请求追踪。

模块还可能来自另一个源码仓库。Host 上对两个预编译模块查询:

modinfo -F scmversion prebuilts/qemu-kernel/x86_64/6.12/gki_modules/virtio_blk.ko
modinfo -F scmversion prebuilts/qemu-kernel/x86_64/6.12/goldfish_modules/goldfish_pipe.ko
modinfo -F vermagic prebuilts/qemu-kernel/x86_64/6.12/goldfish_modules/goldfish_pipe.ko

本轮结果依次为:

gccafb60de224
g544e91ec0222
6.12.58-android16-6-gccafb60de224-ab14828483 SMP preempt mod_unload modversions

virtio_blk 来自 kernel/common,而 goldfish_pipe 的短提交解析到 kernel/common-modules/virtual-device 的固定提交。相同的 vermagic 说明模块面向同一 Kernel 版本与兼容条件;scmversion 则可能指向各自不同的源码仓库。 本轮进一步比较设备端与 Host 的模块摘要,确认上述两个已加载模块对应现存预编译文件。

Binder 到底使用 C 还是 Rust

同时存在 C、Rust 源码,甚至系统里安装了 rust_binder.ko,都不能直接判断运行选择。先读本轮 Kernel 配置:C Binder 内建,Rust Binder 按模块构建;再看实际参数与加载状态:

"$chapter1_adb" -s "$chapter1_serial" shell cat /sys/module/binder/parameters/impl
"$chapter1_adb" -s "$chapter1_serial" shell ls -l /dev/binder
"$chapter1_adb" -s "$chapter1_serial" shell cat /proc/modules

本轮 impl 为 c,/dev/binder 指向 /dev/binderfs/binder,rust_binder 未加载。结合固定 Kernel 的 drivers/android/Makefile,配置对应的编译规则是:

obj-$(CONFIG_ANDROID_BINDER_IPC)	+= binder.o binder_alloc.o binder_netlink.o

本轮 SDK Emulator 使用 C Binder。 这是当前镜像、启动配置和观测时刻的结果,不由其他产品的 binder.impl=rust 配置代替。第二章因此可以以 C 实现为当前运行主线,Rust 源码用于对应比较。配置、参数与模块证据

HAL 从服务实例追到模块与源码

HAL 可以运行在用户空间进程里。以 Graphics Composer 为例,先问“哪一个进程提供 IComposer/default”,再找它对应的模块,而不是从 hardware 目录猜名字。

在 Host 查询服务与 PID:

"$chapter1_adb" -s "$chapter1_serial" shell service list
"$chapter1_adb" -s "$chapter1_serial" shell dumpsys --pid \
    android.hardware.graphics.composer3.IComposer/default

这里的进程号每轮可能变化,先从刚才成功的服务查询取得本轮实际 PID;无 PID、多个结果或权限不足就停止此项,不照抄历史数字。终端 B 输入并核对:

read -r -p '本轮 Composer 服务的实际 PID:' chapter1_hal_pid
case "$chapter1_hal_pid" in
  ''|*[!0-9]*) printf '需要唯一数字 PID,停止此项核对\n';;
  *) chapter1_hal_exe=$("$chapter1_adb" -s "$chapter1_serial" shell \
       readlink "/proc/$chapter1_hal_pid/exe" | tr -d '\r')
     printf 'device executable=%s\n' "$chapter1_hal_exe";;
esac

只在返回了该服务实际绝对程序路径、且 Host 对应文件存在时继续。若 root 被拒绝或重连失败,停止需要该权限的来源核对,不把缺失数据写成匹配结论:

"$chapter1_adb" -s "$chapter1_serial" shell sha256sum "$chapter1_hal_exe"
sha256sum "$chapter1_product_out$chapter1_hal_exe"
rg -n 'composer3-service.ranchu|hwc3.rc|hwc3.xml' \
  "$chapter1_top/device/generic/goldfish/hals/hwc3/Android.bp"

两侧摘要一致才说明文件内容相同;路径不同、Host 文件缺失或摘要不一致时,记录结果并核对产品与产物批次,不能直接沿用历史实例结论。

本轮服务已注册,PID 为 474。进一步读取该进程的 exe、设备端文件摘要与 VINTF 清单,得到下面的对应关系;PID 仅用于本次记录,不应在下次实验中直接复用。

运行对象本轮实际值对应的源码材料
服务实例android.hardware.graphics.composer3.IComposer/defaultMain.cpp 拼接接口 descriptor 与 /default 并注册
进程可执行文件/vendor/bin/hw/android.hardware.graphics.composer3-service.ranchuAndroid.bp 声明同名 cc_binary,vendor=true、relative_install_path=hw
init 服务vendor.hwcomposer-3hwc3.rc 指定可执行文件、用户与分组
VINTF 声明/vendor/etc/vintf/manifest/hwc3.xml,AIDL 版本 5Android.bp 的 vintf_fragments 关联源码 hwc3.xml
具体实现目录device/generic/goldfish/hals/hwc3Goldfish 仓库固定提交 296e55aa0244e8929e393e00e34471fef2a5d662

VINTF 描述接口契约;服务列表说明实例当前已注册;进程与文件把它关联到具体程序。这几种观察互相补足。本轮设备文件与当前产品输出的 Composer 二进制 SHA256 相同,完整摘要保存在来源清单。

下面是 Main.cpp 中注册实例的连续源码:

    const std::string instance = std::string() + Composer::descriptor + "/default";
    binder_status_t status =
        AServiceManager_addService(composer->asBinder().get(), instance.c_str());
    CHECK(status == STATUS_OK);

Composer::descriptor + "/default" 把运行时看到的服务名接回源码。 接下来再读 Composer、Device 与具体 FrameComposer,才进入真正的图形实现;第一章在此先建立可追溯入口。

虚拟设备的另一端 Host 后端怎样记录

HAL 的服务名相同,不表示每个设备采用同一渲染方式。本轮属性为 ro.hardware.vulkan=ranchu、ro.hardware.gralloc=ranchu,未设置 ro.vendor.hwcomposer.mode。按 Common.cpp 与 Device.cpp 的条件判断,对应 HostFrameComposer 分支;这属于属性与源码对应,没有给工厂函数另做逐调用插桩。

继续检查本轮 Composer 的 fd,能看到它打开 /dev/goldfish_pipe_dprctd 和 /dev/goldfish_address_space;系统中 goldfish_pipe 模块已加载,其设备也有实际绑定。当前 gfxstream guest 源码的 qemu_pipe_guest.cpp 在图形 pipe 路径中包含以下连续语句:

    fd = open_verbose_path("/dev/goldfish_pipe_dprctd", flags);
    if (fd >= 0) {
        return fd;
    }

设备 fd 提供了“这个进程确实打开该接口”的证据。 它比只看到模块文件更进一步,但没有逐帧证明每个图形请求的完整去向。Host 启动日志另外记录了 gfxstream、SwiftShader Device 和 Google SwiftShader,可与本轮 -gpu swiftshader_indirect 参数对照。

本轮使用的预编译 Emulator 为 36.3.10、build 14472402。当前 gfxstream 源码可用于阅读接口和候选实现;要精确重建 Host 后端,还需要取得这个 Emulator build 对应的源码 manifest 与工具链,不能把工作区 HEAD 直接认定为预编译包的构建提交。

汇总到哪里 第一章做到什么程度

详细值和证据统一放在 SDK Emulator 底层来源清单。每一行保留运行对象、配置、产物、源码仓库与提交、证据和范围;文章负责解释如何建立这些联系。后续章节选定其他 HAL、Driver 或后端时,沿同样方法补充对应行。

当前已建立用户空间、Kernel 与模块、C Binder、VirtIO block、Graphics Composer 及图形传输的代表性对应关系。完整 Kernel/模块的可复现构建、Host 预编译包的精确源码对应和所有硬件能力继续按实际研究需要展开。

Kernel 驱动与 HAL 的来源追溯方法

自测:为什么模块目录里有 rust_binder.ko,本轮仍应读 C Binder 主线?因为模块文件说明实现可用,实际配置、impl 参数和加载状态共同表明本轮运行选择为 C。

1.7 让一行 Java 改动在设备上可见

为什么选择 Settings 首页

Settings 是系统应用,它的源码、资源、模块声明与安装位置都能在本工程中找到。一行日志只改变可观察输出,便于把注意力放在编译、打包和运行对应关系上。

本实验选择 SettingsHomepageActivity.java。它继承 FragmentActivity,不应凭旧教程假定每个 Settings 页面都经 SettingsActivity 的 onCreate。

AndroidManifest.xml中,该组件的声明片段如下,为连续原文:

        <activity android:name=".homepage.SettingsHomepageActivity"
                  android:label="@string/settings_label_launcher"
                  android:theme="@style/Theme.Settings.Home"
                  android:taskAffinity="com.android.settings.root"
                  android:exported="true"
                  android:configChanges="orientation|keyboard|keyboardHidden|screenSize|screenLayout|smallestScreenSize">

exported 为 true,表示组件允许来自应用外部的符合条件的启动。它还声明 android.settings.SETTINGS 入口。实验使用明确组件名,减少系统中其他 Activity 对同一 action 的解析差异。

对应源码的 onCreate 开头原文如下:

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        if (SettingsThemeHelper.isExpressiveTheme(this)) {
            setTheme(R.style.Theme_Settings_Home_Expressive);
        }

super.onCreate 完成父类生命周期处理;后面根据主题条件设置样式,再检查设备配置状态等。把新日志放在 super 调用之后、这些条件之前,即使后面因设备尚未 provisioned 而退出,也能知道该方法是否进入。生命周期的完整原理将在应用组件章节展开。

先定位模块与安装分区

文件存在不表示任意产品都会使用它。先在 Host 终端确认构建声明:

cd "$chapter1_top"
rg -n 'name: "Settings-core"|src/\*\*|name: "Settings"|system_ext_specific|static_libs' \
  packages/apps/Settings/Android.bp

本版本 Android.bp 中 Settings-core 收集 src 下的 Java/Kotlin 源码,Settings 应用引用它。Settings 应用的声明开头有这些属性:

android_app {
    name: "Settings",
    defaults: [
        "platform_app_defaults",
        "SpaPrivilegedLib-defaults",
        "Settings_optimized_defaults",
    ],
    platform_apis: true,
    certificate: "platform",
    system_ext_specific: true,
    privileged: true,

name 给出构建目标 Settings;platform_apis 允许使用平台 API;certificate 使用平台签名配置;system_ext_specific 将安装归属指向 system_ext;privileged 表示按特权应用形式安装。它们解释了为什么本章需要更新 system_ext 分区,而不是只盯着 system.img。

以上 Settings 源码属于提交 213829fb67f5e070029e0513a088f31bc8f5c1ed,公开固定版本见 Activity、Manifest和 模块声明。

第一步 保存当前文件再做最小修改

在构建用的 Host 终端 A 中设置文件路径,记录现状并备份当前内容。备份保存的是现在的工作区内容,包括可能已有的改动,不是强行还原到 Git HEAD。

chapter1_settings_rel=src/com/android/settings/homepage/SettingsHomepageActivity.java
chapter1_settings_file="$chapter1_top/packages/apps/Settings/$chapter1_settings_rel"
git -C "$chapter1_top/packages/apps/Settings" status --short
cp -p "$chapter1_settings_file" \
  "$chapter1_run/SettingsHomepageActivity.java.before"
git -C "$chapter1_top/packages/apps/Settings" diff -- "$chapter1_settings_rel" \
  > "$chapter1_run/settings-existing.diff"

打开上述文件,在该 onCreate 的 super 调用后添加一行。下面是改动后的教学片段,省略后续逻辑;新增的是 Log.i,原文件已有 Log 导入和 TAG。

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        Log.i(TAG, "AOSP_CHAPTER1 settings homepage created");
        // 笔记删节:后续原有逻辑保持原样

这里展示函数开头,不能用它覆盖整个方法。保存后查看本文件 diff:

git -C "$chapter1_top/packages/apps/Settings" diff -- "$chapter1_settings_rel" \
  > "$chapter1_run/settings-with-marker.diff"
cat "$chapter1_run/settings-with-marker.diff"

预期相对于刚才的备份只多一行日志。若本文件原先已有变化,应与 settings-existing.diff 对照,区分之前的改动。工作区中的其他配置、动画或功能改动继续属于实验基线。

第二步 停止旧虚拟设备再编译

在终端 B 用已确认的 serial 关闭本章虚拟设备:

"$chapter1_adb" -s "$chapter1_serial" emu kill

等终端 A 的启动进程结束再使用该终端构建;若构建环境已换终端,重新 source 并 lunch 本章三项。先构建模块,再更新系统打包目标,分别保存退出状态。

set -o pipefail
m Settings -j2 2>&1 | tee "$chapter1_run/settings-build.log"
chapter1_module_status=("${PIPESTATUS[@]}")
printf 'build=%s tee=%s\n' "${chapter1_module_status[0]}" \
  "${chapter1_module_status[1]}" | tee "$chapter1_run/settings-build-exit.txt"

模块构建与日志保存均成功后继续:

m systemimage systemextimage -j2 2>&1 | tee "$chapter1_run/images-build.log"
chapter1_images_status=("${PIPESTATUS[@]}")
printf 'build=%s tee=%s\n' "${chapter1_images_status[0]}" \
  "${chapter1_images_status[1]}" | tee "$chapter1_run/images-build-exit.txt"
sha256sum "$ANDROID_PRODUCT_OUT/system_ext.img" \
  "$ANDROID_PRODUCT_OUT/system-qemu.img" "$ANDROID_PRODUCT_OUT/vbmeta.img" \
  > "$chapter1_run/images-with-marker.sha256"

任一构建失败就先处理错误,不使用旧产物继续判断本轮修改。这里通过离线重打包、重启设备部署,不依赖 adb remount 或 adb install 对特权系统应用的额外部署条件。

第三步 冷启动同一 data 并进入明确页面

终端 A 复用之前的 chapter1_runtime,保持相同 data。直接执行下面的启动命令,不重新创建运行目录或复制 userdata:

"$chapter1_emulator" -port 5556 -no-snapshot -no-window \
  -gpu swiftshader_indirect -no-audio \
  -data "$chapter1_runtime/userdata.img" \
  -cache "$chapter1_runtime/cache.img" \
  2>&1 | tee "$chapter1_run/emulator-with-marker.log"

终端 B 按上一节的有界等待确认本轮 ADB 和 sys.boot_completed,再启动组件。force-stop 会关闭当前 Settings 进程,使这次操作能创建新的 Activity 实例。

"$chapter1_adb" -s "$chapter1_serial" logcat -c
"$chapter1_adb" -s "$chapter1_serial" shell am force-stop com.android.settings
"$chapter1_adb" -s "$chapter1_serial" shell am start -W \
  -n com.android.settings/.homepage.SettingsHomepageActivity
"$chapter1_adb" -s "$chapter1_serial" logcat -d \
  -s SettingsHomepageActivity:I '*:S' \
  > "$chapter1_run/settings-marker.log"
rg -F 'AOSP_CHAPTER1 settings homepage created' "$chapter1_run/settings-marker.log"

先确认 am start -W 返回 Status: ok,再确认清空旧日志后这一轮包含唯一标记;两项共同成立才是本轮创建并执行目标代码的依据。-W 等待 Activity 启动结果,不表示已经验证页面所有功能。logcat 的 tag 取自源码 TAG,I 表示该 tag 从 Info 级别起显示,'*:S' 关闭其他 tag,单引号防止 Host shell 展开星号。

要匹配的日志标记 AOSP_CHAPTER1 settings homepage created

如果没有标记,依次检查:构建是否成功、镜像是否更新、运行器是否读取本次产品输出、快照是否关闭、pm path 是否指向系统内的 APK、组件是否确实启动。可以临时查看未过滤的 logcat,避免把过滤条件错误当作代码未执行。

这次重新打包后,ro.build.id 或 fingerprint 可能与之前相同;它们不能单独识别这一行本地修改。唯一标记、文件摘要、构建与启动记录共同说明修改是否到达运行系统。

第四步 恢复当前文件并再次验证

本次学习已完成启动动画与 FallbackHome 修改实测,并决定保留定制效果,不执行回退验证。下面的方法供之后需要恢复临时改动时参考,不列为本次未完成任务。

先关闭本章虚拟设备并等待退出。确认本文件除了本轮日志外没有新加的其他编辑;随后恢复本轮备份,保留实验开始前的内容。

cp -p "$chapter1_run/SettingsHomepageActivity.java.before" "$chapter1_settings_file"
cmp "$chapter1_run/SettingsHomepageActivity.java.before" "$chapter1_settings_file"

cmp 无输出且退出码为 0 表示文件内容已恢复。不要用整个 Settings 项目的 reset/clean 代替单文件恢复,那会影响基线中的其他修改。

在终端 A 请求模块与镜像目标,依赖顺序由构建系统处理,保存本次恢复构建的结果:

m Settings systemimage systemextimage -j2 2>&1 | tee "$chapter1_run/rollback-build.log"
chapter1_rollback_status=("${PIPESTATUS[@]}")
printf 'build=%s tee=%s\n' "${chapter1_rollback_status[0]}" \
  "${chapter1_rollback_status[1]}" | tee "$chapter1_run/rollback-build-exit.txt"

两项状态均为 0 后,用同一运行目录冷启动:

"$chapter1_emulator" -port 5556 -no-snapshot -no-window \
  -gpu swiftshader_indirect -no-audio \
  -data "$chapter1_runtime/userdata.img" \
  -cache "$chapter1_runtime/cache.img" \
  2>&1 | tee "$chapter1_run/emulator-rollback.log"

终端 B 等待本轮启动完成,再重新创建 Activity 并保存该轮日志:

"$chapter1_adb" -s "$chapter1_serial" logcat -c
"$chapter1_adb" -s "$chapter1_serial" shell am force-stop com.android.settings
"$chapter1_adb" -s "$chapter1_serial" shell am start -W \
  -n com.android.settings/.homepage.SettingsHomepageActivity
"$chapter1_adb" -s "$chapter1_serial" logcat -d \
  -s SettingsHomepageActivity:I '*:S' \
  > "$chapter1_run/settings-rollback.log"
rg -F 'AOSP_CHAPTER1 settings homepage created' "$chapter1_run/settings-rollback.log"

最后的 rg 预期没有匹配并返回 1;这是“没有找到标记”的查询结果。还要确认 am start -W 返回 Status: ok,结合本轮启动记录,避免把 Activity 没有启动误判为恢复成功。

恢复验收应同时满足:源码与备份一致、构建成功、新一轮启动成功、明确启动了同一组件、该轮日志不再出现新增标记。只把文件恢复而继续运行旧进程,不算完成运行回退。

调试通道 启动状态 修改结果与按需恢复的验证依据

为什么这次实验能连接整条路径

为什么这次实验能连接整条路径(过程或对象关系)

向下能解释每次打包与加载,向上能从标记追溯到对应源码。日志实验不证明所有 Framework、HAL 或 Driver 已读通,但它建立了后续修改与验证所需的工程方法。

实际踩坑 动画已经改了 为什么还是旧画面

现象。 历史中先生成动画素材,模拟器仍显示旧 Android 动画;随后又遇到“开机动画之后的手机正在启动画面在哪里”。这两个画面属于不同实现,先确认自己改的是哪一段。

想改变什么本例对应材料需要更新什么
开机动画的画面与循环bootanimation.zip 中的连续 PNG 和 desc.txt将资源纳入当前产品,更新相应分区、组合镜像和校验参数
动画播放器行为frameworks/base/cmds/bootanimation/BootAnimation.cppNative 播放器及所在分区与镜像
启动后暂时显示的“手机正在启动”Settings 的 FallbackHome.java 与 fallback_home_finishing_boot.xmlSettings 及其所在 system_ext 分区、组合镜像与校验参数
正式桌面packages/apps/Launcher3Launcher 模块及对应产品镜像

先查目标,再查资源进入了哪份镜像,最后查运行时实际加载了什么。 历史上曾同时存在 ARM64 Cuttlefish 车载构建与 x86_64 SDK Emulator 目标;前者构建成功不会更新后者。只生成 ZIP、只编译播放器或只在旧 guest 里重启,都不能证明新产品镜像已加载。按本文的 systemimage 构建与冷启动路径验证,相关启动失败见 AVB 案例。

历史还把 desc.txt 末尾的 #000000 误认成图片文件名。下面是一个教学配置示例,不是源函数:

1080 1920 30
p 0 0 part0 #000000

#000000 是背景色,part0 才是帧目录。 第一行表示宽、高与帧率;第二行 p 表示允许在启动结束时中断,次数 0 表示循环,暂停 0 表示无帧间段落暂停。帧文件另按补零编号排列;desc.txt 位于 ZIP 根目录。本次采用连续 PNG,视频或 GIF 先导出帧再制作动画包,不把 MP4 直接改名为 ZIP。

配置格式见 FORMAT.md,实际选取动画文件的顺序还要看同版本 BootAnimation.cpp 的 findBootAnimationFile,不能只套用格式文档中列出的历史路径。

FallbackHome 是条件性的临时桌面。 用户解锁与正式 Home 可用后它退出;Launcher 已就绪时可能不出现。因此“动画 → FallbackHome → Launcher”是某次可见界面顺序,不是每次开机都必经的固定画面,也不能当成三个进程的固定启动顺序。

早期记录。 动画经过帧序列制作、运行测试和后续镜像持久化验证;当时另一份 FallbackHome 的 GIF 改动记录止于资源与 Java 编译检查。这是早期材料的验证范围,后续实践进展见下文。个人素材可作为附件保留,公开文章使用可分享的帧图。

本章实践成果 启动动画与启动过渡页面

2026-10-19 补录:已完成 Android 启动动画和 Settings FallbackHome 启动过渡页面的修改与运行测试。两项改动都以实际运行效果检验修改结果,作为本章修改实践的成果。修改实测记录

实践成果已完成内容从中理解的工程关系
修改 Android 启动动画动画修改与运行测试素材与资源包、产品配置、镜像及开机画面的对应关系
修改 FallbackHome 启动过渡页面页面布局、GIF 播放与运行测试Settings 中的临时页面与 Native 启动动画分别实现,需分别更新资源与所属产物

复盘时分别回答两个问题:改动属于哪份资源或哪个模块?运行时为什么显示这份改动? 再把修改位置、构建产物、部署方式与实际画面对应起来。这比只记住一条构建命令更有助于后续修改 Framework 或系统应用。

把实际结果变成学习成果

本次实践的配置、操作入口、两次动画启动结果、FallbackHome 完成反馈、素材摘要与关键改动已补入实验 0002。后续实验继续关联当轮 manifest、本地改动、构建日志、镜像摘要与运行效果;需要恢复时再记录恢复过程。若某步失败,另建问题记录保存症状、条件、检查过程和解决依据。

这个案例中的模块、分区、镜像、进程四个边界,也是一套排查顺序:先确认代码已经进入模块,再确认分区和镜像更新,最后确认目标进程实际加载并执行了新代码。下面把它扩展为各工程阶段的常见问题检查表。

自测:为什么新增日志放在 onCreate,重复打开已存在的页面却可能看不到新日志?Activity 可能被复用;本实验通过停止进程后显式启动建立一次新的创建过程。

1.8 常见问题按阶段定位

先判断失败发生在下载、配置、构建、启动还是功能验证,再看对应输入输出。不要一遇到异常就清空 out 或重新同步全部源码,那会丢失线索,也不一定改变问题条件。

症状先理解什么第一检查项与后续处理
TLS / promisor remote 错误补下载对象可能因连接中断失败见 TLS 案例,看失败项目与最终退出码
sync 后空目录或 index.lock空树、检出失败、残留锁要分别判断见 检出案例 与 静默和锁案例
Repo 显示 NO BRANCHdetached HEAD 是检出方式,不等于下载失败用项目提交和本地状态判断;需要开发分支时再为相关项目创建分支
lunch 找不到命令它由 envsetup.sh 定义在当前 shell 中在当前 Bash 终端加载脚本;核对源码目录与 PATH
lunch 提示产品或 release 无效项目存在不代表任意配置组合有效用本版本的 list_products、list_releases 查询,再显式指定三个参数
signal 9 / 长时间 Soong 分析需要对齐进程、时间和内存证据见 内存案例,不要因缓慢反复重启
nsjail Permission denied探测退化与具体动作失败不同见 nsjail 案例,结合 AppArmor 日志
super.img 空间不足Host 空间与目标镜像容量不同见 容量案例,检查最终配置与失败动作
构建报 action cancelled取消可能由另一个任务的失败引起在本次完整日志中找首个有诊断内容的失败;并行日志顺序也需结合依赖分析
memory stall 或构建很慢资源压力会影响调度,不能仅凭这条信息认定 OOM用 free、vmstat 看内存和换页;有权限时查看内核 OOM 记录,再调整并发
No AVD / GPU 与 ADB 提醒分别检查产品环境与 Emulator 工具配置见 启动环境、工具提醒;KVM 前置检查见 1.1
更新后无法完成开机镜像与启动校验参数可能不匹配见 AVB 案例,先证据后归因
ADB offline 或一直无法完成启动ADB 通道、Kernel、Android 启动是不同层次保存 Emulator 输出,先确认虚拟机仍在运行;能够连接后再采集 logcat;按失败阶段定位
APK 编译成功但日志不出现编译、分区打包、冷启动和 Activity 创建各有边界核对 system_ext.img 与 system-qemu.img 已更新、快照关闭、启动的是指定 Activity
新动画未出现或改错启动画面资源、播放器、FallbackHome 与 Launcher 分别判断见 动画修改案例,先确认目标与显示阶段
adb remount 失败userdebug 不意味着所有分区天然可写本章走离线重打包与冷启动路径;研究部署优化时再解释 AVB、overlayfs 与权限条件

例如,TLS 错误经过重试后仍可能以同步成功结束;action cancelled 也可能是上游失败导致的连带取消。判断结果要看完整过程和最终退出状态,判断根因则需要找到解释该结果的具体错误。

1.9 回顾 自测与速查

用自己的话把过程连起来

Repo 根据 manifest 取得多个 Git 项目,固定提交和本地改动共同描述源码输入。lunch 选择产品、发布配置和构建类型。m 进入 soong_ui,由构建系统生成规则,再交给本版本选定的执行器运行。模块产物装入分区,Emulator 使用与该产品匹配的镜像和 Kernel 启动 Android。最后通过 ADB 进入目标页面、观察日志,并把运行结果对应回源码修改。

从源码到运行结果的六步工程路线

先检查环境与目录基础

  1. 源码大小为什么不能直接当作磁盘需求?因为还要保存构建中间文件、工具与镜像,见 1.1。
  2. packages/apps/Settings、SettingsHomepageActivity.java、Settings 三者是什么关系?分别是 Git 项目路径、源码文件和构建模块名称,见 1.3。
  3. hardware、kernel 和 out 分别能说明什么?前者常见 HAL 等用户空间接口,Kernel 材料需核对来源,out 是生成结果,不能仅凭目录名推断全部实现,见 1.3。

再串起编译与运行

  1. 一个 manifest 仓库提交,为什么不能代表全部 AOSP 的精确版本?
  2. 新格式 lunch sdk_phone64_x86_64 为什么可能没有得到 userdebug?
  3. product 名称里有 x86_64,为什么输出目录叫 emu64x?
  4. m、Soong、Clang、Siso 分别负责哪一部分?
  5. 为什么 m Settings 成功后,本章还需要重新打包镜像并冷启动?
  6. 把日志打印改到另一个 Activity,仍启动原页面,应该预期什么?
  7. 设备的 uname 显示 6.12,能否据此选任意一个 6.12 分支阅读 Binder Driver?
  8. 实际完成一次修改与验证后,应保留哪些最小材料?若之后选择恢复,还应保留什么?

参考答案:

  1. manifest 可以引用移动分支;各项目实际提交和本地改动需另外固定。见 1.2 的快照部分。
  2. 本版本新格式在省略 release、variant 时补 trunk_staging、eng;应显式写全。见 1.4 的 lunch 源码。
  3. PRODUCT_NAME 是产品配置名称,PRODUCT_DEVICE 是设备名称;本产品的后者为 emu64x。见 1.4 的产品定义。
  4. m 是入口;Soong 处理模块及规则生成,Kati 处理兼容的 Make 配置;Clang 等工具执行具体编译;Siso 按生成的规则调度任务。见 1.5。
  5. 模块构建不会让已启动系统自动换代码;Settings 位于 system_ext,设备还可能使用旧镜像、旧进程或快照。见 1.7。
  6. 新日志可能不会出现;必须触发真正修改的组件,并确认发生新的 onCreate。见 1.7 的显式 Activity 启动。
  7. 不能。版本号不能识别准确提交、配置、模块来源和本地补丁;需追溯预编译来源。见 1.6。
  8. 源码快照与本地改动、构建配置与日志/退出码、镜像摘要、启动命令、运行属性及本轮日志;只有之后选择恢复时,才另记恢复过程与结果。见各操作小节。

常用命令按用途查

下表是定位入口,参数、条件与输出解释在对应正文中。命令在本章 Host Bash 环境执行,设备命令使用已确认的 serial。

目的命令主要输出或作用
看项目状态repo status本地修改与未跟踪文件
固定 Git 基线repo manifest -r -o 文件.xml各项目的提交快照
看当前目标printf '%s\n' "$TARGET_PRODUCT / $TARGET_RELEASE / $TARGET_BUILD_VARIANT"当前终端配置
查询配置lunch --help;list_releases 产品名用法与所选产品的 release
构建系统m -j2当前产品的默认构建目标
构建模块m Settings -j2Settings 与所需依赖产物
更新本章镜像m systemimage systemextimage -j2相关镜像与 Emulator 打包依赖
观察设备adb -s serial shell getprop设备属性
找实际 APKadb -s serial shell pm path com.android.settings设备使用的安装路径
观察实验日志adb -s serial logcat -d -s SettingsHomepageActivity:I '*:S'指定 tag 的历史缓冲日志

源码与学习成果入口

源码摘录采用下列项目基线。复现实验时,按 1.2 保存自己工作区的完整 manifest、本地改动和必要素材;下表只列出本文直接分析的项目。

项目提交本章用途
build/make5ce6f787337d0223710bf7d4a16dbe6d2a35f777envsetup、镜像打包
build/soong6722dd8833db7482df1a2543ca3fcf67ddf0f7b1m、soong_ui、执行器
device/generic/goldfish296e55aa0244e8929e393e00e34471fef2a5d662SDK Emulator 产品与 Kernel 选择
packages/apps/Settings213829fb67f5e070029e0513a088f31bc8f5c1edJava 修改、模块与安装分区
device/google/cuttlefish283645aacf6cdb56cc31a9362f54d412dbc132a1对照 Cuttlefish 的配置边界

本章实验完成后,第二章将以一次 Binder 调用为线索进入进程间通信。第一章解决的工程对应关系,会继续用于判断“正在读的 Binder 实现”是否就是运行设备实际使用的实现。

参考资料