1. 功能库落进 Android 工程:先定 libredwg 的交付形态
在 Android 上读 DWG,绕不开一个用 C 写的功能库,libredwg 就是这条路里常见的一个。交叉编译这一段很多人能跑通:NDK 装好,工具链文件一配,几个 .so 出得来。真正翻车的位置在后面——工程里的 CMake 找不到它,或者编译期找到了、装进手机一跑就崩。这篇写的是 libredwg 从交叉编译产物到 Android 工程 JNI 集成这一整段,重心不在怎么编,而在编出来的东西怎么被 CMake 稳定接进去、怎么让多个 ABI 一次配置全都能用。适合已经能产出 so、但还在为路径和 ABI 反复改 CMakeLists 的人。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 交叉编译产物的落位:jniLibs 目录、ABI 与路径推导
2.1 一个 ABI 一个目录,文件名必须带 lib 前缀
先把产物放对地方,后面 CMake 才有东西可找。Android 的动态库按 CPU 架构分目录,同一个 libredwg.so 在 arm64-v8a 和 armeabi-v7a 下是两份不同的二进制,不能混放,也不能只放一份指望它通吃。
bash复制app/
└── src/
└── main/
├── cpp/
│ ├── CMakeLists.txt
│ └── dwg_jni.c
└── jniLibs/
├── arm64-v8a/
│ └── libredwg.so
├── armeabi-v7a/
│ └── libredwg.so
├── x86/
│ └── libredwg.so
└── x86_64/
└── libredwg.so
这个结构有两个硬约束。第一,目录名必须是 Android 认的 ABI 名,arm64-v8a 不能写成 arm64,否则 CMake 里 ${ANDROID_ABI} 拼出来的路径和实际目录对不上,配置阶段直接报找不到文件。第二,文件名必须是 libredwg.so,前缀 lib 不能省。CMake 里 add_library(redwg SHARED IMPORTED) 的目标名是 redwg,链接时按 -lredwg 去解析,最终写进 libdwg_jni.so 的 DT_NEEDED 记录是 libredwg.so;如果交叉编译脚本产出的文件叫 redwg.so,构建期可能凑合过去,运行期动态链接器按这个名字找不到,报的就是 dlopen failed: library "libredwg.so" not found。
jniLibs 放在 app/src/main/ 下不是随便选的。这是 AGP 默认识别的原生库源集目录,放在这里的 so 会被打进 APK 的 lib/<abi>/ 下。放在工程根目录或者 app/libs/ 下,CMake 通过 IMPORTED_LOCATION 照样能找到并完成链接,但打包时不会带上,结果就是编译全绿、安装即崩。这个差异是后面排查章节里最常见的一条。
2.2 用 CMAKE_SOURCE_DIR 反推路径,不要写死绝对路径
材料里的配置用了 ${CMAKE_SOURCE_DIR}/../jniLibs/${ANDROID_ABI}/libredwg.so。这个写法的前提是 CMakeLists.txt 位于 app/src/main/cpp/,往上退一层正好是 app/src/main/jniLibs/,和 2.1 的目录结构严丝合缝。换个位置,比如把 CMakeLists 提到 app/ 下,这条相对路径就指向 app/../jniLibs,整个错位。
CMAKE_SOURCE_DIR 和 CMAKE_CURRENT_SOURCE_DIR 容易混。前者是顶层 CMakeLists 所在目录,后者是当前处理的 CMakeLists 所在目录。工程里只有一份 CMakeLists 时两者相同;一旦用 add_subdirectory 拆了子目录,CMAKE_SOURCE_DIR 仍然指向顶层,用哪个取决于你的目录规划。我的习惯是:路径推导统一用 CMAKE_CURRENT_SOURCE_DIR,因为原生代码目录以后大概率会被拆。
配置阶段加一行打印,比事后猜路径省事得多:
cmake复制message(STATUS "redwg so path = ${CMAKE_CURRENT_SOURCE_DIR}/../jniLibs/${ANDROID_ABI}/libredwg.so")
这行输出会出现在 Gradle 的 C++ 配置日志里。构建失败时先看它打印的路径,再去文件管理器里对照是否存在,能省掉大量「明明放了文件」的争论。参数上唯一要改的是中间那段相对路径,其余部分不要动,尤其不要把 ${ANDROID_ABI} 换成某个固定值——换掉之后多 ABI 构建时所有变体都会去读同一份 so,32 位设备拿到 64 位库,问题会推迟到运行期才暴露。
2.3 ABI 集合要和产物数量对齐
只编你真正要发的 ABI,是控制包体和排查成本最直接的手段。四个常见目录的对应关系如下:
| ABI 目录名 | 位数 | 说明 |
|---|---|---|
arm64-v8a |
64 位 | 目前主流真机,优先级最高 |
armeabi-v7a |
32 位 | 老设备兼容,按需保留 |
x86 |
32 位 | 模拟器调试用,发布包通常不带 |
x86_64 |
64 位 | 模拟器调试用,发布包通常不带 |
jniLibs 下有几个目录,abiFilters 里就应该有同样的几个,两边差一个都会在某个变体上出问题。常见做法是在模块的 build.gradle 里显式收口:
groovy复制android {
defaultConfig {
ndk {
// 只保留实际要发布的 ABI,与 jniLibs 下的目录一一对应
abiFilters 'arm64-v8a', 'armeabi-v7a'
}
}
}
这段配置的作用是告诉打包流程只产出这两个 ABI 的变体。如果 jniLibs 下还留着 x86_64 的 so 而过滤器里没写,那份 so 就是死重量;反过来过滤器开了 x86_64 但目录里没有,构建会在这个变体上因为找不到 libredwg.so 而失败。两边对齐之后,CMake 里的 ${ANDROID_ABI} 才有意义——它在每个变体构建时取当前 ABI 名,自动指向对应目录,这就是「配置一次处理多个 ABI」的实际含义,不是什么自动探测机制。
3. CMakeLists.txt 逐行拆:把功能库接进 JNI 桥接层
3.1 完整配置与 IMPORTED 目标的语义
cmake复制cmake_minimum_required(VERSION 3.18.1)
project("dwgreader")
# 导入交叉编译好的 libredwg.so
add_library(redwg SHARED IMPORTED)
set_target_properties(redwg PROPERTIES
IMPORTED_LOCATION ${CMAKE_SOURCE_DIR}/../jniLibs/${ANDROID_ABI}/libredwg.so
)
# 编译JNI桥接层
add_library(dwg_jni SHARED
src/main/cpp/dwg_jni.c
)
# 链接Libredwg动态库和Android内置的log库
target_link_libraries(dwg_jni
redwg
log
)
find_library(log-lib log)
target_link_libraries(dwg_jni ${log-lib})
add_library(redwg SHARED IMPORTED) 里的 IMPORTED 是关键。它告诉 CMake:这个目标已经存在于磁盘上,不要尝试编译它,只把它当成一个可链接对象登记进来。所以这条语句后面没有源文件列表,也不需要。SHARED 表示它是动态库;如果交叉编译产出的是静态库,这里要改成 STATIC,同时 IMPORTED_LOCATION 指向 .a 文件,链接行为会完全不同。
set_target_properties 只设了一个属性:IMPORTED_LOCATION。这是 IMPORTED 目标的最低要求,缺了它 CMake 在生成构建文件时会直接报错,提示目标没有指定位置。注意这个属性必须指向具体文件,不能指向目录,也不能写成 ${ANDROID_ABI} 之外的变量——用别的变量名,构建时不会自动展开成当前 ABI。
3.2 JNI 桥接层作为独立目标
add_library(dwg_jni SHARED src/main/cpp/dwg_jni.c) 这一段编的是我们自己的桥接层,产出 libdwg_jni.so。源文件路径写的是 src/main/cpp/dwg_jni.c,这是相对于 CMAKE_SOURCE_DIR 的路径。这里有个容易忽略的边界:如果 CMakeLists.txt 本身就在 app/src/main/cpp/ 下,那么再写 src/main/cpp/... 就会拼成 app/src/main/cpp/src/main/cpp/dwg_jni.c,文件不存在,配置阶段报源文件缺失。
两种写法选一种并保持一致:要么 CMakeLists 放在 app/ 下、源文件用 src/main/cpp/dwg_jni.c;要么 CMakeLists 放在 app/src/main/cpp/ 下、源文件只写 dwg_jni.c。材料里的配置把 IMPORTED_LOCATION 写成 ${CMAKE_SOURCE_DIR}/../jniLibs/...,这个「退一层」的写法说明它假设 CMakeLists 在 cpp 目录下;但源文件又写了完整相对路径,两者其实互相矛盾。实际落地时按你的真实目录改其中一处,不要两处都照抄。
SHARED 不能省。JNI 桥接层要被 System.loadLibrary 加载,必须是动态库;写成默认的静态库,产出的 .a 不会进 APK,Java 侧调用时找不到符号。
3.3 链接关系:redwg、log 与那行重复的 find_library
target_link_libraries(dwg_jni redwg log) 建立了依赖:链接 libdwg_jni.so 时把 libredwg.so 和系统的 liblog.so 一起解析。链接 redwg 之后,libdwg_jni.so 的动态段里会记一条 NEEDED libredwg.so,运行期由动态链接器负责加载,桥接层代码里不需要手动 dlopen。
后面三行 find_library(log-lib log) 加 target_link_libraries(dwg_jni ${log-lib}) 和前面的 log 是同一件事。find_library 在 NDK 工具链的 sysroot 里搜 liblog.so,把绝对路径赋给 log-lib 变量,再链一次。功能上没有问题,链接器对重复的同一个库会去重;但它会让后来读配置的人以为工程里有两个日志库,也让配置多了一次文件搜索。留一种就行,我一般直接留 log 这一种,短且明确。
find_library 还有一个边界:它依赖 NDK 工具链提供的搜索路径。如果同一份 CMakeLists 被宿主机构建(比如某些单元测试或本地调试)复用,find_library(log-lib log) 会返回 log-lib-NOTFOUND,随后链接报错。真要把配置复用到非 Android 场景,用 if(ANDROID) 把这几行包起来,比事后改报错省事。
3.4 配置通过不等于运行成功
这三段配置跑通,只说明构建期能找到文件、链接器能解析符号。构建期检查的是源码树里的路径 ${CMAKE_SOURCE_DIR}/../jniLibs/${ANDROID_ABI}/libredwg.so;运行期动态链接器找的是 APK 内部的 lib/<abi>/libredwg.so。这是两套完全不同的路径,前者存在不代表后者存在。2.1 里提到的「so 放在工程根目录」就是这个断层的典型:CMake 阶段一切正常,APK 里却少一个文件。
配置在 Android Studio 2022.3+ 和 AGP 7.4+ 环境下实测通过,cmake_minimum_required(VERSION 3.18.1) 与这个组合匹配。低于这个下限的 CMake 版本对 IMPORTED 目标的处理有差异,不建议往下调。
4. 功能库的加载边界:so 名字、DT_NEEDED 与 JNI 符号
4.1 loadLibrary 的顺序与库名映射
java复制public class DwgReader {
static {
// 对应 libdwg_jni.so,参数不带 lib 前缀和 .so 后缀
System.loadLibrary("dwg_jni");
}
public static native long nativeOpen(String path);
public static native void nativeClose(long handle);
}
loadLibrary 的参数是库名去掉 lib 前缀和 .so 后缀之后的部分,dwg_jni 对应 libdwg_jni.so。加载 libdwg_jni.so 时,动态链接器读到它动态段里的 NEEDED libredwg.so,会在同一个 lib/<abi>/ 目录下继续找 libredwg.so。这意味着不需要、也不应该再写一行 System.loadLibrary("redwg"):手动加载一遍不会出错,但顺序和路径都得自己保证,反而多一个失败点。让依赖关系交给链接器处理,是更稳的做法。
如果 libredwg.so 没进 APK,崩溃点会出现在 loadLibrary("dwg_jni") 这一行,报的是 libredwg.so 找不到,而不是 dwg_jni 找不到。看日志时别被第一行误导,报哪个名字缺的就是哪个文件。
4.2 JNI 符号名对不上,加载成功也调不到
c复制#include <jni.h>
#include <android/log.h>
#define LOG_TAG "dwg_jni"
#define LOGI(...) __android_log_print(ANDROID_LOG_INFO, LOG_TAG, __VA_ARGS__)
JNIEXPORT jlong JNICALL
Java_xxx_DwgReader_nativeOpen(JNIEnv *env, jclass clazz, jstring path)
{
const char *cpath = (*env)->GetStringUTFChars(env, path, NULL);
if (cpath == NULL) {
return 0;
}
long handle = 0;
/* 这里调用 libredwg 的打开接口,拿到解析句柄 */
(*env)->ReleaseStringUTFChars(env, path, cpath);
return (jlong)handle;
}
函数名不是随便起的。规则是 Java_ 加包名(点换成下划线)、下划线、类名、下划线、方法名;包名或类名本身含下划线时,下划线要转义成 _1。上面的 Java_xxx_DwgReader_nativeOpen 里 xxx 要换成真实包名路径。改包名、改类名之后忘了同步这个函数名,loadLibrary 会成功,调用时抛 No implementation found for long ...nativeOpen,现象和库没加载上很像,但原因完全不同。
文件是 .c 时不需要 extern "C";如果桥接层改写成 .cpp,必须给函数加 extern "C",否则 C++ 编译器会做名字修饰,导出的符号和 Java 侧期望的完全对不上。这个坑在把桥接层从 C 迁到 C++ 时几乎必踩一次。
4.3 句柄生命周期与线程边界
nativeOpen 返回的句柄是一个 native 侧的资源标识,在 nativeClose 之前有效。Java 侧要保证成对调用,别指望 GC 帮你回收——native 内存和文件句柄不受 Java 堆管理,对象被回收了 native 资源照样泄漏。我一般把句柄包在一个带 close() 的类里,显式释放。
线程上有一条硬边界:JNIEnv 是线程相关的,不能在 A 线程拿到的 env 去 B 线程用。大文件解析要放工作线程时,线程入口里用 AttachCurrentThread 拿自己的 env,退出前 DetachCurrentThread。解析本身也不要放主线程,DWG 文件动辄几十兆,主线程阻塞几秒就会被系统判成无响应。
5. 集成环节的避坑与排查:五类现象对应五个断点
5.1 配置期报 IMPORTED_LOCATION 不存在
现象:Gradle 同步或构建时 C++ 配置失败,报 Imported target "redwg" includes non-existent path ".../jniLibs/arm64-v8a/libredwg.so"。
原因通常有三种:交叉编译只出了 armeabi-v7a 一份,arm64-v8a 目录是空的;目录层级多套了一层,实际路径是 jniLibs/arm64-v8a/arm64-v8a/libredwg.so;产物文件名是 redwg.so,少了 lib 前缀。这三种在报错信息里都表现为「文件不存在」,但改法完全不同。
解决:先按 2.2 加那行 message,把 CMake 实际拼出来的路径打出来,再拿这个路径去文件管理器逐段核对。文件名不对就改文件名,目录多一层就挪文件,ABI 缺一份就补交叉编译。不要用改 IMPORTED_LOCATION 指向另一份 so 的方式绕过——那等于把 ABI 不匹配的问题推迟到运行期。
5.2 构建全绿,安装后 dlopen 找不到 libredwg.so
现象:java.lang.UnsatisfiedLinkError: dlopen failed: library "libredwg.so" not found,崩溃点在 System.loadLibrary("dwg_jni")。
原因是构建期和运行期看的不是同一份文件系统。so 放在了工程根目录的 jniLibs/ 或者 app/libs/ 下,CMake 的 IMPORTED_LOCATION 能指过去,链接正常;但 AGP 只把 app/src/main/jniLibs/<abi>/ 下的 so 打进 APK,APK 里根本没有这个文件。
解决:把 so 挪到 app/src/main/jniLibs/<abi>/。确实要放别的目录,就得在 build.gradle 里用 sourceSets 的 jniLibs.srcDirs 显式声明,让打包流程知道去哪收。改完用第 6 章的解包命令确认一遍,别只看构建日志。
5.3 32 位库跑在 64 位设备上
现象:UnsatisfiedLinkError: dlopen failed: ".../libredwg.so" is 32-bit instead of 64-bit,或者反过来提示 64 位库跑在 32 位进程里。
原因:abiFilters 里开了 arm64-v8a,但 jniLibs/arm64-v8a/ 下放的是从 armeabi-v7a 拷过来的 so;或者 APK 里某个 ABI 目录只有桥接层没有 libredwg.so,系统按 ABI 优先级挑了那个目录。后一种更隐蔽,因为崩溃信息只提位数不匹配,不提文件缺失。
解决:用 file 命令逐个检查 so 的架构,确认每个 ABI 目录里的 libredwg.so 和 libdwg_jni.so 位数一致,并且成对存在。ABI 目录、abiFilters、交叉编译脚本三处的 ABI 清单要完全一致,差一个都会在某个设备上炸。
5.4 库加载成功,方法调用报 No implementation found
现象:loadLibrary 没报错,第一次调 nativeOpen 抛 UnsatisfiedLinkError: No implementation found for long com.xxx.DwgReader.nativeOpen(java.lang.String)。
原因:JNI 函数名和 Java 侧的包名、类名、方法名对不上,最常见的是重构时改了包名或类名,C 文件里的 Java_ 前缀没跟着改;其次是 dwg_jni.c 没被加进 add_library(dwg_jni SHARED ...) 的源文件列表,编出来的 so 里压根没有这个符号。
解决:先用 javap -s 看 Java 侧方法的真实签名,再按 Java_包名_类名_方法名 逐段比对 C 文件里的函数名,注意下划线转义 _1。符号缺失用 nm -D libdwg_jni.so | grep nativeOpen 确认,没有输出就回头查源文件列表。
5.5 log 库的链接在非 Android 构建下失败
现象:同一份 CMakeLists 在宿主机构建时报 Could NOT find log 或链接阶段找不到 -llog。
原因:find_library(log-lib log) 的搜索路径来自 NDK 工具链的 sysroot,离开 Android 工具链就没有 liblog.so,变量变成 log-lib-NOTFOUND,随后 target_link_libraries 把它当成一个不存在的库去解析。
解决:要么直接删掉 find_library 那两行、只保留 target_link_libraries 里的 log(Android 构建下 NDK 会自动解析),要么用 if(ANDROID) 把这几行包起来,非 Android 分支走另一套链接。这个坑不影响 APK 构建,但会让本地调试和单元测试莫名其妙失败。
6. 多 ABI 交付前的验证:三条命令和一个固定习惯
6.1 打包之后先解包看目录
构建产物不能只看 Gradle 的绿色提示,得看 APK 里到底装了什么:
bash复制unzip -l app/build/outputs/apk/debug/app-debug.apk | grep "lib/"
期望输出里 lib/arm64-v8a/libdwg_jni.so 和 lib/arm64-v8a/libredwg.so 成对出现,每个开启的 ABI 目录下都是这两份。只看到 libdwg_jni.so 而看不到 libredwg.so,就是 5.2 那条,装到设备必崩。这一步比任何构建日志都直接。
再看桥接层有没有正确记录依赖:
bash复制readelf -d libdwg_jni.so | grep NEEDED
期望里有 libredwg.so。没有这一条,说明 target_link_libraries 里的 redwg 没生效,或者链接的是一个静态库版本,运行期不会自动加载 libredwg.so。
最后核对架构:
bash复制file app/src/main/jniLibs/arm64-v8a/libredwg.so
期望是 ELF 64-bit LSB shared object, ARM aarch64。输出里出现 32-bit 就说明这个目录里放错了文件。
6.2 三处清单对齐,打包前跑一遍
| 检查项 | 命令或位置 | 期望结果 |
|---|---|---|
| jniLibs 目录 | ls app/src/main/jniLibs/ |
与 abiFilters 完全一致 |
| 每个 ABI 的 so | ls app/src/main/jniLibs/*/libredwg.so |
每个目录各一份 |
| APK 内库文件 | unzip -l ... | grep lib/ |
每个 ABI 两份 so 成对 |
我习惯在打包脚本开头塞一段比对,缺文件就直接退出,不让它编到一半才炸:
bash复制for abi in arm64-v8a armeabi-v7a; do
if [ ! -f "app/src/main/jniLibs/$abi/libredwg.so" ]; then
echo "missing libredwg.so for $abi"
exit 1
fi
done
这段脚本里的 ABI 列表要跟 abiFilters 手抄一致,别用通配符自动收集——自动收集会把误放的临时目录也算进去,等于把 5.1 的坑埋回去。
血泪经验是:这套集成真正花时间的不是写 CMakeLists,而是让「交叉编译脚本产出的 ABI」「jniLibs 下的目录」「abiFilters 里的清单」「APK 里实际打进去的文件」这四份清单始终保持一致。任何一处改动没同步,问题都会以「找不到库」「位数不对」「方法没实现」这三种完全不同的面貌出现,排查时很容易往错误方向走。从那以后我每次改 CMakeLists 或者换交叉编译脚本,都先把这三条命令跑一遍再装设备,再没在这类问题上浪费过半天。希望帮到你。
