whole-archive与gc-sections

在嵌入式系统开发中，--whole-archive 和 --gc-sections 是链接器（ld）的两个关键选项，它们的组合使用对最终二进制文件的构成有决定性影响。下面从原理和实际示例详细说明：

一、基础原理

1. --whole-archive

作用机制：

• 强制链接器处理静态库（.a文件）时，包含库中所有目标文件（.o文件）
• 覆盖默认的"仅包含被引用目标文件"的行为
• 作用范围：从出现位置开始，直到遇到--no-whole-archive

典型问题解决：

// 在libdrivers.a中的uart_init.c
__attribute__((section(".init"))) void uart_init() {
    // 硬件初始化代码
}

如果没有--whole-archive，这个初始化函数可能因为没有被显式调用而被丢弃。

2. --gc-sections

作用机制：

• 在目标文件已加载的基础上，进行节区(Section)级别的垃圾回收
• 仅保留被直接或间接引用的节区
• 依赖编译时添加-ffunction-sections -fdata-sections选项

优化效果：

// 在已加载的目标文件中
void used_func() {}  // 会被保留
static void unused_func() {}  // 会被清除

---

二、组合使用的工作流程

1. 完整处理链条

--whole-archive --gc-sections 未引用 静态库.a文件 加载所有.o文件 节区分析 保留被引用节区 丢弃无用节区

2. 实际示例对比

假设有以下代码结构：

libembedded.a
├── uart.o      # 包含硬件初始化代码
├── timer.o     # 包含定时器驱动
└── unused.o    # 包含废弃代码

链接选项组合	结果分析
仅用默认链接	可能丢失uart.o中的初始化代码，因为无显式调用
仅用--whole-archive	包含所有.o文件，但未使用的函数/变量也会保留，增大固件体积
仅用--gc-sections	可能因目标文件未被加载而丢失关键代码
两者结合	确保所有.o被加载，同时清除.o内未被引用的节区，完美平衡可靠性和体积优化

---

三、CMake配置中的体现

# 确保关键库的所有目标文件被加载
-Wl,--whole-archive
$<LINK_ONLY:platform>
-Wl,--no-whole-archive

# 在全局进行节区优化
-Wl,--gc-sections

典型场景解析：

1. 平台初始化代码保留：

// 在platform库中
__attribute__((constructor)) void platform_early_init() {
// 时钟/内存控制器初始化
}

• --whole-archive确保包含platform库的所有.o
• --gc-sections清除其中未被调用的辅助函数

2. 驱动注册机制：

// 在bsp库中
struct driver uart_driver = {...};
void __register_driver() __attribute__((section(".init")));

即使没有显式调用__register_driver，组合使用也能确保其被包含。

---

四、开发建议

1. 调试技巧：

# 查看被丢弃的节区
arm-none-eabi-nm --print-armap -l -n oneos.elf | grep '^ '

# 查看链接映射(需配合-Map选项)
grep "Memory Configuration" oneos.map

2. 关键编译选项补充：

# 建议在编译选项中添加（如果尚未存在）
add_compile_options(
    -ffunction-sections  # 让每个函数独立节区
    -fdata-sections      # 让每个全局变量独立节区
)

这种组合是嵌入式开发的黄金标准，既保证了系统关键代码的可靠性，又实现了最优的代码体积优化。