3. 源文件组织与编译流程

在 SEGGER Embedded Studio（以下简称 SES）中，一个可执行工程并不是“把 .c 文件堆在一起”那么简单。它由三部分信息共同决定：参与编译的源文件集合、头文件的搜索路径、预处理宏定义。这三者决定了编译器“看到什么代码”，而编译与链接两个阶段则决定了这些代码最终如何变成可烧录的映像。理解这条链路，是排查“找不到头文件”“符号未定义”“宏没生效”等问题的前提。

一、源文件的添加与移除

SES 的工程树中，源文件按“组（Folder）”组织，但组只是逻辑分类，不改变文件在磁盘上的真实位置。添加源文件有两种典型方式：

• 添加已有文件：右键目标组 → Add Existing File…，选择磁盘上已存在的 .c/.s 文件。SES 默认以“引用”方式加入，即工程只记录路径，不复制文件。
• 新建文件：右键组 → Add New File…，指定文件名与保存目录，SES 会创建模板骨架并自动加入工程。

移除文件时，右键 → Remove File 只是把文件从工程树中移出，磁盘文件不会被删除；若想彻底删除，需在文件系统中另行操作。这一点在多人协作时尤其重要：误以为“移除即删除”会导致本地文件残留、版本库状态混乱。

需要特别区分的是：加入工程树 ≠ 参与编译。在 SES 中，每个文件节点都有 Options → Code → Generate 之类的属性，但更关键的是文件是否被包含在构建配置中。若某文件被标记为 Exclude from build，它会显示在工程树里，却不参与编译。排查“函数明明写了却报未定义”时，第一步就应确认该文件是否真的被编译。

二、头文件搜索路径配置

当代码中出现 #include "sensor.h" 时，编译器需要知道去哪里找这个文件。SES 的搜索路径在 Project Options → Preprocessor → User Include Directories 中配置，可填相对路径或绝对路径，多个路径用分号分隔。

搜索顺序遵循两条规则：

1. 对于 #include "xxx.h"（双引号），先在当前源文件所在目录查找，找不到再到用户包含路径中查找。
2. 对于 #include <xxx.h>（尖括号），直接到用户包含路径与系统包含路径中查找，不搜索当前目录。

因此，工程中常见的做法是：把公共头文件集中放在 inc/ 目录，把驱动头文件放在 drivers/xxx/ 下，然后在 User Include Directories 中统一登记这些目录。路径建议使用相对工程文件的写法（如 ../inc），这样工程整体移动或换机器时不会失效。

三、预处理器宏定义

宏定义在 Project Options → Preprocessor → Preprocessor Definitions 中配置，等价于在命令行传入 -D。例如填入 DEBUG=1、BOARD_V2，编译器在预处理阶段就会把这些符号展开。

宏的典型用途有三类：

• 条件编译：#ifdef BOARD_V2 选择不同硬件版本的驱动代码。
• 功能开关：#if LOG_LEVEL >= 2 控制日志输出粒度。
• 参数注入：-DCPU_FREQ=64000000 把频率作为编译期常量传入，避免运行时计算。

需要注意：宏定义是编译期生效的，修改宏后必须重新编译受影响的源文件，仅重新链接不会让宏生效。此外，宏名不要与头文件中的枚举、变量重名，否则会出现难以定位的替换错误。

四、编译与链接过程解析

SES 的构建过程可分为四个阶段，下图展示了从源文件到可执行映像的完整数据流，以及头文件路径与宏定义在其中的作用位置：

四个阶段的具体行为如下：

1. 预处理：处理所有以 # 开头的指令。把头文件内容原地插入，把宏替换为定义值，根据条件编译决定保留或删除代码块。此阶段只做文本操作，不检查语法。
2. 编译：对预处理后的单个翻译单元做词法、语法、语义分析，生成汇编，再汇编为目标文件 .o。每个 .c 文件独立编译，互不知道对方的存在。
3. 链接：把所有 .o 与库文件合并，解析跨文件的符号引用（如 main 调用 drv_init），分配最终地址，输出 .elf。
4. 格式转换：SES 可进一步调用 objcopy 把 .elf 转为 .hex 或 .bin，供烧录器使用。

理解这条链路后，常见报错就能快速定位：undefined reference to 'xxx' 属于链接阶段，说明符号声明了但没找到定义，通常是源文件未加入编译或库未链接；multiple definition of 'xxx' 也是链接错误，说明同一符号在多个 .o 中都有定义，常见于头文件中直接定义变量；而 expected ';' before '}' 属于编译阶段，与链接无关。

五、构建配置与增量编译

SES 允许为同一工程建立多个构建配置（如 Debug、Release），每个配置拥有独立的源文件集合、包含路径、宏定义和优化等级。切换配置后，SES 会依据文件时间戳与依赖关系决定哪些文件需要重新编译，这就是增量编译。若发现“改了头文件但行为没变”，可执行 Build → Rebuild 强制全量重建，排除依赖记录异常的可能。

综上，源文件决定“编译什么”，包含路径决定“去哪找头文件”，宏定义决定“编译成什么样”，而编译与链接则把这三者转化为最终映像。把这四件事在工程配置中一一对应清楚，是 SES 工程可维护、可复现的基础。