1. 项目概述为什么模块清理是Android源码编译的“必修课”如果你正在或曾经参与过Android系统的深度定制、ROM开发或者仅仅是出于学习目的下载过那动辄几十GB的AOSP源码那么“编译”这个词对你来说一定不陌生。从source build/envsetup.sh到lunch再到最终的make -jN这一套流程走下来少则一两个小时多则大半天。然而编译过程并非总是一帆风顺一个常见的拦路虎就是当你修改了某个模块的代码或者调整了编译配置后重新执行make预期的变更却没有生效或者出现了各种光怪陆离的编译错误。这时有经验的开发者会告诉你“清理一下再编。”这个“清理一下”指的就是我们今天要深入探讨的核心——Android源码的模块清理。模块清理远不止是简单地在模块目录下执行一个make clean。在Android如此庞大且高度模块化的构建系统Soong/Bazel与Make并存中理解清理的粒度、时机和背后的原理是提升开发效率、避免无谓等待的关键。它直接关系到你的编译缓存是否有效、增量编译是否可靠以及最终生成的镜像是否纯净。网络上搜索“make clean”时常伴随出现“make没有指明目标并且找不到makefile”、“error (209014): conf_done pin failed to go high”等看似不相关的错误其实很多都源于对构建中间状态管理不当。因此掌握模块清理技巧是每一位Android系统开发者从“会编译”到“高效编译”进阶的必经之路。2. 核心需求解析我们到底在清理什么在动手之前我们必须先搞清楚Android构建系统产生了哪些“中间产物”以及我们清理的目标是什么。盲目地全量清理如make clean固然能解决问题但代价是数小时的重新编译时间这显然不是高效的做法。2.1 构建产物的多层次结构Android的构建输出主要位于out目录下其结构是理解清理的基础out/soong/.bootstrap和out/soong/.minibootstrap这是Soong构建系统自身的引导和最小化引导输出目录。Soong是Android新的构建系统用于解析Android.bp文件。通常我们不需要手动清理这里。out/soong/build.ninja这是Soong根据所有Android.bp文件生成的Ninja构建脚本。Ninja是一个专注于速度的小型构建系统。当你修改了Android.bp或涉及模块依赖关系时这个文件会重新生成。out/soong/.intermediates这是模块清理的重中之重。几乎所有模块的编译中间文件都存放在这里。例如一个名为libexample的模块其.o对象文件、.a静态库、未链接的.so动态库等都会存在于类似out/soong/.intermediates/packages/modules/Example/libexample的路径下。清理特定模块主要就是清理这个目录下对应的子目录。out/target/product/device_name/obj这里存放的是目标设备相关的中间对象文件特别是那些由传统的Android.mk定义的模块。它与out/soong/.intermediates有重叠但体系不同。随着Android版本迭代Android.bp是主流但仍有大量遗留代码使用Android.mk。out/target/product/device_name/systemout/target/product/device_name/vendor等这些是最终生成的系统镜像的组成部分包含了打包好的APK、库文件、配置文件等。清理模块后这些目录下的对应文件也需要被移除或更新。out/dist分发目录存放一些用于发布的工具包或符号文件。Ninja构建缓存Soong/Ninja有内部缓存机制来加速增量编译。有时缓存不一致会导致问题。2.2 何时需要进行模块清理理解了产物结构我们就能判断清理的时机修改了模块的源代码.cpp .java .kt等理论上Ninja的增量编译机制能自动检测到并重新编译该模块。这是最理想的情况。修改了模块的构建脚本Android.bp或Android.mk例如添加或删除了源文件、修改了编译标志CFLAGS LDFLAGS、改变了依赖关系。这种情况增量编译经常失效因为构建系统生成的Ninja文件build.ninja可能没有正确更新。此时必须清理该模块。切换了编译目标lunch选择了不同的设备或版本从aosp_arm-eng切换到aosp_x86_64-userdebug大部分中间产物不兼容需要清理。通常使用make installclean来处理。遇到了无法解释的编译错误或链接错误例如报错找不到某个符号但明明代码里有或者生成的库版本不对。这常常是陈旧的中间文件在“作祟”。清理是首要的排查步骤。需要释放磁盘空间out目录是磁盘空间消耗大户。定期清理不活跃设备的中间文件可以节省大量空间。注意频繁且无差别的make clean是效率的敌人。我们的目标是进行精准的、最小粒度的清理以最短的时间恢复到一个正确的编译状态。3. 精准清理从模块级到文件级的操作指南Android提供了多种不同粒度的清理命令我们需要根据实际情况选择。3.1 针对单个模块的清理这是最常用也最应该掌握的技巧。假设你要清理一个名为libexample的模块。方法一使用mma/mmma的清理模式在源码根目录下首先设置好环境并选择目标设备source build/envsetup.sh lunch aosp_x86_64-userdebug # 以x86_64模拟器为例然后进入你模块所在的目录或者在任何目录下指定模块路径# 清理当前目录下的模块 mmm . -c # 或 mm -c # 清理指定路径的模块 mmm packages/modules/Example -c这里的-c参数就代表clean。mmmmake module in directory用于编译或不带-c时或清理指定目录下的模块。mm是mmm .的简写即处理当前目录。方法二使用make命令直接指定模块目标你也可以在源码根目录直接操作make clean-module_name例如make clean-libexample这个命令会精准地定位到libexample模块的所有中间产物并删除。如何知道模块的确切名称可以查看模块的Android.bp文件中的name属性或者Android.mk中的LOCAL_MODULE。实操心得我更喜欢使用方法二make clean-module_name。因为它不依赖于当前工作目录在任意位置都可以执行而且目标明确。方法一需要你先cd到模块目录或知道准确路径在大型源码树中穿梭有时不那么方便。3.2 针对多个模块或一个目录的清理如果你修改了一个库及其多个依赖模块或者修改了一个公共头文件影响了多个模块可能需要批量清理。清理一个目录下的所有模块使用mma或mmma配合-c指定目录即可如上文的mmm packages/modules/Example -c。清理多个特定模块可以连续使用多个make clean-module_name命令或者写一个简单的Shell循环。使用make clean-tagAndroid构建系统支持模块标签Tags比如make clean-ALL_MODULES会清理所有模块相当于make clean但更底层一些。但日常开发中直接使用标签的情况较少。3.3 不同粒度的全局清理命令当模块清理无法解决问题或者你进行了更广泛的更改时就需要更大范围的清理。make installclean这是最常用、最安全的“中度”清理命令。它会删除out/target/product/device_name/下的所有内容如system.img,vendor.img,obj/中目标文件等但保留out/soong/.intermediates中的主机工具如adb,fastboot和部分中间产物。这意味着你的设备专属镜像需要重新生成。但Soong/Ninja的构建图缓存和主机工具不需要重新编译下次编译速度仍然较快。适用场景切换lunch目标后、修改了系统全局配置如BoardConfig.mk、或者遇到了奇怪的系统镜像相关问题。make clean重型清理。它会删除整个out目录out/本身除外。这意味着所有中间产物、主机工具、最终镜像都会被清除。下一次编译将是从头开始from scratch耗时最长。适用场景构建系统本身进行了重大升级如repo sync了构建工具链、磁盘空间严重不足、或者任何其他清理手段都无效时的“终极手段”。rm -rf out/手动核弹。效果等同于make clean但更“暴力”。不推荐直接使用因为make clean可能还会执行一些额外的清理钩子。但在某些极端情况下如文件权限错乱直接删除out目录可能是唯一选择。选择策略流程图遇到编译问题 | v 尝试 make clean-module_name (针对单个模块) | \ | \ 问题未解决或涉及多个模块/配置 | \ v v 问题解决 尝试 make installclean | | | | v v 完成 问题解决 | | v 是/否 / \ / \ / \ v v 完成 终极方案make clean4. 高级技巧与疑难杂症排查掌握了基本命令我们来看看一些更深入的问题和技巧。4.1 当make clean-module不奏效时有时候你执行了模块清理重新编译但问题依旧。这可能是因为依赖模块未被清理你的模块A依赖模块B。你只清理了A但B的接口或实现变了而B的陈旧中间产物还在。你需要递归地清理其依赖链。一个笨但有效的方法是清理该模块所在整个子系统的中间目录。例如怀疑frameworks/base下的问题可以尝试谨慎操作rm -rf out/soong/.intermediates/frameworks/base/ rm -rf out/target/product/device_name/obj/JAVA_LIBRARIES/framework*_intermediates/ # 示例路径可能不同Ninja缓存或Soong状态不一致可以尝试强制重新生成Ninja文件并清理Soong缓存# 删除Soong的运行状态和缓存 rm -rf out/soong/.bootstrap out/soong/.minibootstrap out/soong/.soong.in_make # 删除生成的Ninja文件 rm -f out/soong/build.ninja out/soong/build.ninja.d # 然后重新执行source/lunch再编译 source build/envsetup.sh lunch your_target make -jN这个操作相当于让Soong重新解析所有Android.bp文件适用于修改了大量构建脚本后的情况。4.2 与IDEAndroid Studio的协同如果你使用Android Studio进行AOSP模块开发比如开发一个系统APPIDE内部也有编译和缓存。Android Studio的缓存在菜单栏选择File Invalidate Caches and Restart...可以清理IDE的索引和缓存这在代码导航、索引出错时很有用但它不清理AOSP的out目录。Gradle缓存对于包含build.gradle的模块如一些Java库、APPGradle也有自己的缓存通常在~/.gradle/caches/。在AOSP环境中Soong会调用Gradle但通常Soong会管理其生命周期。极端情况下可以手动清理Gradle缓存但这不是首选方案。最佳实践在Android Studio中修改AOSP代码后建议通过终端执行AOSP的编译命令make或mma来构建模块。确保你的Android Studio项目是从AOSP根目录导入的这样它才能识别正确的SDK和依赖。4.3 磁盘空间管理AOSP编译一次out目录占用几十GB是常事。定期清理不用的设备输出非常必要。查看占用空间du -sh out/target/product/* | sort -hr选择性删除直接rm -rf out/target/product/your_old_device_name。如果你确定不再编译某个设备可以删除整个产品目录。使用ccache正确配置ccache可以显著加速重复编译并可能因为缓存复用而略微减少out目录的增量大小。但ccache本身也会占用磁盘空间默认5GB需要权衡。4.4 常见错误与make clean的关系回顾网络热词中的一些错误其实都与状态清理有关make没有指明目标并且找不到makefile这通常发生在错误的目录下执行make或者构建环境没有正确设置没执行source build/envsetup.sh。与clean无关但提醒我们必须在正确的上下文中工作。error (209014): conf_done pin failed to go high in device这是一个FPGA编程错误看起来与Android编译无关被搜索到可能只是因为它包含了“make sure”和“make”。这提醒我们搜索错误信息时要结合上下文。xaudio2.7 is not installed这是一个Windows环境下编译某些项目时缺失系统库的错误。在Android源码编译中如果主机环境依赖缺失应该在首次编译前解决而不是靠clean。Bypass paywalls clean这是一个浏览器插件名称与编译清理毫无关系属于关键词巧合。核心原则只有当问题表现为“编译产物与源代码预期不一致”时才优先考虑清理操作。对于环境配置、语法错误、缺失文件等问题清理是无效的。5. 自动化与最佳实践将清理融入工作流手动清理固然可以但将其自动化能进一步提升效率。5.1 编写辅助脚本你可以在你的Shell配置文件中如~/.bashrc或~/.zshrc添加一些函数# 快速清理当前目录模块并重新编译 function mmc() { mm -c mm } # 清理指定模块 (用法: mclean libexample) function mclean() { for module in $; do echo Cleaning module: $module make clean-$module done } # 安全的重置编译环境 (保留主机工具) function rebuild() { make installclean make -j$(nproc) }5.2 版本控制与清洁编译在repo sync之后同步代码后特别是大版本更新时构建系统本身可能变化。建议执行一次make installclean然后重新lunch和编译。这比全量clean要快又能保证一致性。提交代码前在本地完成模块编译测试后建议在干净的输出环境下或至少执行make installclean后进行一次完整的make -jN以确保你的修改不会破坏全局编译。CI/CD系统通常就是从零开始编译的。5.3 心理模型建立状态管理意识最终最高效的清理策略来源于你对Android构建系统状态的心理模型。你需要意识到源代码aosp/目录下是唯一的真相来源。out目录是一个纯粹的、可丢弃的缓存。它的唯一作用是加速编译。任何时候你都可以重建它代价是时间。Soong/Ninja是状态机。它们根据输入源码、bp/mk文件生成输出中间文件、镜像。当输入变化时状态机应该能正确过渡。清理操作是我们在状态机可能“卡住”时手动进行的“重置状态”操作。粒度意识总是从最小的可能粒度单个模块开始尝试清理逐步扩大范围。掌握Android源码的模块清理就像一位熟练的机械师懂得何时只需拧紧一颗螺丝何时需要更换整个部件何时又该对发动机进行大修。它不会让你的代码写得更好但能让你在发现问题、验证想法时速度更快从而将宝贵的时间聚焦在真正的开发与创新上。在庞大的AOSP源码面前高效的编译状态管理是保持开发节奏流畅、心绪平稳的重要技能。