ICU4C 链接报错与数据加载排查:版本后缀、SONAME 与 libicudt
结论先给:三类「像是没装 ICU」的报错成因不同。undefined reference 多是头文件与 .so 不同源(renaming 状态或版本后缀不一致),或漏链 icu-i18n;cannot open shared object file 是 SONAME 随大版本跳变导致加载期找不到;U_MISSING_RESOURCE_ERROR 是数据没被加载,而不是数据文件不存在。
项目信息
- 仓库:https://github.com/unicode-org/icu (
icu4c/子目录) - 文档:https://unicode-org.github.io/icu/
- 官网:https://icu.unicode.org/
ICU4C 是 International Components for Unicode 的 C/C++ 侧,与 Java 侧的 ICU4J 是姊妹项目,需要区分时写 ICU4C。至少需要 data(libicudt)与 common(libicuuc)两个库。
现象
三种报错看起来都像「没装 ICU」:
undefined reference to icu_79::UnicodeString::...或undefined reference to ucnv_open_79libicui18n.so.79: cannot open shared object file- 程序跑起来了,取 locale 数据返回
U_MISSING_RESOURCE_ERROR(UErrorCode = 2)
第一步:分清是符号名不对,还是库根本没找到
nm -D /usr/lib/x86_64-linux-gnu/libicuuc.so | grep ucnv_open
# 输出 ucnv_open_79,带版本后缀
readelf -d /usr/lib/.../libicui18n.so.79 | grep SONAME
# 输出 libicui18n.so.79
- 自带的
icuinfo会打印 ICU version、DataVersion、config(含 renaming 是否开启),比icu-config --version更直接。 uconv -V输出形如uconv v2.1 ICU 79.1。
命名空间与符号重命名(renaming)
- ICU 61 起头文件不再默认把 ICU 类型放进全局作用域,要写
icu::UnicodeString或using icu::UnicodeString;。依赖旧的隐式 using 会报找不到符号,临时兼容可用-DU_USING_ICU_NAMESPACE=1。 - C++ 实际命名空间是带版本的
icu_79,icu只是稳定别名。要写前向声明用U_NAMESPACE_BEGIN/U_NAMESPACE_END。 - C API 走的是 entry point 重命名:符号名追加
_79。如果发行版用--disable-renaming编译,符号就是ucnv_open,命名空间也是icu。头文件和.so必须同源同版本,混用系统里另一份 ICU 头文件就会报 undefined reference。
pkg-config 取代 icu-config
icu-config自 ICU 63.1 起弃用(ICU-10464),可能被默认关闭;configure 有--enable-icu-config/--disable-icu-config。- 推荐 pkg-config,包名:
icu-uc(common+data)、icu-i18n(国际化)、icu-lx(ParagraphLayout)、icu-io(ustdio)。
c++ -o test test.cpp $(pkg-config --libs --cflags icu-uc icu-io)
.pc文件装在$(prefix)/lib/pkgconfig,自定前缀时要export PKG_CONFIG_PATH=$(prefix)/lib/pkgconfig。- 常见坑:只链
icu-uc却在用icu::Collator/icu::DateFormat,这两个在icu-i18n,报的就是 undefined reference。 - 自己搭构建系统时,各库要分别定义
-DU_COMMON_IMPLEMENTATION/-DU_I18N_IMPLEMENTATION,单库合并加-DU_COMBINED_IMPLEMENTATION,静态库加-DU_STATIC_IMPLEMENTATION;不开这些会撞到符号可见性问题。 - ICU4C 现在要求 C11 与 C++17,老工具链报一堆语法错时先看这条。
- 源码构建顺序:
runConfigureICU Linux/gcc
gmake
非 GNU make 环境按配置结尾提示用 gmake。
数据加载:U_MISSING_RESOURCE_ERROR 不是文件缺失那么简单
- 数据是独立一份的:
libicudt。ICU 服务对象打开时(ucnv_open/ucol_open/ C++ 构造函数)都会给UErrorCode,必须逐个查,不能只看最后一次。 u_init()(uclean.h)返回失败,通常意味着数据文件找不到;它只加载一到两个文件,通过也不代表所有数据齐。- 数据打包四种形态:static / library(数据内嵌进
libicudt.so)/ files(散装.res)/ shared。 - 用
.dat包(或 files 模式自定路径)时,必须在任何其它 ICU API 之前调用u_setDataDirectory()或udata_setCommonData(),否则全部资源失败。 - 数据包换字节序或字符集用
icupkg工具处理。 uconv在source/extra/,官方明确不保证支持,但做码页转换排查很好用:uconv -l列可用转换器,uconv -x Any-Hex看实际码点。
升级时的互斥点
SONAME 随大版本跳变(libicui18n.so.78 → .79),没有稳定 ABI。PHP 的 intl、Node、PostgreSQL 的 ICU 依赖,只要有一环还链着旧 SONAME,就会在加载期报 cannot open shared object file 或 undefined symbol。做法是装新版本后立刻用 ldd 检查所有依赖 ICU 的二进制,而不是只看 ldconfig -p 里有几份。
与站内 #8612 的切面差异
#8612 讲 ICU4J 的 SPI 与 java.text.Collator 的兜底边界;这篇只切 ICU4C 的构建、链接与数据加载层。