AOSP编译环境搭建与避坑指南

AOSP编译环境搭建与避坑指南

发布时间：2026/8/9 8:13:04
AOSP编译环境搭建与避坑指南 1. AOSP编译环境搭建的血泪史第一次接触AOSP源码编译是在2016年当时为了给一台老旧的Nexus 5定制ROM。那会儿Ubuntu 16.04刚发布不久我兴冲冲地按照官方文档操作结果在repo sync阶段就卡了三天——公司网络有代理限制而Google的git仓库经常连接超时。这段经历让我明白编译AOSP不仅是技术活更是对耐心和网络环境的终极考验。十年间我参与过数十个AOSP相关项目从手机厂商的ROM定制到车机系统开发踩过的坑足以写本手册。今天就把这些实战经验系统梳理出来重点分享那些官方文档不会告诉你的坑位分布和逃生技巧。无论你是想学习Android系统架构还是需要定制企业级设备系统这些经验都能让你少走弯路。2. 编译环境准备的三大陷阱2.1 操作系统选择的门道官方推荐Ubuntu LTS版本但这里面有讲究Ubuntu 18.04是最后的32位兼容版本适合老旧设备编译20.04开始默认python3要注意脚本兼容性22.04需要额外处理glibc版本问题实测发现对于较新的AOSP版本Android 12在Ubuntu 20.04上最稳定。我曾尝试在Arch Linux上编译结果在ninja阶段出现诡异的符号冲突最终不得不切换回Ubuntu。重要提示千万不要使用WSL我曾在WSL2上耗费两周时间最终在kernel构建阶段因文件系统性能问题失败。虚拟机的选择也有讲究——VMware比VirtualBox的IO性能更好建议分配至少200GB空间和16GB内存。2.2 依赖包安装的隐藏关卡官方文档的sudo apt-get install命令并不完整缺少这些关键包# 补充这些依赖项 sudo apt-get install libncurses5 libssl-dev bc flex bison build-essential zip curl zlib1g-dev gcc-multilib g-multilib libxml2-utils unzip python2.7 python3-dev lib32z1-dev libx11-dev lib32z1 ccache libgl1-mesa-dev libxml2-utils xsltproc fontconfig特别是lib32z1-dev这个包缺少它会导致zlib链接错误。去年帮某车企定制车机系统时团队新人就因为漏装这个包在编译三天后突然报错不得不从头开始。2.3 Java版本的时间陷阱AOSP的Java版本要求严格对应Android 5.x-6.xOpenJDK 7Android 7.x-8.xOpenJDK 8Android 9-10OpenJDK 9Android 11OpenJDK 11最坑的是Android 7-8的版本必须使用特定版本的OpenJDK 8。去年有个智能家居项目客户要求基于Android 8.1定制我用Ubuntu默认的OpenJDK 8编译总是报错最后发现必须用Oracle JDK 8u191版本。3. 源码下载的五个生死劫3.1 repo工具的镜像配置官方源在国内基本无法使用必须配置清华镜像export REPO_URLhttps://mirrors.tuna.tsinghua.edu.cn/git/git-repo但要注意同步问题2021年某次镜像同步延迟导致我们团队下载的源码缺少vendor分支编译出的镜像无法启动。现在我会在repo sync后额外执行repo forall -c git lfs pull3.2 磁盘格式的隐藏要求EXT4文件系统是必须的NTFS或FAT32会导致符号链接错误。我曾遇到一个奇葩案例开发者将源码放在exFAT格式的移动硬盘编译到90%时出现Too many open files错误。解决方案# 创建ext4镜像文件 dd if/dev/zero ofaosp.img bs1G count200 mkfs.ext4 aosp.img sudo mount -o loop aosp.img /mnt/aosp3.3 网络断连的抢救方案repo sync可能持续数小时推荐使用tmuxtmux new -s sync ctrlb d # 脱离会话 tmux attach -t sync # 重连如果中断不要直接重新sync先执行repo sync -c -j4 --fail-fast-c参数只同步当前分支-j4控制并发数--fail-fast遇到错误立即停止。3.4 版本选择的玄学通过repo init指定分支时官方文档的标签可能过时。比如最近Android 13的稳定版标签应该是android-13.0.0_r41而非文档中的_r35。建议查看 Google的构建编号页面 获取最新信息。3.5 预构建二进制文件的坑某些厂商驱动如NVIDIA显卡驱动需要额外下载。我曾为一块开发板编译AOSP结果因为缺少GPU驱动系统启动后黑屏。解决方案是在device/vendor/device目录下创建proprietary-blobs.txt文件格式如下vendor/lib/egl/libEGL_tegra.so vendor/lib/hw/gralloc.tegra.so4. 编译过程的六个夺命坑4.1 lunch菜单的幽灵选项执行lunch时可能遇到Device not found错误。这是因为某些设备需要先导入厂商配置。比如为Pixel 3编译时source build/envsetup.sh lunch aosp_blueline-userdebug # Pixel 3代号blueline如果lunch列表为空检查是否执行了source build/envsetup.sh。去年有个实习生连续三天卡在这个问题最后发现是因为在子shell中操作。4.2 Jack编译器的内存黑洞Android 7-8使用Jack编译器极易OOM。必须在~/.jack中配置SERVER_NB_COMPILE1 SERVER_TIMEOUT60 ANDROID_JACK_VM_ARGS-Dfile.encodingUTF-8 -XX:TieredCompilation -Xmx8G对于16GB内存的机器建议export JACK_SERVER_VM_ARGUMENTS-Dfile.encodingUTF-8 -XX:TieredCompilation -Xmx6g -Xms6g ./prebuilts/sdk/tools/jack-admin kill-server ./prebuilts/sdk/tools/jack-admin start-server4.3 ccache的配置艺术正确配置ccache可提升30%编译速度export USE_CCACHE1 export CCACHE_DIR/mnt/ccache # 建议放在SSD上 prebuilts/misc/linux-x86/ccache/ccache -M 50G # 设置缓存大小但要注意跨分支编译时必须清空缓存我有次从Android 10切换到11编译因为缓存污染导致各种诡异错误。4.4 ninja的并行控制通过-j参数控制并行任务数建议设置为CPU线程数的1.5倍。但遇到内存不足时make -j4 # 保守方案监控内存使用watch -n 1 free -h4.5 模块化编译技巧不需要每次都完整编译。比如只修改了Settings应用mmm packages/apps/Settings make snod # 重新生成system.img但要注意某些模块有依赖关系。我有次只编译了SystemUI结果导致系统服务崩溃。4.6 构建错误的黄金排查法遇到构建错误时查看out/error.log和out/soong.log搜索FAILED:后的第一个错误对C错误重点关注头文件包含路径Java错误检查类冲突和注解处理器典型错误案例error: overriding commands for target out/target/product/generic/system/etc/permissions/platform.xml这通常是因为PRODUCT_COPY_FILES中有重复定义。5. 刷机与调试的三大险滩5.1 镜像打包的格式差异不同设备需要不同的镜像组合大部分设备system.img vendor.img boot.img新设备super.img动态分区某些MTK设备还需要preloader.img生成super.img的特殊命令lpmake --metadata-size 65536 --super-name super --metadata-slots 2 --device super:4294967296 --group main:3221225472 --partition system:readonly:1610612736:main --image systemout/target/product/generic/system.img --partition vendor:readonly:536870912:main --image vendorout/target/product/generic/vendor.img --output out/target/product/generic/super.img5.2 ADB连接的暗礁设备连接后没反应试试sudo ~/android-sdk/platform-tools/adb kill-server sudo ~/android-sdk/platform-tools/adb start-server adb devices对于Linux系统还需要配置udev规则echo SUBSYSTEMusb, ATTR{idVendor}18d1, MODE0666 | sudo tee /etc/udev/rules.d/51-android.rules sudo udevadm control --reload-rules5.3 日志分析的进阶技巧除了logcat这些日志也很关键dmesg # 内核日志 cat /proc/kmsg # 实时内核日志 dumpstate # 系统状态快照对于启动问题可以adb shell setprop logd.kernel true adb shell cat /proc/last_kmsg last_kmsg.log6. 企业级定制开发的实战经验6.1 厂商代码的整合策略与厂商合作时他们会提供闭源驱动包。标准整合流程解压到vendor/company/device创建AndroidBoard.mk和BoardConfig.mk更新device.mk包含驱动模块关键点驱动版本必须与内核版本严格匹配。去年有个项目因为内核版本差了一个小版本号导致WiFi驱动无法加载。6.2 系统签名的密钥管理自定义系统需要自己的平台密钥development/tools/make_key platform /CUS/STCalifornia/LMountain View/OAndroid/OUAndroid/CNAndroid/emailAddressandroidandroid.com安全建议将密钥存储在HSM中为不同部门分配不同密钥定期轮换密钥6.3 性能优化的黄金法则通过BoardConfig.mk调整# 内核优化 TARGET_KERNEL_CFLAGS -O2 -pipe -fomit-frame-pointer # 内存配置 PRODUCT_PROPERTY_OVERRIDES \ dalvik.vm.heapstartsize8m \ dalvik.vm.heapgrowthlimit96m \ dalvik.vm.heapsize256m实测案例为某POS设备优化后应用启动速度提升40%内存占用减少25%。7. 那些年我遇到的奇葩问题7.1 时区导致的编译失败某次在UTC8时区编译总是报错error: Timestamp check failed原因是某些Java工具对时区敏感解决方案export JAVA_TOOL_OPTIONS-Duser.timezoneGMT7.2 文件名大小写引发的血案在MacOS上开发然后到Linux编译报错File not found: frameworks/base/core/java/android/Manifest.java原因是MacOS不区分大小写而Linux区分。解决方案find . -type f -name *.java | while read file; do git mv $file ${file}.tmp git mv ${file}.tmp $(echo $file | tr [:upper:] [:lower:]); done7.3 杀毒软件吃掉关键文件某Windows开发者使用虚拟机编译总是随机失败。最后发现是杀毒软件将prebuilts目录下的某些exe文件误删。解决方案将整个AOSP目录加入杀毒软件白名单或者干脆在Linux物理机上编译8. 效率提升的终极方案8.1 分布式编译实战配置distcc分布式编译export DISTCC_DIR/path/to/distcc export DISTCC_HOSTSlocalhost 192.168.1.100 192.168.1.101 export CCdistcc gcc export CXXdistcc g make -j32注意事项所有机器必须使用相同的工具链版本网络延迟要低于5ms主控机需要有足够的内存8.2 增量编译的智能判断通过mka替代makemka baconmka会自动计算最优的并行任务数。更智能的方案#!/bin/bash if [ -f out/build.ninja ]; then ninja -f out/build.ninja else make -j$(nproc --all) fi8.3 自动化监控脚本编译时实时监控watch -n 1 ps aux | grep -E ccache|gcc|g | grep -v grep; echo; df -h; echo; free -h邮件通知脚本make 21 | tee build.log if [ $? -eq 0 ]; then mail -s Build Success teamcompany.com build.log else mail -s Build Failed teamcompany.com build.log fi十年AOSP编译经验告诉我每个错误都有原因每次失败都是成长。记得2018年那个连续编译失败三周的项目吗最终发现是因为Ubuntu自动更新了binutils导致链接器行为变化。现在我的~/.bashrc里永远写着export DEBIAN_FRONTENDnoninteractive sudo apt-mark hold binutils保持环境稳定比追求新特性更重要。这也是为什么我的编译服务器从不开启自动更新。希望这些经验能帮你避开我踩过的坑在AOSP的海洋里顺利航行。