1. 把一堆 .c 收进一个 .lib:Keil 里那步 Create Library 到底省了什么
小容量 MCU 的 Flash 就那么点,工程里十几个 .c 一编译,.hex 眼看要顶到上限;同一份驱动代码交给协作方,过两天在别人的工程里看到一模一样的实现,连注释都没改。这两件事看着不挨着,在 Keil 里可以用同一个动作处理:把成组的 .c 编译成静态库 .lib。.lib 是目标文件的归档,不是源码,别人拿到也改不动,只能通过你交付的头文件调用;链接器只把被引用到的成员从库里抽出来,没被点名的目标文件不进最终镜像。手上有一批稳定驱动或算法要交付、或者单纯想让工程文件列表短一点的人,都适合走这条路。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 建库工程:从新建 Target 到产出 .lib 的六步配置
2.1 先把链接粒度说清:.lib 是按目标文件抽取的
很多人对静态库的第一印象是"没用到的函数不会生成代码",这句话只对了一半,剩下的一半决定了你后面会不会翻车。Keil 生成的 .lib 本质是一堆 .o 目标文件加上一份符号索引的归档包。链接阶段,链接器扫描调用方 .o 里还没解析的符号,拿这些名字去库的索引里查,命中哪个符号,就把包含这个符号的整个 .o 成员拉进最终镜像。
粒度是 .o,不是函数。这一个事实能推出三个直接后果:第一,如果你把五个函数全写在一个 .c 里,调用方只用了其中一个,剩下四个照样进镜像,体积一点没省;第二,库里的 .o 一旦被拉进来,它引用的其他符号也会变成新的未解析项,链接器得继续去别的库或调用方工程里找;第三,头文件不参与链接,只参与编译,所以头文件和 .lib 必须是同一个版本,错一个字段就是运行期的错位读。
对照一下这几个东西在工程里的位置,后面配起来不容易乱:
| 名词 | 在 Keil 工程里的位置 | 作用 |
|---|---|---|
| .c | Source Group 里的文件 | 编译输入 |
| .o | 中间产物,一般在 Objects 目录 | 链接输入 |
| .lib | Output 页勾选后生成 | .o 归档 + 符号索引 |
| .h | C/C++ 页的 Include Paths | 编译期的声明契约 |
想让"没用到的函数不进镜像"真正成立,办法是拆文件:一个功能模块一个 .c,或者至少把体积大、调用频率低的模块单独拆出去。这是建库之前就要定的事,等库发出去了再改,调用方全部得重新对接。
提示:拆 .c 的时候按"会不会被同时调用"来分组,不要按代码行数切。同一个业务流程里必然一起出现的函数放一个 .c,反而能减少链接器的成员数量。
2.2 目录先分好,后面少返工
建库最容易返工的地方不是配置,是路径。源码、对外头文件、生成的 .lib 如果混在同一个目录里,调用方引用时只能写绝对路径,换台机器就断。我一般先把目录切成四块再动手:
bash复制proj/
app/ # 调用方工程,.uvprojx 放这里
lib_src/ # 库的 .c 源码,只给内部
lib_inc/ # 对外头文件,随 .lib 一起交付
lib_out/ # 编译出来的 .lib
lib_inc 和 lib_src 必须分开,这是纪律问题。lib_src 里可以有内部使用的私有头文件,lib_inc 里只放调用方需要的声明。交付的时候只给 lib_inc 加 lib_out 里的 .lib,源码目录不出去,代码保护这件事才算落地。如果私有头文件也被调用方 Include 进来,等于把内部结构暴露了,改一次结构就得通知所有人。
lib_out 单独放还有一个好处:清理工程时不会误删。Keil 的 Clean 只清 Objects 和 Listings,你把库输出指到独立目录,重新编译时旧库还在,方便对比前后两次的产物大小。
2.3 在原工程里加一个 Target,而不是另起炉灶
新建一个完全独立的库工程看起来干净,实际会带来一个隐蔽问题:器件配置、时钟宏、优化等级全靠手工抄,抄漏一项就是后面"库能编过但跑飞"的根源。更稳的做法是在现有工程里加一个 Target。
操作顺序是这样的:
- 打开调用方工程,菜单 Project → Manage → Project Items,切到 Project Targets 页。
- 新建一个 Target,命名成
LibBuild之类能一眼看出用途的名字。 - 用 Set as Current Target 把它切成当前目标,然后检查 Options for Target 里的器件型号、晶振、C/C++ 宏定义是否和调用方 Target 完全一致。
- 在 LibBuild 下新建一个 Group,命名
LibSrc,把lib_src下要封装的 .c 加进去。 - 把
main.c、启动文件startup_xxx.s从这个 Target 的 Group 里移除。注意是移除引用,不是删文件——同一个文件可以只属于某个 Target。 - 编译一次,确认没有报错,再进行下一步。
第 5 步经常被忽略。启动文件里放着中断向量表,如果它被编进库,而调用方工程也有一份启动文件,链接时就是两份向量表抢同一个地址。移除的做法在 Keil 里是选中文件右键 Remove File from Group,源文件本身还在磁盘上,不影响另一个 Target 使用。
2.4 Output 页只改三个地方
Target 建好之后,Options for Target → Output 页是生成库的总开关。这一页配置项多,但跟建库真正相关的只有三个:
| 配置项 | 建库时怎么填 | 说明 |
|---|---|---|
| Create Library | 勾选 | 勾上之后链接器不再生成可执行文件,改为归档 |
| Name of Executable | 填库名,如 mylib |
生成的产物就是 mylib.lib |
| Select Folder for Objects | 指到 lib_out |
不指的话产物散在 Objects 目录里,容易和 .o 混在一起 |
勾了 Create Library 之后,Output 页下面的 Debug Information、Browse Information 这些选项作用会变。调试信息可以保留,库里的符号信息对后续用 map 文件排查有帮助,代价是 .lib 文件大一点,对最终镜像没影响。Create HEX File 这时候没有意义,可以取消勾选,省一次无用的转换。
还有一点:Name of Executable 这一栏在可执行工程里填的是 .axf 的名字,在库工程里填的就是库名,不用自己加 .lib 后缀,Keil 会按 Create Library 的设定补上。手动加后缀的结果往往是生成 mylib.lib.lib,然后在调用方工程里怎么都找不到文件。
2.5 C/C++ 页:优化等级和宏定义要跟调用方对齐
这一页是"库能编过但行为不对"的高发区。库和调用方是两个独立编译单元,编译器对每个单元单独做优化决策,两边的选项不一致时,最典型的冲突有三类:
第一类是结构体对齐。库编译时用了某个宏打开紧凑布局,调用方没开,同一个结构体在两边的大小不一样。调用方按自己的布局分配栈空间,库按自己的布局往里写,越界写坏相邻变量,现象是"调完这个函数别的变量就变了"。
第二类是内联函数。头文件里定义的 static inline 函数,如果库编译时开了高等级优化把它内联展开,而调用方在低优化等级下需要这个符号的实体,链接器就会报找不到符号。反过来,库在低优化下保留了实体,调用方内联展开,两边的行为也可能有细微差别。
第三类是条件编译。库里的 #ifdef DEBUG 分支和调用方的 DEBUG 宏状态不一致,等于跑了两套代码。
实际操作上,把 C/C++ 页的这几个值抄成一张对照表,建库和调用方各填一遍,对不上就不开工:
| 选项 | 建议值 | 为什么 |
|---|---|---|
| Optimization | 与调用方一致,通常 -O1 或 -O2 | 避免内联和代码生成差异 |
| Define | 只放公共宏,不放调试宏 | 调试宏随环境变,库不能依赖 |
| Include Paths | 只加 lib_inc |
私有头文件不进调用方的搜索路径 |
| C/C++ 标准 | 与调用方一致 | 影响枚举大小和部分语法行为 |
器件型号那一栏虽然不在这页,但同样要对齐。Cortex-M0 和 Cortex-M4 编出来的指令集不同,库拿到另一个内核的工程里链接,运气好是链接报错,运气不好是某条指令不被识别,跑起来直接进 HardFault。
2.6 编完先别急着交付,做一次符号自检
库生成之后,Output 窗口会打印产物路径和归档结果。看到 mylib.lib 出现在 lib_out 里,只能说明编译通过了,不能说明符号齐全。
我的做法是先建一个空的调用方 Target,写一个只包含所有导出函数调用的测试文件,每个函数都调一次、参数随便给,编译链接跑一遍。这一步能抓出两类问题:一是头文件声明了但 .c 里没实现,二是 .c 里实现了但头文件没声明(调用方根本用不了)。测试文件不需要有业务逻辑,能过链接就算过关。
c复制/* lib_selftest.c —— 只验证符号可解析,不做功能测试 */
#include "mylib.h"
void lib_selftest(void)
{
mylib_init(0); /* 每个导出函数至少引用一次 */
mylib_task();
mylib_deinit();
}
这段代码不会被真正执行,它的价值在于让链接器把库里的相关成员全部拉进来一次。如果某个函数在头文件里存在、库里缺失,链接阶段就会报未解析符号,比交付之后被调用方发现要早得多。函数参数给 0 是图省事,真实项目里按头文件注释的取值范围填,顺便验证参数校验逻辑。
3. 调用方工程:头文件、库文件和链接入口怎么接
3.1 头文件是唯一契约,.lib 是黑匣子
.lib 打开是一堆二进制,用反汇编能看到机器码,但看不到变量名、结构体定义和参数含义。所以头文件不是"顺便给的附件",它是这个库唯一的对外说明书。头文件里至少要写清楚四件事:每个函数的返回码含义(0 成功还是 0 失败,负值代表什么)、参数的有效范围、函数是否可重入、有没有依赖外部提供的时钟或中断。
这四件事不写,调用方只能靠猜。猜错返回码的后果最轻,猜错可重入性的后果最重——一个内部用了静态缓冲区的函数被放在两个中断里调用,数据互相覆盖,现象是"偶尔出错、复现不了",这种问题查起来能耗掉一整天。
头文件的写法上,extern "C" 这层包装建议一开始就加上。哪怕当前工程是纯 C,以后有人把库拿到 C++ 工程里用,没有这层包装,C++ 编译器会把函数名做名字修饰,链接器按修饰后的名字去库里找,一个都找不到。加上之后,C 和 C++ 两边都能正常解析。
c复制/* mylib.h —— 随 .lib 一起交付的唯一入口 */
#ifndef MYLIB_H
#define MYLIB_H
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/* 返回 0 成功,-1 参数错,-2 硬件未就绪 */
int8_t mylib_init(uint32_t param);
/* 周期调用,建议 10ms 一次;不可在中断中调用 */
void mylib_task(void);
void mylib_deinit(void);
#ifdef __cplusplus
}
#endif
#endif
代码里的注释就是契约本身。"不可在中断中调用"这一句省掉了后面无数次扯皮,写库的人知道边界在哪,用库的人也知道自己该守什么。参数 param 的具体含义要按实际填,别留成 uint32_t param 就完事——调用方拿到这种签名只能翻源码,而源码又不给。
3.2 两种把 .lib 交给链接器的方式
Keil 里让链接器看到 .lib,有两条路,日常用第一条就够了。
方式一,把 .lib 当普通文件加进 Group。操作是右键目标 Group → Add Existing Files to Group,在文件类型下拉里选 Library file (*.lib),然后选中 lib_out 下的库文件。加进来之后,这个 .lib 会出现在工程树里,图标和 .c 不一样,一眼能区分。这种方式的好处是路径由工程管理,工程搬到哪,相对路径跟着走。
方式二,在 Options for Target → Linker 的 Misc controls 里手写库名和搜索路径。这种方式适合库不在工程目录下、由外部构建系统统一管理的情况。缺点是配置藏在对话框里,新接手的人打开工程看不到库的存在,排查时容易漏。
| 方式 | 配置位置 | 适用场景 | 风险 |
|---|---|---|---|
| Add Existing Files | 工程树 Group | 库随工程走,日常开发 | 换目录要重新加 |
| Linker Misc controls | 对话框文本框 | 库由外部统一构建 | 配置不可见,易漏 |
不管走哪条路,加完之后都要重新编译一次,看 Build Output 里有没有把库作为链接输入列出来。没有列出来,说明文件类型选错了,Keil 把它当源文件处理,编译阶段直接跳过。
3.3 Include Paths 用相对路径
头文件目录加到 Options for Target → C/C++ → Include Paths。这里唯一的建议是:全部用相对路径,基准是 .uvprojx 文件所在目录。
Keil 对相对路径的处理是以工程文件为锚点的,写 ..\lib_inc 就是从工程文件往上一级再进 lib_inc。工程目录结构一旦定下来就不要轻易动,动了之后所有引用它的工程都得改。用绝对路径的工程在单机上跑得好好的,一进版本库、一换机器,路径里带用户名的那一段直接失效,报的错还是"找不到头文件",让人以为是文件丢了。
工程里如果有多个调用方(比如一个产品线好几个变体),把 lib_inc 放在所有工程共同的上级目录,每个工程写各自的相对路径指过去。这样库升级一次,所有变体重新编译就能拿到新版本,不用逐个改路径。
3.4 一个能跑通的最小调用
接线接好之后,先用最小代码验证一次,别急着往里塞业务逻辑。
c复制/* main.c —— 调用方最小验证 */
#include "mylib.h"
int main(void)
{
if (mylib_init(1000) != 0) {
while (1) {
/* 初始化失败,停在这里便于挂调试器看返回值 */
}
}
while (1) {
mylib_task(); /* 周期任务,内部不做阻塞延时 */
}
}
这段代码只做三件事:初始化、检查返回码、进主循环。返回码检查不能省,库内部的失败原因只有库自己知道,调用方拿到负值至少能停下来让人 attach 调试器。主循环里没有加延时,是因为 mylib_task 的注释里写明了"建议 10ms 一次",节拍应该由定时器中断或系统滴答提供,塞个 delay_ms 进去会把整个系统的时序拖乱。
编译链接通过、下载运行不跑飞,这一步才算接完。接下来才是把真实业务代码往里加,加一段编译一次,出问题时能立刻定位到是哪一段引入的。
3.5 库依赖库时的顺序
一个库不太可能完全自给自足,它可能调用另一个库里的函数。这时候链接顺序就有讲究:被依赖的库要排在依赖它的库后面。
原因还是链接器的工作方式。链接器从左到右扫描输入,遇到库就从中抽取当前未解析符号对应的成员。如果先扫到被依赖的库,此时依赖它的库还没被扫到,那些符号还没变成"未解析",被依赖的库里对应的成员就不会被抽取;等后面扫到依赖库、产生新的未解析符号时,前面的库已经扫完了,不会再回头。
在 Keil 的工程树里,这个顺序大致对应 Group 的排列顺序。把基础库放前面、业务库放后面,或者在 Linker 页确认最终传给链接器的库顺序。搞反了的现象很典型:单独编某个库没问题,几个库一起链就报一堆未定义符号,把顺序调一下就全好了。
4. 排查:库能编过却链不过的五种现场
4.1 现象:满屏 undefined symbol,库明明加进来了
链接阶段报一堆 undefined symbol,每个都指向你库里的函数名,但工程树里 .lib 明明在。
原因通常有两个。第一个是头文件和库不同步:头文件里声明的函数签名和库里实际编译出来的不一致,比如头文件写 int8_t mylib_init(uint32_t),库里实现的是 int8_t mylib_init(uint16_t),C 编译器不做跨单元的类型检查,链接器按名字找,找到的符号类型对不上就当作没有。第二个是 C++ 名字修饰:调用方是 C++ 工程,头文件里没加 extern "C",编译器把 mylib_init 修饰成 _Z9mylib_initj 之类的名字去库里找,库里存的是未修饰的 mylib_init,自然找不到。
解决办法:先确认头文件和生成库的那份源码是同一版本,改过签名就重新出库;再检查头文件里的 extern "C" 包装有没有漏。排查时可以看 Build Output 里链接器实际在找的符号名,带下划线前缀和一串编码的,基本就是名字修饰问题。
4.2 现象:L6200E multiply defined,同一个符号出现两次
链接器报 Symbol xxx multiply defined,指向的符号你在库里和调用方工程里各能找到一份定义。
最常见的是全局变量。库的 .c 里写了 uint8_t g_buf[64];,调用方为了省事也写了一份同名同形的定义,两边都进镜像,链接器不知道用哪个。其次是中断服务函数:库为了保证自己能独立工作,把某个中断的处理函数也编进去了,调用方工程里本来就有一份,两份向量表指向同一个中断,冲突。
解决办法:库里只放 extern 声明,真正的定义留在调用方;确实需要库自己持有的状态,用 static 限制在本编译单元内,通过函数接口访问。中断服务函数不要封进库,它是调用方系统集成的一部分,交给使用方实现,库里只提供被中断调用的普通函数。
4.3 现象:链接能过,跑起来进 HardFault 或数据错乱
这是最难查的一类,因为编译和链接全绿,问题在运行期才暴露。
根因基本都是两边编译环境不一致。器件内核不同,库用的是带 FPU 的指令,调用方器件没有 FPU,执行到那条指令直接异常;优化等级不同,结构体里成员的排列和填充不一样,库按自己的布局写,调用方按自己的布局读,读出来是错位的数据;宏定义不同,同一段条件编译在两边走了不同分支。
解决办法:把建库 Target 和调用方 Target 的器件型号、Optimization、Define、C/C++ 标准逐项对一遍,做成清单。对不上的地方以调用方为准,重新出库。这套对照看着笨,但比事后挂调试器一行行看汇编快得多。
4.4 现象:换成本库之后,.hex 反而变大了
本来指望用库减小镜像,结果编译出来一对比,.hex 比原来直接加 .c 还大一圈。
原因是链接粒度。所有函数塞在一个 .c 里,链接器以 .o 为单位抽取,只要调用方用到其中一个函数,整个 .o 连同里面所有函数一起进镜像;再加上库里的调试信息默认保留,文件本身也大。原来直接加 .c 的时候,链接器至少还能做函数级的段回收,换成粗粒度的库之后这层优化反而没了。
解决办法:按功能把 .c 拆开,一个模块一个文件,让"用到才拉"真正生效;如果某个模块内部函数很多、调用关系稀疏,还可以把不常变的工具函数单独拆成一个小库。拆完之后重新对比 map 文件里的成员列表,确认没被调用的模块确实没进镜像。
4.5 现象:本机好好的,同事拉下来就找不到库
工程在你机器上编译通过,同事从版本库拉下来,一编译就报找不到 .lib 或者路径非法。
原因是 .lib 在工程里的引用写成了绝对路径,比如 D:\work\proj\lib_out\mylib.lib。这种路径在别人机器上不存在,Keil 直接报错。另一种情况是 .lib 压根没进版本库——很多人习惯把编译产物排除在外,但 .lib 对调用方来说是输入不是产物,得跟着工程一起提交。
解决办法:工程里所有对 .lib 的引用改成相对路径,基准是 .uvprojx 所在目录;把 lib_out 从忽略规则里拿出来,确保 .lib 进版本库。交付给外部的时候,单独打包 lib_inc 和 lib_out 两个目录,附一份版本号说明,别让对方自己去猜哪个是最新的。
5. 收尾检查:用 map 文件确认库成员真的按需加载
库接完、跑通,还不算完。我习惯在交付前打开 Listings 目录下的 .map 文件,做两件事。
第一件,搜库名,看链接器到底从库里拉了哪些成员进来。map 文件里会按库分组列出被抽取的目标文件,名字对得上你拆的 .c 文件名。如果只调用了一个模块,列表里却出现了全部模块,说明拆文件没拆到位,得回去继续拆。这一步是验证 2.1 节那个粒度结论的唯一硬证据,靠猜是靠不住的。
第二件,对比加库前后的 Image component sizes。Code、RO Data、RW Data、ZI Data 四个数字,跟直接加 .c 的版本比一遍。体积没降下来,大概率是 4.4 节那个原因;体积降了但 RAM 反而涨了,要看库里是不是有大的静态缓冲区被拉进来了,那种情况适合改成调用方传入缓冲区指针。
bash复制# 在 Listings 目录下快速定位库成员的加载情况
# 不同版本 Keil 的 map 段落命名略有差异,按关键字搜即可
grep -n "mylib" myproj.map
这个命令只是把 map 里所有跟库相关的行捞出来,人工扫一遍比任何自动统计都可靠。扫的时候重点看两类行:一类是 Library Member Name,确认抽取粒度;一类是 Removing unused section,确认段回收有没有生效。
从那以后我每次交付 .lib 之前,都强制走一遍「空调用自检 → map 成员核对 → 体积对比」这三步,哪怕这次只改了一个函数。它像一道安全阀:一旦调用方那边出问题,我能立刻分清是头文件版本不对、链接顺序错了,还是库压根没被拉进去。这种确定性,比任何一键打包脚本都值钱。希望帮到你。
