Android.mk 语法详细总结

Android.mk 是 Android NDK 构建系统基于 GNU Make 封装的原生代码构建脚本，用于描述 C/C++ 源码、库、可执行文件的编译规则，是 NDK 开发中 native 代码构建的核心配置文件，本质是 Makefile 语法的子集，与 Android 平台源码构建语法高度兼容。

一、基础核心结构（必写模板）

一个合法的 Android.mk 必须遵循固定的结构范式，每个模块的定义都需遵循该流程，最小可运行模板如下：

# 1. 必须放在文件最开头：定义当前mk文件所在目录，my-dir是NDK内置函数
LOCAL_PATH := $(call my-dir)

# 2. 清空LOCAL_系列变量（仅保留LOCAL_PATH），每个新模块定义前必须调用
include $(CLEAR_VARS)

# 3. 模块核心属性定义（模块名、源码、编译选项等）
LOCAL_MODULE := hello_jni  # 模块名，全局唯一
LOCAL_SRC_FILES := hello_jni.c  # 待编译的源码文件，路径相对LOCAL_PATH

# 4. 指定构建目标类型，收尾模块定义
include $(BUILD_SHARED_LIBRARY)

核心规则：一个 Android.mk 可定义多个模块，每个新模块前必须重新执行 include $(CLEAR_VARS)，LOCAL_PATH 仅需在文件开头定义一次。

二、系统预定义核心变量

NDK 构建系统提前定义好的全局变量，无需用户赋值，直接引用即可，分为构建目标、平台架构两大类。

1. 构建目标类型变量

2. 目标平台与架构变量

用于差异化适配不同CPU架构、Android系统版本，常用于条件编译。

三、模块定义核心 LOCAL_* 变量

这是 Android.mk 最核心的部分，用于描述单个模块的编译规则，所有变量均以 LOCAL_ 开头，必须在 include $(CLEAR_VARS) 之后、include $(BUILD_XXX) 之前定义。

1. 模块基础标识变量

2. 源码与头文件相关变量

3. 编译选项相关变量

4. 链接与依赖相关变量

5. 预编译库专属变量

用于引入第三方已编译好的 .so/.a 文件，无需重新编译源码，核心配置如下：

6. 其他常用变量

四、NDK 内置常用函数

所有函数均通过 $(call 函数名, 参数) 格式调用，核心高频函数如下：

1. my-dir 无参数，返回当前 Android.mk 文件所在的目录路径，每个mk文件开头必须调用，用于定义 LOCAL_PATH。 示例：LOCAL_PATH := $(call my-dir)

2. all-subdir-makefiles 无参数，返回当前目录下所有子目录中的 Android.mk 文件路径，用于递归包含子目录的构建脚本。 示例：include $(call all-subdir-makefiles)

3. all-makefiles-under 参数为指定目录路径，返回该目录下所有子目录中的 Android.mk 文件路径，比 all-subdir-makefiles 更灵活。 示例：include $(call all-makefiles-under, $(LOCAL_PATH)/modules)

4. this-makefile 无参数，返回当前正在执行的 Makefile 的完整路径。

5. parent-makefile 无参数，返回包含当前 Makefile 的父 Makefile 路径。

6. grand-parent-makefile 无参数，返回包含当前 Makefile 的祖父级 Makefile 路径。

7. import-module 参数为模块的相对路径，用于导入外部模块，根据 NDK_MODULE_PATH 环境变量搜索模块目录，常用于引入第三方NDK模块。 示例：$(call import-module, thirdparty/ffmpeg)

五、条件控制语法

Android.mk 完全兼容 GNU Make 的条件判断语法，用于实现按架构、平台、编译模式等场景的差异化编译，核心语法如下。

1. 相等/不等判断：ifeq / ifneq

# 按CPU架构区分源码
ifeq ($(TARGET_ARCH), arm64)
    LOCAL_SRC_FILES += arm64_utils.c
else ifeq ($(TARGET_ARCH), x86_64)
    LOCAL_SRC_FILES += x64_utils.c
else
    LOCAL_SRC_FILES += default_utils.c
endif

# 按编译模式配置优化选项
ifeq ($(APP_OPTIM), debug)
    LOCAL_CFLAGS += -O0 -g -DDEBUG_MODE
else
    LOCAL_CFLAGS += -O2 -DNDEBUG
endif

2. 变量定义判断：ifdef / ifndef

# 若定义了ENABLE_LOG宏，则开启日志功能
ifdef ENABLE_LOG
    LOCAL_CFLAGS += -DENABLE_LOG
    LOCAL_LDLIBS += -llog
endif

# 若未定义DISABLE_SECURITY，则开启安全编译选项
ifndef DISABLE_SECURITY
    LOCAL_CFLAGS += -fstack-protector-strong
endif

六、典型场景完整示例

示例1：基础JNI共享库（最常用）

LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)

# 模块基础信息
LOCAL_MODULE := hello_jni
LOCAL_SRC_FILES := hello_jni.c
# 头文件路径
LOCAL_C_INCLUDES := $(LOCAL_PATH)/include
# 链接Android日志库
LOCAL_LDLIBS := -llog
# 开启C++17标准
LOCAL_CPPFLAGS := -std=c++17
# 开启所有编译警告
LOCAL_CFLAGS := -Wall

include $(BUILD_SHARED_LIBRARY)

示例2：静态库+依赖静态库的共享库

LOCAL_PATH := $(call my-dir)

# 1. 编译工具静态库
include $(CLEAR_VARS)
LOCAL_MODULE := utils
LOCAL_SRC_FILES := utils/string.c utils/math.c
LOCAL_C_INCLUDES := $(LOCAL_PATH)/utils
# 导出头文件，依赖模块自动继承
LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)/utils
include $(BUILD_STATIC_LIBRARY)

# 2. 编译主共享库，依赖上述静态库
include $(CLEAR_VARS)
LOCAL_MODULE := main_lib
LOCAL_SRC_FILES := main.c
# 依赖静态库
LOCAL_STATIC_LIBRARIES := utils
LOCAL_LDLIBS := -llog
include $(BUILD_SHARED_LIBRARY)

示例3：引入第三方预编译共享库

LOCAL_PATH := $(call my-dir)

# 引入预编译的FFmpeg库
include $(CLEAR_VARS)
LOCAL_MODULE := ffmpeg
LOCAL_SRC_FILES := libs/$(TARGET_ARCH_ABI)/libffmpeg.so
# 导出头文件路径
LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)/ffmpeg/include
include $(PREBUILT_SHARED_LIBRARY)

# 主库依赖FFmpeg
include $(CLEAR_VARS)
LOCAL_MODULE := video_player
LOCAL_SRC_FILES := player.c decoder.c
# 依赖预编译的FFmpeg库
LOCAL_SHARED_LIBRARIES := ffmpeg
LOCAL_LDLIBS := -llog -landroid -lGLESv2
include $(BUILD_SHARED_LIBRARY)

示例4：编译原生可执行文件

LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)

LOCAL_MODULE := test_shell
LOCAL_SRC_FILES := test.c
# 静态链接，减少运行时依赖
LOCAL_FORCE_STATIC_EXECUTABLE := true
LOCAL_STATIC_LIBRARIES := utils
include $(BUILD_EXECUTABLE)

七、最佳实践与高级用法

1. 模块化导出配置 库模块必须通过 LOCAL_EXPORT_C_INCLUDES 导出对外头文件，通过 LOCAL_EXPORT_LDLIBS/LOCAL_EXPORT_CFLAGS 导出依赖的系统库和编译选项，避免依赖模块重复配置，减少出错。

2. 单文件多模块规范 一个 Android.mk 中可定义多个模块，每个模块前必须执行 include $(CLEAR_VARS)，LOCAL_PATH 仅需在开头定义一次，禁止多个模块共用一个 CLEAR_VARS 作用域。

3. ABI差异化适配 针对不同架构使用专属源码/库，通过 TARGET_ARCH_ABI 条件判断实现，避免无效代码编译，减小包体积。

4. 递归包含子目录 项目源码分多目录时，在根目录 Android.mk 末尾添加 include $(call all-subdir-makefiles)，自动包含所有子目录的mk文件，无需手动逐个引入。

5. 调试与发布分离 通过 APP_OPTIM 区分debug和release模式，debug模式关闭优化、保留调试信息，release模式开启优化、strip符号，减小体积。

八、常见坑与避坑指南

1. 变量污染：每个新模块前必须加 include $(CLEAR_VARS)，否则前一个模块的变量会污染后一个模块，导致诡异的编译错误。
2. LOCAL_PATH 位置错误：必须在 Android.mk 最开头定义 LOCAL_PATH，且仅定义一次，避免被 CLEAR_VARS 清空。
3. 依赖库链接错误：LOCAL_LDLIBS 只能链接系统库，自定义模块必须用 LOCAL_SHARED_LIBRARIES/LOCAL_STATIC_LIBRARIES，否则会报符号找不到。
4. 静态库符号丢失：静态库嵌套依赖、需要导出全部符号时，必须用 LOCAL_WHOLE_STATIC_LIBRARIES，否则未被直接引用的符号会被链接器丢弃，运行时崩溃。
5. 头文件路径错误：对外头文件必须用 LOCAL_EXPORT_C_INCLUDES 导出，否则依赖模块需要手动添加头文件路径，否则会报头文件找不到。
6. 模块名重复：模块名必须全局唯一，否则后定义的模块会覆盖先定义的，导致编译异常。
7. 路径格式错误：LOCAL_SRC_FILES 必须使用Unix风格正斜杠 /，Windows反斜杠 \ 会导致构建系统无法识别路径。

九、与 Application.mk 的配合

Android.mk 是模块级构建配置，描述单个模块的编译规则；Application.mk 是项目级全局配置，作用于当前项目所有模块，二者配合完成NDK构建，Application.mk 核心常用配置如下：

补充说明：Android.mk 是传统NDK构建系统，目前Google推荐新工程使用 CMake 构建，但Android.mk 在大量存量项目、系统级native开发中仍广泛使用，是Android NDK开发的必备基础。