1 / 4概念
Toolchain: Packaging
C 的打包不是“发一个二进制”,而是回答三个问题:产物是静态库还是共享库,库的名字与版本如何被链接器和加载器解析,消费者如何拿到头文件与链接参数。做完能让 pkg-config --cflags --libs foo 在干净机器上直接可用,也能判断一次升级该不该换 soname。
1 概念
1.1 一句话定义
C 的打包是把目标文件、头文件、元数据与许可证组织成可被他人链接或加载的单元;静态库把代码复制进消费者,共享库在运行期由加载器按 soname 解析,pkg-config 的 .pc 文件负责把编译与链接参数传给构建系统。
1.2 它解决什么问题
- 消费者不知道路径:头文件在
include/、库在lib/,需要一种机制自动给出-I与-l。 - 升级破坏兼容:改了结构体或函数签名后,旧二进制仍会加载新库,直到运行到出错的那一行。
- 静态与动态取舍:部署简单性与安全更新能力相互冲突。
- 许可证义务:静态链接 GPL 库与动态链接 LGPL 库的责任完全不同。
代价是多了一层命名与元数据契约:名字写错、版本号写错、.pc 字段写错,都会变成运行期的“找不到库”。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
| 调用约定、结构体布局与 ABI | c-object-model-and-abi |
跨语言绑定与 extern "C" | c-ffi |
| 符号解析与装载器细节 | c-linking-and-loading |
| 构建规则、install 与 export | c-make-and-cmake |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
| 静态库 | .a,成员按需抽取并复制进消费者 | 不是“静态链接的可执行文件” |
| 共享库 | .so/.dylib/.dll,运行期加载 | 不是静态库的压缩 |
| soname | 库的 ABI 标识,链接时写入 NEEDED | 不是文件名 |
| linker name | libfoo.so,供 -lfoo 使用 | 不是 soname |
| real name | libfoo.so.1.0.0,磁盘上的实际文件 | 不是链接名 |
| pkg-config | 用 .pc 文件传递编译与链接参数 | 不是包管理器 |
2 机制
2.1 心智模型
共享库有三个名字和一条符号边界。 链接时用 libfoo.so,运行时用 libfoo.so.1(soname),磁盘上是 libfoo.so.1.0.0(real name);-fvisibility=hidden 让符号默认不可见,只导出带 FOO_API 的函数。soname 是 ABI 承诺的粒度:兼容升级不动 soname,破坏兼容就换号。
2.2 机制拆解
- 库形态:
ar rcs libfoo.a foo.o打归档,链接器只抽取被引用成员,消费者得到代码副本;共享库要求每个对象加-fPIC,用-shared -Wl,-soname,libfoo.so.1链接,-Wl,--no-undefined让缺失依赖在链接期暴露。忘记-fPIC的报错是relocation R_X86_64_32 ... can not be used when making a shared object。 - 三个名字与符号链接:
libfoo.so指向libfoo.so.1,再指向libfoo.so.1.0.0;链接器读 linker name,加载器按 soname 查找,ldconfig维护缓存。 - 符号可见性:默认
default,-fvisibility=hidden把默认改为隐藏,再用__attribute__((visibility("default")))显式导出公共 API。隐藏符号不进入动态符号表,既缩小 ABI 面,也便于编译器优化。 - pkg-config:
.pc文件用prefix、exec_prefix、libdir、includedir变量和Name、Description、Version、Requires、Requires.private、Cflags、Libs、Libs.private字段描述包;--cflags、--libs、--static、--modversion是常用查询。安装布局固定为${prefix}/include、${prefix}/lib、${prefix}/lib/pkgconfig。 - 版本与 ABI:兼容变更(增加函数或符号)只进 minor,破坏变更(改结构体布局、函数签名、enum 值、删除符号、改调用约定)必须进 major 并换 soname。
- vendoring 与发行版:vendoring 把第三方源码放进仓库并固定 commit,构建可复现但安全更新要手工跟进;发行版打包由维护者处理 ABI、补丁与生命周期,代价是版本落后。
- 许可证:MIT、BSD 与 Apache-2.0 属宽松许可,保留版权与许可声明即可;LGPL 允许动态链接闭源程序,静态链接需提供可重新链接的目标文件;GPL 具传染性,分发衍生作品须以同许可开放源码。
2.3 完整枚举
ELF 平台的符号可见性共四种,GCC 与 Clang 都支持:
| 可见性 | 含义 | 链接行为 | 典型用法 |
|---|---|---|---|
| default | 导出,可被其它模块引用 | 进入动态符号表 | 公共 API |
| hidden | 不导出,仅本模块可见 | 不进入动态符号表 | -fvisibility=hidden 的默认值 |
| protected | 导出,但模块内引用绑定本地,不可被插入 | 进入动态符号表 | 少数性能敏感符号 |
| internal | 类似 hidden,且禁止跨模块引用 | 不进入动态符号表 | 编译器内部使用 |
3 实践
3.1 最小示例与追踪
示例把同一份代码打成共享库与静态库,并写一个 .pc 文件给消费者。
/* include/foo.h */
#ifndef FOO_H
#define FOO_H
#if defined(_WIN32)
# define FOO_API __declspec(dllexport)
#else
# define FOO_API __attribute__((visibility("default")))
#endif
FOO_API int foo_parse(const char *s);
#endif
/* src/foo.c */
#include <string.h>
#include "foo.h"
int foo_helper(const char *s) { return (int)strlen(s); } /* 内部符号 */
int foo_parse(const char *s) { return foo_helper(s) > 0; }
cc -std=c17 -O2 -fPIC -fvisibility=hidden -Iinclude -c src/foo.c -o build/foo.o
cc -shared -Wl,-soname,libfoo.so.1 -Wl,--no-undefined -o build/libfoo.so.1.0.0 build/foo.o
ln -sf libfoo.so.1.0.0 build/libfoo.so.1
ln -sf libfoo.so.1 build/libfoo.so
ar rcsD build/libfoo.a build/foo.o
# foo.pc
prefix=/opt/foo
exec_prefix=${prefix}
libdir=${exec_prefix}/lib
includedir=${prefix}/include
Name: foo
Description: Minimal parser library
Version: 1.0.0
Libs: -L${libdir} -lfoo
Libs.private: -lm
Cflags: -I${includedir}
install -d /opt/foo/lib/pkgconfig /opt/foo/include
install -m 755 build/libfoo.so.1.0.0 /opt/foo/lib/
ln -sf libfoo.so.1.0.0 /opt/foo/lib/libfoo.so.1
ln -sf libfoo.so.1 /opt/foo/lib/libfoo.so
install -m 644 include/foo.h /opt/foo/include/ && install -m 644 foo.pc /opt/foo/lib/pkgconfig/
export PKG_CONFIG_PATH=/opt/foo/lib/pkgconfig
cc -std=c17 main.c $(pkg-config --cflags --libs foo) -o app
readelf -d app | grep NEEDED
readelf -d /opt/foo/lib/libfoo.so.1.0.0 | grep SONAME
nm -D --defined-only /opt/foo/lib/libfoo.so.1.0.0
ldd app
pkg-config --libs --static foo
追踪:链接 app 时,-lfoo 找到 libfoo.so,链接器读取 libfoo.so.1.0.0 的 SONAME 并把 libfoo.so.1 写进 app 的 NEEDED;运行时加载器按 libfoo.so.1 找文件,经符号链接落到 real name。nm -D 只列出 foo_parse,因为 -fvisibility=hidden 把 foo_helper 移出了动态符号表;若报错里出现 foo_helper,说明链接时漏了这个选项。pkg-config --libs --static foo 在 -lfoo 后追加 -lm(假设库内部用到 libm),这是 Libs.private 的唯一作用。把 /opt/foo/lib 加入 /etc/ld.so.conf.d/foo.conf 后运行 ldconfig,或链接时写 -Wl,-rpath,/opt/foo/lib,否则 ldd 会报 libfoo.so.1 => not found。
3.2 选型矩阵
| 场景 | 首选 | 备选 | 理由 |
|---|---|---|---|
| 单二进制、无外部消费者 | 静态库 | 直接编译源文件 | 无运行时依赖,部署简单 |
| 多程序共享、需独立升级 | 共享库加 soname | 静态库 | 升级不必重编消费者 |
| 跨语言 ABI 边界 | 共享库加隐藏符号 | 静态库 | 导出面小,边界稳定 |
| 发行版分发 | 源码包加 distro 规则 | 预编译二进制 | 由发行版处理 ABI 与安全更新 |
3.3 决策规则
- 所有进入共享库的目标文件都应加
-fPIC;只在链接命令加-shared会在重定位阶段失败。 - soname 只在不兼容变更时递增;加函数、加符号只升 minor,消费者无需重编。
- 默认隐藏符号,只导出公共 API;导出面越小,后续改内部实现越自由。
.pc的Libs只放直接依赖,私有依赖放Libs.private或Requires.private,否则静态链接会漏库。- 选择静态链接前先过一遍许可证;LGPL 与 GPL 的义务不会因为“只是编译进去”而消失。
4 边界
4.1 典型故障
| 症状 | 根因 | 诊断 | 修复 |
|---|---|---|---|
error while loading shared libraries: libfoo.so.1 | 缺 soname 链接,或目录不在加载器搜索路径 | readelf -d app 看 NEEDED,ls -l /opt/foo/lib | 补 libfoo.so.1 链接,设 rpath 或 ldconfig |
relocation R_X86_64_32 ... can not be used | 目标文件没加 -fPIC | 报错指向具体 .o | 所有进共享库的对象重编加 -fPIC |
| 升级 minor 后老程序崩溃 | 改了结构体布局、函数签名或 enum 值 | abidiff old.so new.so | 按不兼容变更处理,升 major 并换 soname |
undefined reference 只在静态链接出现 | Libs.private 少了依赖 | pkg-config --libs --static foo 看输出 | 补 Libs.private 或 Requires.private |
pkg-config --exists foo 返回非零 | .pc 不在 PKG_CONFIG_PATH,或字段缺失 | pkg-config --debug 看搜索目录 | 设 PKG_CONFIG_PATH,补齐 Name 与 Version |
nm -D 出现大量内部符号 | 没开 -fvisibility=hidden | nm -D --defined-only libfoo.so.1.0.0 | 加编译选项与 FOO_API 导出宏 |
| 静态链接 LGPL 库后被要求开源 | 未履行重新链接义务 | 许可证审计与 SBOM | 改动态链接,或提供目标文件与重新链接材料 |
4.2 可观测信号
先看名字与依赖:readelf -d 给出 SONAME、NEEDED、RPATH 与 RUNPATH,ldd 或 macOS 的 otool -L 显示实际解析结果,ldconfig -p | grep foo 确认缓存。再看符号面:nm -D --defined-only 列出导出符号,objdump -T 给出动态符号表,readelf -s 区分绑定与可见性。升级前用 abidiff 或 abi-compliance-checker 对比两版库,pkg-config --debug 定位 .pc 搜索失败,strings libfoo.so | grep "$(pwd)" 检查绝对路径是否进入产物。
4.3 安全 / 性能 / 一致性边界
- 安全更新:静态链接把库代码冻结在发布物里,库出 CVE 后必须重编并重新分发;共享库可由系统包管理器统一修复,但要求 soname 不变。
- ABI 不是 API:只增不改的 C 接口可以保持 ABI,但结构体大小、字段偏移与 enum 值一旦变化就破坏兼容;符号版本化只能防旧符号被替换,不能保证语义兼容。
- 许可证:动态链接与静态链接在 LGPL 下的义务不同,分发前应生成 SBOM 并逐项核对;Apache-2.0 还需保留
NOTICE,MIT 与 BSD 需保留版权声明。