C++ ABI 与跨库兼容：为什么换编译器要重编、符号可见性

换了个编译器、或者把 std::string 穿过动态库边界传进传出，程序就可能莫名其妙地崩。根子不在语法，而在 ABI（Application Binary Interface，应用二进制接口）：它管的是「编译出来的二进制怎么互相咬合」。这篇讲清 ABI 包含哪几样、为什么 GCC 和 Clang 的标准库不兼容、怎么用 -fvisibility=hidden 控制导出符号，以及为什么跨库稳定接口只能走 C ABI。

1. 引子：标准库类型的大小是「实现细节」

同一个 std::string，在 GCC 的 libstdc++ 里 64 位下是 32 字节（用了短字符串优化 SSO，短串不堆分配），在 Clang 的 libc++ 里是 24 字节，在旧版 MSVC 里又是另一种布局。这意味着：一个动态库用 libstdc++ 编译、另一个用 libc++ 编译，它们对 std::string 的理解就不同。跨库传 std::string 等于把两种不同布局的二进制硬接在一起，必崩。

#include <iostream>
#include <string>

int main() {
    std::cout << "sizeof(std::string) = " << sizeof(std::string) << '\n';
    std::string s = "hello, world";   // 短字符串，SSO 下不触发堆分配
    std::cout << "内容 = " << s << "  长度 = " << s.size() << '\n';
    // s.capacity() 是 SSO 阈值（libstdc++ 下通常是 15）
    std::cout << "容量 = " << s.capacity() << '\n';
}

sizeof(std::string) = 32
内容 = hello, world  长度 = 12
容量 = 15

官方文档：std::basic_string 只保证行为，不规定内存布局——布局是各标准库的实现细节，这正是跨库传递危险的原因。

2. ABI 到底包含什么

ABI 不是「一门语言规则」，而是一整套「二进制契约」，任何一条不一致都可能让两个二进制无法正确对接：

ABI 的组成部分	举例	不一致会怎样
对象内存布局	成员偏移、vptr 位置、padding	读错字段、越界
名字修饰（name mangling）	_Z3addii	链接报 undefined reference
函数调用约定	参数放寄存器还是栈	参数错乱、崩溃
异常处理	栈展开、landing pad 表	异常穿过边界时崩溃
标准库实现	std::string/std::vector 布局	跨库传标准库类型出错

官方文档：Itanium C++ ABI 是 GCC/Clang 在 Linux 上共同遵循的 ABI 规范——正因如此，GCC 和 Clang 编出的 C++ 二进制通常能互链，但它们各自的标准库（libstdc++ vs libc++）并不 ABI 兼容。

3. 符号可见性：默认全导出，.so 又大又慢

编译动态库时，GCC 默认把所有非 static 函数都导出到动态符号表。一个本该私有的 hidden_fn 也成了公开符号——符号表变大、加载变慢、还可能被外部意外依赖。用 -fvisibility=hidden 让「默认隐藏」，再给真正要公开的接口加 __attribute__((visibility("default"))) 显式导出。

下面这个动态库，hidden_fn 被隐藏、exported_fn 显式导出。用 nm 看真实符号（大写 T 是全局导出，小写 t 是本地隐藏）：

$ nm -C libmylib.so
0000000000001110 T exported_fn()
0000000000001100 t hidden_fn()

$ nm -D -C libmylib.so      # -D：只看动态导出符号表
0000000000001110 T exported_fn()

nm -D 里只剩 exported_fn：hidden_fn 彻底从动态符号表消失，外部链接不到它。

// lib.cpp —— 编译成动态库
// 未标记：被 -fvisibility=hidden 隐藏，符号为本地（t）
int hidden_fn() { return 1; }

// 显式导出：符号为全局（T），能被外部链接
__attribute__((visibility("default"))) int exported_fn() { return 42; }

符号类型字母	含义
T	代码段的全局（导出）符号
t	代码段的本地（隐藏）符号，外部不可见
D / d	数据段全局 / 本地符号
U	未定义（需要外部提供）的符号

官方文档：GCC Visibility 官方 Wiki 说明 -fvisibility 与 __attribute__((visibility("default"))) 的用法和收益。

4. 隐藏符号的三个收益

把内部符号隐藏掉，不只是「洁癖」，有实打实的好处：

收益	原因
.so 体积更小	少了一堆导出符号和重定位项
加载更快	动态链接器要处理的重定位变少
编译可内联优化	编译器知道符号不会被外部引用，能更大胆地内联/消除

5. C ABI：唯一的稳定跨库边界

既然 C++ ABI 这么脆弱，跨库的稳定接口就退回到 C ABI：extern "C" 关掉名字修饰（符号稳定），配合**不透明指针（opaque pointer）**把 C++ 对象藏起来。下面是一个完整的「库 + 调用方」最小框架，C 侧只看到 Handle*，完全不知道内部结构。

#include <iostream>
#include <memory>

// 不透明指针：C 侧只拿到 Handle*，看不到结构体内部
struct Handle;

// 导出给 C 的稳定接口（extern "C" 关掉名字修饰）
extern "C" Handle* handle_create(int v);
extern "C" int handle_get(const Handle* h);
extern "C" void handle_destroy(Handle* h);

// ---- 以下为 C++ 侧实现 ----
struct Handle { int value; };

Handle* handle_create(int v) {
    auto p = std::make_unique<Handle>();
    p->value = v;
    return p.release();          // 所有权转交给 C 侧调用方
}

int handle_get(const Handle* h) { return h->value; }

void handle_destroy(Handle* h) {
    std::unique_ptr<Handle> guard{h};   // 接管并 RAII 释放
}

int main() {
    Handle* h = handle_create(7);
    std::cout << "handle_get = " << handle_get(h) << '\n';
    handle_destroy(h);
}

handle_get = 7

关键点：C ABI 稳定，是因为它不涉及重载、模板、对象布局、异常——只有「函数名 + 参数类型」这套 C 编译器也能理解的简单契约。

既然异常不能安全穿过 C 边界，C ABI 的错误处理通常退回错误码：函数返回 0 表示成功、非 0 表示失败，结果通过出参带回来。

#include <iostream>

// C ABI 风格：错误用返回值表达，异常在边界内消化，绝不抛出去
extern "C" int divide(int a, int b, int* out) {
    if (b == 0) return -1;   // 错误码：除零
    *out = a / b;
    return 0;                // 成功
}

int main() {
    int result = 0;
    int rc = divide(10, 2, &result);
    std::cout << "rc=" << rc << " result=" << result << '\n';
    rc = divide(10, 0, &result);
    std::cout << "rc=" << rc << "（除零错误码）\n";
}

rc=0 result=5
rc=-1（除零错误码）

6. 完整示例：可见性 + C ABI 边界一起验证

用 CMake 建一个动态库（默认隐藏 + 显式导出 + 一个 C ABI 接口），主程序链接并调用，同时用 nm 看导出符号。

# CMakeLists.txt
cmake_minimum_required(VERSION 3.16)
project(abi_demo LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
add_library(mylib SHARED lib.cpp)
target_compile_options(mylib PRIVATE -fvisibility=hidden)
add_executable(demo main.cpp)
target_link_libraries(demo PRIVATE mylib)

// lib.cpp —— 动态库实现
#include <cstdio>

__attribute__((visibility("default"))) int public_api(int x) { return x * 2; }
int internal_helper(int x) { return x + 1; }   // 默认隐藏

// verify: skip
// main.cpp —— 多文件工程的一部分（public_api 定义在 lib.cpp），单文件无法链接，真跑见下方 text 块
#include <cstdio>

__attribute__((visibility("default"))) int public_api(int x);

int main() {
    std::printf("public_api(21) = %d\n", public_api(21));
}

真构建运行（godbolt CMake 端点）后，程序输出与符号表如下：

public_api(21) = 42

$ nm -D -C libmylib.so
0000000000001110 T public_api(int)

只有 public_api 进了动态导出表，internal_helper 被隐藏。这就是控制符号可见性的完整效果。

7. 延伸阅读

• Itanium C++ ABI —— GCC/Clang 的 ABI 权威定义，对象布局、mangling、异常、RTTI 都在这里。
• GCC Visibility Wiki —— -fvisibility 的官方说明与最佳实践。
• cppreference：std::basic_string —— 确认标准库类型「只定义行为、不定义布局」。
• cppreference：语言链接 —— extern "C" 作为 C ABI 边界的语法依据。
• Compiler Explorer（godbolt） —— 编一个动态库，看 -fvisibility=hidden 前后的导出符号差异。

本知识库内的相关篇目：

• 《C++ 名字修饰（name mangling）与 extern “C”：C/C++ 互操作》 —— 用 nm/nm -C 真实符号表讲清名字修饰
• 《静态库 vs 动态库：-fPIC、PLT/GOT、LD_PRELOAD、链接顺序》 —— 用 nm/readelf/ldd/size 的真实输出讲清静态库 .a 与动态库 .so 的本质差异
• 《异常的实现与代价：零成本异常、栈展开与 -fno-exceptions 什么时候用》 —— C++ 异常常被说「零成本」，但它的代价藏在抛出路径上。

8. 一句话总结

C++ ABI 是「对象布局 + 名字修饰 + 调用约定 + 异常 + 标准库细节」的整套二进制契约，GCC 与 Clang 的标准库不 ABI 兼容，所以 std::string 之类标准库类型不能跨动态库边界传；控制导出符号用 -fvisibility=hidden + 显式 default，而真正的稳定跨库边界只有 C ABI（extern "C" + 不透明指针）。