STM32静态库制作与链接原理：从.a文件到固件

（上）篇拆了目标文件、链接脚本和启动流程，这次我打算把焦点放在静态库上。STM32开发里“把代码打包成 .a 文件”这个操作，很多工程师每天在用，但未必清楚链接器到底拿这个文件做了什么，以及为什么有时候函数明明在库里，链接依然报 undefined reference。这篇文章就围绕静态库的制作与原理展开，讲一下 .a 的组成、库工程怎么建、封装代码有哪些讲究、怎么排查链接错误，最后带你在命令行下把库从零手搓一遍。适合要给团队交付二进制库、想压缩编译时间、或者被各种符号问题折磨过的人阅读。

1. 静态库不是玄学：先搞清 .a 文件在干什么

1.1 一个 .a 文件里到底装了什么

静态库在 Linux 和 Windows 上通常叫 libxxx.a，在 Keil 里可能直接生成 xxx.lib，但本质接近：它是一堆目标文件的归档包。目标文件就是 .o 文件，里面装的是机器码、符号表、重定位信息、段信息。你可以把 .a 理解成一个“没有压缩的 ZIP”，只是它不用解压，链接器能直接翻看里面的目录。

我最早接触这一段时，犯过一个认知错误：以为 .a 是个和 .o 平级的“大对象文件”。实际上，用 arm-none-eabi-ar 把库解开，你能看到里面是一个个独立的 .o：

$ arm-none-eabi-ar -t build/libbsp.a gpio.o uart.o timer.o crc16.o

除了这些 .o，归档文件里还有一张全局符号索引表，记录“某个符号在哪个 .o 里”。之所以做索引，是为了让链接器不用遍历每个 .o 的符号表去查符号，直接照索引找就行。既然 .a 本质上就是“目标文件的集合”，那它就没有什么魔法，库文件的原理深度全在“链接器如何消费这个集合”上。

1.2 链接器为什么不是“整包引入”

这是静态库和普通目标文件在链接阶段最大的区别。你链接一个 .o 文件时，这个文件的全部内容都会被搬进最终镜像。但链接一个 .a 文件时，链接器会先扫一遍工程里已经出现过的所有未解析符号，然后对照库里的符号索引，只把包含这些符号的 .o 成员拉进来，其他 .o 一律不进镜像。

举个例子，我的 bsp 库里有一个 dma.o 和一个 key_scan.o。工程里只调用了 key_scan 的函数，那么链接完成后，dma.o 整个不会出现在固件里。反过来，只要 key_scan 里有一个函数被引用了，不管只用了其中哪一个函数，key_scan.o 的整份代码和数据都会进镜像。

这个机制直接解释了很多实际现象：

• 为什么一个库文件很大，但你固件体积没怎么涨；
• 为什么你明明在库里定义了一个函数，链接却报 undefined reference；
• 为什么某些库作者喜欢“一个 .c 文件只放一个函数”。

第三点是很多人的习惯，说到底就是为了躲开“按 .o 为粒度拉取”的限制。如果一个 .c 文件里既有项目正在调用的函数，又有一个没人调但体积很大的调试函数，那你把这个 .o 拉进来时，调试函数也跟着进去了。想实现“函数级裁剪”，比较靠谱的做法是编译时加 -ffunction-sections，再配合链接时的 --gc-sections，让链接器有机会丢弃没被引用的函数段。但库文件本身是别人编好的，如果对方没开这个选项，你在这边拿到的就是“一个 .o 整体进不进来的二选一”。

1.3 为什么 MCU 上很少用动态库

上位机开发中，DLL/SO 满天飞，好处是运行时可加载、可替换，但这一切的前提是有 MMU、有操作系统、有独立的地址空间。Cortex-M 上这些条件都不具备。程序烧进 Flash 后，函数地址和中断向量基本定死在链接阶段，运行期间再去“加载”一段代码，且不说 Flash 改写代价高，光是重定位表的解析、RAM 与 Flash 的分配策略就足够让你放弃。

所以在 STM32 上，静态库就是最自然的复用形式。它在编译期完成符号解析、地址重定位，最终产物和普通源码编出来的固件没有任何区别，运行效率上没有额外开销。这也意味着，库文件一旦生成，和编译器、芯片型号、C 标准库版本的关系就很强，跨工具链使用经常出问题。这一点在后面工程配置的部分会反复踩到。

2. 新建一个 STM32 库工程，CubeIDE 和 Keil 都行

2.1 先想清楚哪些代码适合进库

不是所有代码都适合做成库。我的经验是，放进库的模块通常具备三个特征：稳定、无关平台细节、不太需要被主工程频繁定制。比如 CRC 校验、软件定时器、各种解码器、外设驱动、协议栈，这些都是容易抽成库的东西。

比较难搞的是启动代码、时钟初始化、main 函数本身，以及大量依赖弱符号覆盖的库函数。启动文件和链接脚本天然属于“最终工程”的一部分；时钟树配置在不同板卡上可能天差地别，如果你把 SystemClock_Config 焊死在库里，别人换一块板子就得找你重新出包。碰到这种情况，常见的做法是库提供“带默认实现的弱函数”，比如 HAL 库里的 HAL_MspInit，让主工程可以强符号覆盖，同时又保证用户在偷懒时也有默认行为可用。

还有一点容易被忽略：配置宏的粒度。库里面尽量不要使用一堆“用户必须自行定义”的宏，因为库被编译时这些宏是固定的。如果主工程改了一个宏，库却没重新编，两边看到的结构体大小、数组长度完全不一样，轻则数据错乱，重则直接 HardFault。更稳妥的思路是库提供 Init 结构体或者运行时配置函数，把差异收敛到调用方。

2.2 STM32CubeIDE：三步建一个 Static Library 工程

在 STM32CubeIDE 里建库工程非常顺。新建项目时，在 Embedded Software -> Project Type 下选 Static Library，工具链会自动进入“不生成 main.c，也不走链接”的模式。

重点提一下生成之后的工程结构。CubeIDE 会帮你把编译产物命名为 lib<工程名>.a，中间 .o 文件统一放在 Debug 目录。你把自己的源文件丢进 Core/Src 之后，直接 build，就能得到库文件。

这时候其实还有一个隐藏问题：CubeIDE 默认会给工程添加一堆 HAL 相关的源文件。如果只是想要一个纯粹的纯算法库，这些东西反而碍事。我一般会手动把不用的 HAL 模块从工程里移除，省得最后交付的 .a 里带着一堆用不到的外设代码，虽然链接时会按需拉取，但库的“体检”阶段看着碍眼，排查问题也不清爽。

2.3 Keil 工程：勾选“Create Library”即可

Keil MDK 里操作更隐蔽一点。你正常建立一个新的空工程（不需要添加启动文件），把源文件加进工程后，在 Options for Target -> Output 选项卡里勾上 Create Library。确认下面输出文件名是 libxxx.lib 或 xxx.lib 后，重新编译，就不会调用链接器，而是把目标文件打包成库。

有一个坑必须提醒：Keil 勾选 Create Library 之后，工程里如果还有 main 函数，编译通常没问题，但这个 main 也会被打进库里。之后另一个工程链接这个库时，如果那个工程自己也有 main，就是 multiple definition。所以Keil 的库工程里最好连 main.c 都不要加，省得事后再用符号表检查去排查这类低级错误。

另外，Keil 的库工程不生成 .map 文件，因为根本不链接。你如果想知道自己到底写了哪些符号，需要用命令行工具（比如 fromelf、nm）去看库的符号表，这个我在第 4 章会详细说。

2.4 编译选项必须和主工程对齐

库是别人预先“编好”的东西，它跟主工程必须在一个兼容的 ABI 之下。哪怕代码完全一样，两边编译选项不同，合成一个固件也可能翻车。我列了个自检清单，每次从老工程拆库时都会过一遍：

其中 FPU 的选项最阴险。两个库一个软浮点一个硬浮点，库本身能编过，主工程也能链接成功，但函数调用时浮点参数传递约定不同，参数错位后你看到的现象往往是“计算值莫名多了个 1.1920929e-07”，而不是直接崩掉。排查这类问题非常头疼，所以最省心的做法就是从源头保证两边编译配置一致。

3. 驱动代码怎么拆才能进库：封装与符号控制

3.1 头文件是契约，内部实现要“藏得住”

一个库对外只有头文件和 .a，头文件就是你和用户的契约。写接口时切忌直接把内部变量 extern 出去，也尽量不要让用户看到“这个模块内部还有个三级缓存”。库的真正价值在于你可以随时重写实现，只要头文件不变，调用方无需重新编译。这也是我拆库时最重要的思路：头文件做小、做稳定，源文件里可以放心折腾。

举个例子。我抽过一个很简单的 GPIO 控制模块，头文件只暴露四个函数：

/* bsp_gpio.h */ #ifndef BSP_GPIO_H #define BSP_GPIO_H #include <stdint.h> typedef enum { BSP_GPIO_LOW = 0, BSP_GPIO_HIGH } bsp_gpio_level_t; void bsp_gpio_init(void); void bsp_gpio_set(uint8_t pin, bsp_gpio_level_t level); bsp_gpio_level_t bsp_gpio_get(uint8_t pin); void bsp_gpio_toggle(uint8_t pin); #endif

源文件里具体是操作寄存器还是调 HAL 库，都是实现细节，用户根本不需要知道。这样你的库可以针对不同芯片重新编译，对外接口不变，上层应用代码一行都不用改。这条经验在多车型、多型号产品线里真的能省出一个人的工作量。

3.2 用 __weak 给主工程留“覆盖口”

库代码里最常被主工程覆盖的是错误处理、日志输出、底层初始化钩子。如果你的库直接实现了一个 log_send 强符号，而主工程也想实现 log_send，两边就会撞车。反过来，如果库用 __weak 定义默认实现，主工程只要再定义一个同名强符号，链接器会优先用强符号。

__weak void bsp_error_handler(uint32_t code) { while (1) { /* 默认行为：死循环，方便调试 */ } }

这时候，如果调用方不想一错就跑死循环，它可以自己写一个强符号的 bsp_error_handler，就像给库“打了补丁”。这个机制在 HAL 库里叫回调覆盖，在 RTOS 里叫钩子函数，本质都是弱符号与强符号的链接规则。

有一点得提醒：弱符号不是所有工具链都一视同仁。ARMCC 的 __weak 和 GCC 的attribute((weak)) 语义相近，但你在 Keil 里用 AC5 编库、AC6 编主工程时，偶尔会出现“弱符号覆盖不干净”的老问题。我的意见是同一个项目尽量保持统一编译器，不要混用。

3.3 全局变量尽量走 getter/setter，别直接裸奔

库内部往往有状态变量，比如采样缓冲区、错误计数。你可以直接把这些变量做成全局符号，主工程用 extern 访问。但这会给后续演进埋雷：一旦你想把缓冲区改成动态分配或加锁，就必须打破头文件里的 extern 声明。封装成 getter/setter 后，改内部实现的代价几乎为零。

/* 库里 */ static volatile uint32_t s_fault_count = 0; void bsp_fault_increase(void) { s_fault_count++; } uint32_t bsp_fault_get_count(void) { return s_fault_count; }

主工程看不到 s_fault_count 这个符号，只能通过函数访问。这样还有一个附带好处：链接器可以发现这个变量“只被函数访问”，配合优化把代码放到合适的位置，对镜像布局更友好。直接扔全局 extern 的变量没有这层控制，很难优化。

4. 制作与验证：用符号表和反汇编检查库的“健康状态”

4.1 编译产物到底在哪，长什么样

不管用什么 IDE，编译结束后你都需要找到那个 .a/.lib 文件。CubeIDE 默认叫 libbsp.a，Keil 默认叫 bsp.lib。我建议拿到库之后，先做一轮“体检”，别急着丢给同事。

第一件事是列成员：

arm-none-eabi-ar -t bsp.a

第二件事是看符号表：

arm-none-eabi-nm -S --size-sort bsp.a

nm 输出的每一行第一列是符号地址（在 .a 里可能为 0），第二列是符号大小，第三列是符号名。符号类型里最重要的是大写 T（代码段全局函数）、D（已初始化全局数据）、B（未初始化全局数据）、U（未解析的外部符号）。我拿到库会先筛一遍 U 类型，看看库对外暴露了哪些依赖，如果意外出现 printf、memcpy 之类，得确认主工程是否有这些符号来源。

4.2 主工程链接一个库的最小姿势

假设我现在有一个 demo 工程，里面只有 main.c 和一个库文件 libbsp.a。在 GCC 工具链下，链接命令长这样：

arm-none-eabi-gcc -mcpu=cortex-m4 -mthumb -mfloat-abi=hard -mfpu=fpv4-sp-d16 \ -T stm32f4_flash.ld \ main.c libbsp.a \ -o demo.elf

注意库文件的位置。GNU 链接器在扫描参数时是从左到右的，它扫描到 libbsp.a 时，如果这个时候前面的目标文件还没有产生对库符号的引用，这个库里的相关 .o 不会被拉进来；等到链接后面再冒出新的引用，前面已经“路过”的库里就不会再去找了。所以强烈建议把库放到所有源文件/目标文件的右边，这是 undefined reference 最常见的原因之一。

4.3 用 map 文件确认哪些目标文件进入了固件

链接完成后，打开生成的 .map 文件，搜索库名，能看到这样一段：

Archive member included to satisfy reference by file (symbol) .../libbsp.a(gpio.o) main.o (bsp_gpio_init) .../libbsp.a(crc16.o) main.o (crc16_update)

这段话非常直白地告诉你，链接器“因为谁”的哪个符号，把库里的哪个 .o 拉进了镜像。如果你发现某个模块出现在 map 文件里，但你根本没打算用它，那说明你的代码有隐藏引用，或者你用了 --whole-archive 把它强制引入了。我排查“固件体积莫名变胖”的问题时，第一步就是看这个列表。

4.4 反汇编“现场验证”：函数确实在预期地址

符号表和 map 文件只能说明“符号存在”，要看它是不是真的可执行，我会习惯性反汇编一下：

arm-none-eabi-objdump -d demo.elf | grep -A 30 '<bsp_gpio_init>:'

看到 bsp_gpio_init 的反汇编代码，并确认它跳转/访问的地址都在合法范围，基本可以断定这个库被正确链接。尤其在栈回溯、中断处理这类场景里，反汇编的确认价值比看 C 源码可靠得多，因为优化器完全可能把函数改成你不认识的样子。

5. 常见报错与排查实录

5.1 undefined symbol：函数明明在库里，链接就是找不到

这是我被问得最多的问题。别急着怀疑库文件坏了，先按这个顺序排查：

1. 确认符号拼写。C++ 编译出来的符号会带 name mangling，C 和 C++ 混用时必须用 extern "C" 包住头文件。
2. 确认库路径和库文件名。GCC 的 -l 参数会把 -lxxx 自动拼成 libxxx.a，如果你的库叫 my_lib.a，那么 -lmy_lib 没错；但如果你的库叫 xxx.lib 或者没有 lib 前缀，-l 就找不到，直接给完整路径最保险。
3. 确认链接顺序。把库放在所有目标文件之后，这条前面说过，直接按“源文件/目标文件 -> 库”的顺序摆。
4. 确认链接器有没有因为 --gc-sections 把符号丢弃。如果库的编译阶段没有把函数单独放到 section 里，这步一般不会误删；但如果你开了 -ffunction-sections + --gc-sections，且库里的函数没人引用，被丢弃是符合预期的。
5. 用 nm 再查一遍符号名，老老实实对着抄，不要自认为“我肯定没拼错”。

arm-none-eabi-nm libbsp.a | grep bsp_gpio_init

如果输出是：

00000000 T bsp_gpio_init

说明符号存在，问题出在链接顺序或参数。如果输出是：

00000000 t bsp_gpio_init

小写 t 表示 static 函数，外部调用当然找不到。

5.2 multiple definition：同一个符号出现在多个地方

这类报错通常发生在新老库混用、重复包含 .o 的场景。最常见的三种来源：

• 库工程里包含了一个 main.c，主工程也有 main.c；
• 同一个源文件既被打进了库，又参与了主工程编译；
• 调用了两个不同的库，而这两个库里有相同模块的实现。

前两种通过调整工程结构就能解决。第三种比较麻烦，我一般先看符号表找重复来源，确认两个库都定义了同一组函数，再决定要不要在链接时用 --allow-multiple-definition 暂时压掉。但注意这只是掩耳盗铃，两个定义谁生效取决于链接顺序，行为不可控。长期方案还是要对库做符号层面的命名空间隔离，比如给每个库的函数加项目前缀。

5.3 库和主工程“对齐”不一致：奇怪的 HardFault

这种问题最让人崩溃，链接能过、烧录能跑，但一执行某个库函数就是 HardFault，或者返回的数据不对。排查方向要转向 ABI 和配置对齐。

举一个真实例子：某库编译时用了 -mfloat-abi=hard，而主工程用的是 softfp。两边都是浮点操作，但函数参数传递的寄存器规则不同。主工程把一个 float 放到 R0，库函数却从 S0 里取参数，结果自然错乱。想定位这类问题，光看 C 代码没用，需要用 objdump 反汇编对比主工程调用处和库函数入口处的参数寄存器使用情况。

另外，所有与“结构体大小”相关的宏也必须一致。库里结构体按 4 字节对齐，主工程却开了 #pragma pack(1)，两者对同一个结构体的大小认知不同，调用时数据错位。排查这种问题最直接的办法是双方各自打印 sizeof(struct)，不一致就顺着宏定义追溯。

5.4 KEEP 和 --gc-sections：中断函数被当成垃圾收走了

静态库里放中断服务函数是常事，但链接器有可能在 --gc-sections 裁剪时把“没有任何代码引用”的中断函数当作垃圾丢掉。中断向量表虽然在启动文件里，但表里引用中断函数的方式可能是一个绝对地址符号，某些场景下链接器不会把它看作强引用。

解决方案有两个。第一，在库源码里给中断函数加保留属性：

__attribute__((used, retain)) void TIM2_IRQHandler(void) { /* ... */ }

GCC 的 used 告诉编译器“这个符号即使没被直接引用也要保留到目标文件中”，retain 则表示不要在 LTO 和 section GC 阶段删除它。第二，在链接脚本里对包含中断函数的 section 加 KEEP：

. = ALIGN(4); KEEP(*(.isr_vector)) KEEP(*(.text*TIM2_IRQHandler*))

如果你是在 Keil 里做库，可以给相应函数加上attribute((used))，或者在工程配置里关掉 --remove 的某些选项。不过关全局裁剪属于下策，影响面太大，尽量定点保留。

5.5 链接顺序问题速查表

我凭记忆整理了一份排查时最常用到的速查表，不算完整，但覆盖了大部分日常场景。

6. 命令行手搓一次静态库：把原理落到实锤

6.1 准备环境

很多读者其实没有命令行编译过 STM32 工程，但命令行恰恰是最能暴露原理的方式。准备一个 arm-none-eabi-gcc 工具链，不管是 ARM 官方还是某种 IDE 内置的都行。Windows 下我建议把工具链的 bin 目录加进 PATH，Linux/macOS 下通常默认就有。

然后建立一个小测试目录：

libtest/ ├── bsp_gpio.c ├── bsp_gpio.h ├── main.c └── stm32f4_flash.ld

为了演示，bsp_gpio.c 里随便写两个函数，比如：

#include "bsp_gpio.h" static volatile uint32_t *const GPIOB_ODR = (uint32_t *)0x40020414; void bsp_gpio_init(void) { /* 演示代码，设置为输出 */ *(uint32_t *)0x40020400 |= (1 << 0); } void bsp_gpio_set(uint8_t pin, bsp_gpio_level_t level) { if (level == BSP_GPIO_HIGH) { *GPIOB_ODR |= (1 << pin); } else { *GPIOB_ODR &= ~(1 << pin); } }

main.c 里写一个普通调用：

#include "bsp_gpio.h" int main(void) { bsp_gpio_init(); bsp_gpio_set(1, BSP_GPIO_HIGH); while (1) { } }

6.2 编译出目标文件

进入 libtest 目录，执行：

arm-none-eabi-gcc -c -mcpu=cortex-m4 -mthumb -O2 -ffunction-sections -fdata-sections \ -I. bsp_gpio.c -o bsp_gpio.o

-c 的意思是只编译不链接。此时你会得到 bsp_gpio.o。再看一下这个文件的段：

arm-none-eabi-objdump -h bsp_gpio.o

由于加了 -ffunction-sections，每个函数会单独占一个段，名字形如 .text.bsp_gpio_init 和 .text.bsp_gpio_set。这个细节很关键，它意味着后续 --gc-sections 能精确到函数级进行裁剪。

6.3 用 ar 打包成静态库

打包命令：

arm-none-eabi-ar crs libbsp.a bsp_gpio.o

参数 c 表示创建，r 表示插入/替换，s 表示写入索引。加 s 很重要，没有索引的库在链接时某些工具链会额外警告，甚至部分版本链接失败。如果后面发现符号表缺失，可以用下面命令补齐索引：

arm-none-eabi-ranlib libbsp.a

打完包之后，用 ar -t 看成员，用 nm 看符号：

arm-none-eabi-nm -S libbsp.a

正常情况下能看见：

00000000 00000018 T bsp_gpio_init 00000000 0000001c T bsp_gpio_set 00000004 C bsp_gpio_level_t??

最后那行不用太纠结，不同工具链对类型常量的符号化方式不同。关注点应该放在大写 T 上，符号被导出，主工程才能调用。

6.4 链接一个完整固件

现在链接 main.c 和库：

arm-none-eabi-gcc -mcpu=cortex-m4 -mthumb -O2 -ffunction-sections -fdata-sections \ -T stm32f4_flash.ld \ main.c libbsp.a \ -Wl,--gc-sections \ -nostartfiles -lc -lm -lnosys \ -o demo.elf

注意这里我故意加了 -nostartfiles，因为我们不引入启动文件，只是演示链接原理。实际工程要带启动文件和必要的系统库，顺序一般是：启动文件、目标文件、库、系统库。链接完成后，用 nm 查看 demo.elf：

arm-none-eabi-nm -n demo.elf | grep bsp_gpio

你会看到 bsp_gpio_init 和 bsp_gpio_set 现在有了真实地址。再对应的反汇编确认代码落位：

arm-none-eabi-objdump -d demo.elf | grep -A 40 '<main>:'

到这里，“源文件 -> .o -> .a -> elf”的完整链路就通了。你亲眼看到库里的函数从“存在于 .a”到“出现在最终镜像”的过程，之后再遇到链接问题，脑子里会自然浮现这条链路的每一步。

6.5 手工验证“没被引用的 .o 不进入镜像”

这是静态库原理最好玩的地方。我再加一个 unused.c，里面放一个函数：

int dead_weight(void) { return 0xdead; }

编成 unused.o，打包进同一个库：

arm-none-eabi-gcc -c unused.c -o unused.o arm-none-eabi-ar crs libbsp.a bsp_gpio.o unused.o

重新链接同一个 main.c，然后查 map 文件，或者直接查 demo.elf 符号：

arm-none-eabi-nm demo.elf | grep dead_weight

你会发现什么都没有。因为整个链接过程中没有任何代码引用 dead_weight，在 --gc-sections 帮助下，它连进入镜像的机会都没有。这就是我在第 1 章讲的“按需拉取”的实证。很多人在面试中被问“静态库链接时是全量还是部分”，其实跑一次这个实验就再也不会忘了。

最后再分享一个实操习惯

做库做多了之后，我养成了一个强迫症：每次把库文件交付出去之前，先跑一遍“符号体检脚本”。脚本逻辑不复杂，用 nm 抓出所有带 T 的全局函数，再和一份接口清单比对，禁止库导出任何清单之外的符号。这个习惯帮我拦下过好几次“把调试用的 dump 函数也导出给别人”的尴尬事。另外，库工程和主工程尽量用同一版本的工具链维护，虽然听起来很基础，但项目一多、人一换，这种事情就是会层出不穷。如果你刚开始拆库，我建议从一个小外设驱动做起，完整走一遍“建库工程 -> 拆代码 -> 链接验证 -> 处理报错”的流程，踩过一轮坑之后，你对链接器的理解会比读十篇文章都深。