1. 代码开发工具视角下的 ntfs-3g:为什么绕不开 Android.mk
代码开发工具里,Android 构建系统算是一个不太直观的角色:没有可视化工程文件,所有编译意图都压在 Android.mk 的变量里。要把 ntfs-3g 这套 FUSE 用户态文件系统塞进 Android,从 mm 编译到最终挂载,第一步不是改源码,而是把 Android.mk 写对。我见过不少人直接拿 Linux 下的 Makefile 改个名字就开编,结果卡在找不到头文件、模块名带横线、共享库没链上这些地方。
这套移植的核心是两个构建目标:libntfs-3g 静态库和 ntfs-3g 可执行文件。前者承载 NTFS 解析逻辑,后者负责 FUSE 会话和命令行参数。下面按这两个目标拆开讲,适合正在做 Android 用户态文件系统移植、需要照着改 Android.mk 的开发者。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码开发工具的第一层拆解:Android.mk 里两个模块怎么分工
2.1 为什么拆成静态库和可执行文件
这份移植源码的 Android.mk 核心是两个模块:一个静态库承载 NTFS 解析逻辑,一个可执行文件负责 FUSE 会话和命令行参数。拆成两个模块的好处是主程序编译快,库可以被其他模块复用;坏处是静态库的头文件导出路径必须写对,否则主程序找不到 ntfs-3g.h。
如果图省事,把所有 .c 都塞进可执行文件,第一次编译可能也能过,但后面想给别的模块复用解析逻辑就麻烦了。更现实的问题是,库源码和主程序源码的 include 路径、编译宏、警告级别并不完全一样,混在一起编会让 Android.mk 越来越难读。拆开之后,静态库只关心自己的源文件和导出头文件,主程序只关心链接谁、依赖哪些共享库。
静态库和可执行文件之间通过 LOCAL_STATIC_LIBRARIES 建立依赖。构建系统会先编静态库,再编可执行文件,不需要手工指定顺序。这个依赖关系写错,常见现象是主程序链接时报一堆 undefined reference,但库本身其实已经编出来了。
2.2 一份可编译的最小 Android.mk
下面是我按这份源码结构整理的最小 Android.mk,字段含义逐段说明。代码里的注释标出了每个模块的职责,后面再逐变量拆。
makefile复制LOCAL_PATH := $(call my-dir)
# 模块一:NTFS 核心库,编成静态库供主程序链接
include $(CLEAR_VARS)
LOCAL_MODULE := libntfs-3g
LOCAL_SRC_FILES := $(wildcard $(LOCAL_PATH)/libntfs-3g/*.c)
LOCAL_C_INCLUDES := \
$(LOCAL_PATH)/include \
$(LOCAL_PATH)/fuse/include
LOCAL_CFLAGS := \
-DHAVE_CONFIG_H \
-D_FILE_OFFSET_BITS=64 \
-DFUSE_USE_VERSION=26 \
-Wno-unused-parameter
LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)/include
include $(BUILD_STATIC_LIBRARY)
# 模块二:主程序,模块名不能带横线,输出名用 STEM 控制
include $(CLEAR_VARS)
LOCAL_MODULE := ntfs3g
LOCAL_MODULE_STEM := ntfs-3g
LOCAL_SRC_FILES := src/ntfs-3g.c
LOCAL_STATIC_LIBRARIES := libntfs-3g
LOCAL_SHARED_LIBRARIES := libfuse libselinux
LOCAL_C_INCLUDES := \
$(LOCAL_PATH)/include \
$(LOCAL_PATH)/fuse/include
LOCAL_CFLAGS := \
-DHAVE_CONFIG_H \
-D_FILE_OFFSET_BITS=64 \
-DFUSE_USE_VERSION=26
LOCAL_LDLIBS := -llog -ldl
include $(BUILD_EXECUTABLE)
逻辑说明:第一个 include $(CLEAR_VARS) 清空上一轮变量,避免模块间串值;LOCAL_SRC_FILES 用 wildcard 收集库源码,省去逐个列文件,但要注意 libntfs-3g 目录下如果有 *_test.c 会被一起编进去,必要时改成显式列表。LOCAL_EXPORT_C_INCLUDES 让依赖这个静态库的模块自动获得头文件路径,主程序就不必重复写库的 include。第二个模块的 LOCAL_MODULE 用 ntfs3g 而不是 ntfs-3g,因为 Android 构建系统对模块名里的横线兼容性不好,容易在中间产物路径上翻车;LOCAL_MODULE_STEM 把最终文件名改回 ntfs-3g,命令行调用习惯不变。
2.3 逐变量看构建系统的输入输出
把变量按“给谁用”分成三类,后面改起来不容易乱。
| 变量 | 作用 | 本工程取值 | 注意点 |
|---|---|---|---|
LOCAL_PATH |
当前 Android.mk 所在目录 | $(call my-dir) |
每个 Android.mk 开头写一次,后续相对路径都靠它 |
LOCAL_MODULE |
构建系统内部模块名 | libntfs-3g、ntfs3g |
主程序模块名不带横线,依赖时用这个名字 |
LOCAL_SRC_FILES |
参与编译的源文件 | wildcard 收集库源码、src/ntfs-3g.c |
wildcard 可能把测试文件带进来 |
LOCAL_C_INCLUDES |
当前模块编译时的头文件路径 | include、fuse/include |
只影响自己,不影响依赖者 |
LOCAL_EXPORT_C_INCLUDES |
导出给依赖者的头文件路径 | include |
静态库专有,主程序靠它找 ntfs-3g.h |
LOCAL_CFLAGS |
编译宏和警告选项 | 四个宏 | 主程序也要写一遍,宏会影响头文件展开 |
LOCAL_STATIC_LIBRARIES |
链接静态库 | libntfs-3g |
写模块名,不写 .a 文件名 |
LOCAL_SHARED_LIBRARIES |
链接共享库 | libfuse、libselinux |
运行时还需要设备上有对应库 |
LOCAL_LDLIBS |
额外链接参数 | -llog -ldl |
不要把静态库塞到这里 |
LOCAL_MODULE 和 LOCAL_MODULE_STEM 的区别值得单独说:前者是构建系统索引模块用的名字,后者是最终输出文件的 stem。主程序依赖静态库时写 LOCAL_STATIC_LIBRARIES := libntfs-3g,这里用的是静态库的 LOCAL_MODULE,不是它的输出文件名。两处名字对不上,链接就会失败。
LOCAL_CFLAGS 在主程序里又写了一遍,不是重复劳动。FUSE_USE_VERSION 这类宏会影响 FUSE 头文件展开的结构体布局,库和主程序必须一致;只在库里写,主程序包含 fuse.h 时可能按默认版本展开,编译能过,运行却出现结构体字段错位。这个坑后面还会展开。
3. 静态库不是编出来就行:libntfs-3g 的源文件收集与头文件导出
3.1 wildcard 收集源文件的便利与边界
LOCAL_SRC_FILES := $(wildcard $(LOCAL_PATH)/libntfs-3g/*.c) 的好处是新增库源码不用改 Android.mk,坏处是目录里放什么就编什么。libntfs-3g 目录下如果有单元测试文件、示例程序或者临时调试文件,也会被一起编进静态库。静态库本身不报错,等到主程序链接时才发现多了 main 或者重复符号,排查起来很绕。
更稳妥的做法是显式列出参与编译的源文件,或者在 wildcard 外面加一层过滤。比如测试文件统一以 _test.c 结尾,就可以这样处理:
makefile复制# 过滤掉测试源文件,避免测试 main 被编进静态库
LOCAL_SRC_FILES := $(filter-out %_test.c,$(wildcard $(LOCAL_PATH)/libntfs-3g/*.c))
filter-out 的第二个参数是全集,第一个参数是要排除的模式。这样新增正常源码仍然自动收集,测试文件不会进来。如果目录里的文件命名没有统一规律,那就老老实实显式列表,编译慢一点,但可控。
静态库的源文件收集还有一个隐性边界:.c 文件里如果包含平台相关头文件,Android 的编译环境不一定和 Linux 主机一致。LOCAL_C_INCLUDES 里把 include 和 fuse/include 都写进去,是为了让库源码既能找到 ntfs-3g 自己的头文件,也能找到 FUSE 的头文件。少写一个路径,现象通常是编译时报 fuse.h: No such file or directory,而不是链接错误。
3.2 LOCAL_EXPORT_C_INCLUDES 让主程序找到 ntfs-3g.h
LOCAL_C_INCLUDES 只影响当前模块。静态库编的时候能找到 ntfs-3g.h,不代表主程序也能找到。主程序要包含 ntfs-3g.h,要么自己再写一遍 $(LOCAL_PATH)/include,要么依赖静态库的 LOCAL_EXPORT_C_INCLUDES 自动带过来。
这份 Android.mk 两边都写了:静态库导出 include,主程序也显式写 include 和 fuse/include。看起来重复,实际是双保险。导出路径写错时,主程序编译会报找不到头文件;导出路径写对但主程序又写了别的同名头文件目录,可能出现包含顺序问题。头文件搜索顺序按 LOCAL_C_INCLUDES 的书写顺序来,多个目录下有同名头文件时,排在前面的优先。
我一般会把静态库的导出路径控制到最小:只导出真正需要给外部用的 include,不导出 fuse/include。FUSE 头文件由主程序自己加,因为主程序也要写 FUSE_USE_VERSION,让两边各自管理更清楚。这样静态库的边界更干净,后面换 FUSE 版本时改动点也少。
3.3 三个编译宏决定 FUSE 与大文件行为
LOCAL_CFLAGS 里的四个宏,前三个影响行为,最后一个只压警告。
| 宏 | 作用 | 不写或写错的后果 |
|---|---|---|
-DHAVE_CONFIG_H |
让源码按配置头文件方式编译 | 源码里条件包含 config.h 的分支走不到,可能缺功能开关 |
-D_FILE_OFFSET_BITS=64 |
文件偏移按 64 位处理 | 大文件读写可能截断,NTFS 大分区上尤其明显 |
-DFUSE_USE_VERSION=26 |
固定 FUSE API 版本 | 头文件按默认版本展开,结构体布局和库不一致 |
-Wno-unused-parameter |
抑制未使用参数警告 | 只是警告变多,不影响功能,但会淹没真正的错误 |
HAVE_CONFIG_H 不是“有配置头文件”这么简单,它决定源码里 #ifdef HAVE_CONFIG_H 包住的那段配置是否生效。移植时如果 config.h 是主机上生成的,里面可能有 Android 不存在的宏,这时要么改 config.h,要么在 Android.mk 里补 -D 覆盖。不要直接把主机 config.h 原样搬过来,里面关于设备、路径、功能的宏很容易和 Android 对不上。
_FILE_OFFSET_BITS=64 在 32 位 Android 上尤其要确认。NTFS 分区里的文件可能超过 2GB,文件偏移按 32 位算会在边界处出错,现象不一定是立刻报错,可能是读到一半数据不对。这个宏在库和主程序里都要写,保证两边看到的 off_t 宽度一致。
FUSE_USE_VERSION=26 是这份源码里明确写的版本。FUSE 头文件会用这个宏做版本检查,版本太低可能缺接口,版本太高可能结构体字段对不上。库和主程序必须用同一个值,否则一个按 26 展开,一个按默认值展开,编译能过,运行时就是玄学崩溃。-Wno-unused-parameter 放在最后,作用是让编译日志干净一点,不要把它当成功能宏。
4. 代码开发工具的产物控制:ntfs3g 模块名、STEM 与依赖链接
4.1 模块名为什么不能带横线
LOCAL_MODULE 是构建系统内部索引模块的名字,不是最终文件名。Android 构建系统对模块名里的横线兼容性不好,容易在中间产物路径上翻车。表现可能是编译中途报找不到中间文件,或者两个模块的中间产物路径撞在一起,错误信息看起来和源码毫无关系。
所以主程序模块名用 ntfs3g,去掉横线。静态库模块名 libntfs-3g 里也有横线,但它是作为静态库模块名使用的,这份源码结构里能正常工作;如果换成别的构建系统版本,出现中间产物路径异常,也可以把静态库模块名改成 libntfs3g,然后同步改主程序的 LOCAL_STATIC_LIBRARIES。原则是:模块名尽量用字母数字下划线,横线留给最终输出名。
改模块名时不要只改一处。LOCAL_MODULE、LOCAL_STATIC_LIBRARIES、LOCAL_SHARED_LIBRARIES 里的依赖名要一起对。比如静态库模块名改成 libntfs3g,主程序还写 LOCAL_STATIC_LIBRARIES := libntfs-3g,链接就会报找不到模块。构建系统不会帮你猜。
4.2 LOCAL_MODULE_STEM 把输出名改回 ntfs-3g
模块名去掉横线后,最终输出文件也会变成 ntfs3g,命令行调用习惯就变了。LOCAL_MODULE_STEM := ntfs-3g 把输出文件的 stem 改回 ntfs-3g,模块名仍然是 ntfs3g。这样构建系统内部用无横线名字,设备上执行的文件名保持 ntfs-3g。
LOCAL_MODULE_STEM 只影响输出文件 stem,不影响依赖名。主程序依赖静态库时仍然写静态库的 LOCAL_MODULE,不要写成 LOCAL_STATIC_LIBRARIES := libntfs-3g.a。写 .a 文件名是另一个常见错误,构建系统认的是模块名,不是磁盘上的文件名。
编译完成后,产物路径随构建产品变化,不要背固定路径。我一般会在源码树里用 find "$OUT" -name 'ntfs-3g' -type f 确认最终文件到底落在哪。$OUT 是当前产品的输出目录,find 的结果比记忆可靠。
4.3 静态库、共享库与 LDLIBS 的摆放
依赖分三处放:静态库放 LOCAL_STATIC_LIBRARIES,共享库放 LOCAL_SHARED_LIBRARIES,额外的链接参数放 LOCAL_LDLIBS。这份 Android.mk 里,libntfs-3g 是静态库,libfuse 和 libselinux 是共享库,-llog -ldl 是额外链接参数。
-llog 对应 Android 的日志库,-ldl 对应动态加载接口。这两个放在 LOCAL_LDLIBS 里没问题,但不要把 libfuse、libselinux 也塞进来。共享库依赖写在 LOCAL_SHARED_LIBRARIES 里,构建系统会处理链接和运行时依赖;塞进 LOCAL_LDLIBS 可能编译能过,打包或运行时却缺库。
单模块编译的入口是 mm。在源码树里先加载构建环境,再选产品,然后进模块目录执行:
bash复制# 在源码树根目录加载构建环境
source build/envsetup.sh
# 选择当前设备对应的产品,按提示选编号
lunch
# 进入包含 Android.mk 的模块目录后执行单模块编译
mm
lunch 不写参数时会列出可选产品,按当前设备对应的产品编号选择。mm 编译当前目录下的模块,适合改完 Android.mk 快速验证。编译报错先看第一条错误,后面的 undefined reference 往往是第一条错误引发的连锁反应。
5. 编译与挂载的避坑排查:五个现象逐条定位
5.1 主程序报找不到 ntfs-3g.h
现象:静态库已经编过,主程序编译时仍然报 ntfs-3g.h: No such file or directory。
原因:静态库的 LOCAL_EXPORT_C_INCLUDES 没写,或者写到了 LOCAL_C_INCLUDES 里;也可能主程序自己的 LOCAL_C_INCLUDES 漏了 $(LOCAL_PATH)/include。
解决:先确认静态库模块里有 LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)/include,再确认主程序的 LOCAL_C_INCLUDES 包含 include 和 fuse/include。两边都写不冲突,导出路径负责依赖传递,主程序显式路径负责包含顺序。改完执行 mm 重新编,不要只编主程序,静态库的导出信息也要重新生成。
5.2 静态库把测试文件编进来
现象:主程序链接时报重复符号,或者报 multiple definition of main,但主程序源码里根本没有 main 冲突。
原因:LOCAL_SRC_FILES 用 wildcard 收集了 libntfs-3g/*.c,目录里的测试文件、示例程序也被编进静态库。静态库阶段不报错,链接阶段才暴露。
解决:用 filter-out 排除 %_test.c,或者改成显式源文件列表。改完先删掉中间产物再编,避免旧静态库还在。判断方法很简单:看链接报错里的符号属于哪个源文件,如果指向测试目录,就是收集范围问题。
5.3 模块名带横线导致中间产物路径异常
现象:编译中途报找不到某个中间文件,路径里带着模块名,但磁盘上确实没有生成;或者两个模块的中间产物互相覆盖。
原因:LOCAL_MODULE 里用了横线,构建系统在中间产物路径处理上兼容性不好。错误信息通常不会直接说“模块名不合法”,所以容易误判成源码问题。
解决:主程序模块名改成 ntfs3g,用 LOCAL_MODULE_STEM := ntfs-3g 保住输出文件名。静态库如果也遇到类似问题,把 libntfs-3g 改成 libntfs3g,同步改主程序的 LOCAL_STATIC_LIBRARIES。改完清掉中间产物再全编一次。
5.4 运行时报 libfuse/libselinux 符号缺失
现象:编译和链接都通过,设备上执行 ntfs-3g 时报 library "libfuse.so" not found 或 undefined symbol 一类错误。
原因:LOCAL_SHARED_LIBRARIES 漏写 libfuse、libselinux,或者只写了静态库依赖。另一种情况是设备系统里没有对应共享库,编译链接的是主机或源码树里的库。
解决:确认主程序模块里有 LOCAL_SHARED_LIBRARIES := libfuse libselinux,不要把它们塞进 LOCAL_LDLIBS。再到设备上确认共享库是否存在,用 readelf -d 看可执行文件的 NEEDED 项。如果设备缺库,要么把库一起编进系统镜像,要么改成静态链接,但静态链接 FUSE 会引入另一套依赖问题,需要单独评估。
5.5 编译通过但挂载被 SELinux 拒绝
现象:ntfs-3g 已经跑到设备上,执行挂载命令返回 Permission denied 或 mount failed,dmesg 里能看到 avc: denied 记录。
原因:SELinux 策略没有放行这个可执行文件或挂载点。编译产物存在不代表运行域有权限,Android 的 SELinux 对可执行文件标签、挂载点上下文都有约束。
解决:先在设备上执行 adb shell getenforce 确认是不是 Enforcing。是的话看 adb shell dmesg | grep avc 里的拒绝项,确认是文件标签、挂载点上下文还是域转换问题。我一般会先用 Permissive 跑一遍,确认挂载本身没问题,再回到 Enforcing 补策略。Permissive 只用于定位,不要长期留在设备上。补策略时只放行实际需要的操作,不要图省事把整个域放开。
6. 从产物到可运行:一次完整的验证习惯
6.1 先验产物名和 NEEDED,再上设备
改完 Android.mk,我习惯先不急着推设备,而是在源码树里做两步检查:产物名对不对、运行时依赖有没有缺。产物名检查能发现 LOCAL_MODULE_STEM 没生效;NEEDED 检查能发现共享库漏链。两步都过了,再上设备挂载,能少很多来回。
bash复制# 先定位产物,不同产品的输出目录可能不同
NTFS3G_BIN=$(find "$OUT" -name 'ntfs-3g' -type f | head -n 1)
echo "$NTFS3G_BIN"
# 查看可执行文件依赖的共享库
readelf -d "$NTFS3G_BIN" | grep NEEDED
# 设备上确认 SELinux 状态,挂载失败时先看这个
adb shell getenforce
adb shell dmesg | grep avc
find 的结果比固定路径可靠,head -n 1 只取第一个匹配项,避免多个产品目录同时存在时拿错。readelf -d 看的是动态依赖,NEEDED 里没有 libfuse 或 libselinux,说明 LOCAL_SHARED_LIBRARIES 没写对。getenforce 和 dmesg 是挂载失败时的黑匣子,先看状态再改策略,不要一上来就猜权限。
6.2 挂载前把 SELinux 状态留成黑匣子
我还会在挂载前把 getenforce 的输出和 dmesg 里最近的 avc 记录存一份。挂载失败时,这份记录能直接区分是“库没链上”还是“策略没放行”。库没链上,错误通常在 readelf 阶段就能看到;策略没放行,编译和链接都正常,只有运行时的 avc 日志会说话。
从那以后我每次改 Android.mk 都先跑一遍产物名和 NEEDED 检查,再上设备挂载,省得在 avc 日志里翻半天。希望帮到你。
