AVR-GCC优化下extern全局常量数组出现未定义引用错误求助

环境信息 #

• Windows 11 x64
• PlatformIO
• AVR-GCC 11.1.0
• 目标MCU：ATmega128

问题现象 #

定义在.cpp文件命名空间内的const全局数组（无论是否带PROGMEM），链接阶段提示undefined reference to...错误。关闭编译器优化、禁用-flto均无效，仅为变量添加volatile可临时解决，但这不是合理方案。

相关代码 #

oled_basic_init_sequence.cpp #

#include <Arduino.h>

namespace oled_basic {

    const uint8_t _init_sequence_for_ssd1316_4_wire_spi[25] PROGMEM = {
        0xae, /*display off*/
        0x00, /*set lower column address*/
        // ... 省略其余初始化数据
    };

    const uint8_t _init_sequence_for_ssd1306_2_wire_i2c[23] PROGMEM = {
        0xAE,
        0xD5,
        // ... 省略其余初始化数据
    };

}  // namespace oled_basic

oled_basic_init_sequence.h #

#pragma once

#include <stdint.h>

namespace oled_basic {

    extern const uint8_t _init_sequence_for_ssd1316_4_wire_spi[25];

    extern const uint8_t _init_sequence_for_ssd1306_2_wire_i2c[23];

}  // namespace oled_basic

main.cpp #

#include <Arduino.h>

#include "oled_basic_init_sequence.h"

volatile uint8_t * test = 0;

void setup() {
    *test = oled_basic::_init_sequence_for_ssd1316_4_wire_spi[0];
    
    // 尝试用PROGMEM读取也无效
    *test = pgm_read_byte(&(oled_basic::_init_sequence_for_ssd1316_4_wire_spi[0]));
}

void loop() {

}

链接错误信息 #

Building in release mode
Compiling .pio\build\ATmega128\src\oled_basic_init_sequence.cpp.o
Linking .pio\build\ATmega128\firmware.elf
c:/users/xxxxx/.platformio/packages/toolchain-atmelavr/bin/../lib/gcc/avr/11.1.0/../../../../avr/bin/ld.exe: C:\Users\xxxxx\AppData\Local\Temp\ccelvOYl.ltrans0.ltrans.o: in function `main':
<artificial>:(.text.startup+0x5a): undefined reference to `_ZN10oled_basic37_init_sequence_for_ssd1316_4_wire_spiE'
collect2.exe: error: ld returned 1 exit status
*** [.pio\build\ATmega128\firmware.elf] Error 1

编译命令 #

avr-g++ -o .pio\build\ATmega128\firmware.elf -mmcu=atmega128 -Os -Wl,--gc-sections -flto -fuse-linker-plugin .pio\build\ATmega128\src\main.cpp.o .pio\build\ATmega128\src\oled_basic_font.cpp.o .pio\build\ATmega128\src\oled_basic_init_sequence.cpp.o -L.pio\build\ATmega128 -Wl,--start-group .pio\build\ATmega128\lib81f\libi2c.a .pio\build\ATmega128\lib685\libSPI.a .pio\build\ATmega128\libe29\libWire.a .pio\build\ATmega128\libFrameworkArduinoVariant.a .pio\build\ATmega128\libFrameworkArduino.a -lm -Wl,--end-group

原因分析 #

C++标准规定：全局作用域（包括命名空间内部）的const变量默认具有内部链接（等价于添加static修饰）。这意味着每个编译单元（.cpp文件）中的const变量都是独立的符号，不会被导出到目标文件的符号表中。头文件中的extern声明无法找到.cpp文件里的定义，因为后者的符号是内部可见的，最终导致链接错误。

添加volatile能临时解决，是因为它改变了编译器对变量的优化策略，强制保留符号，但这是治标不治本的方法。

解决方案 #

方案1：为.cpp中的定义添加extern，改为外部链接 #

修改oled_basic_init_sequence.cpp，在每个const数组定义前添加extern，覆盖默认的内部链接属性：

#include <Arduino.h>

namespace oled_basic {

    extern const uint8_t _init_sequence_for_ssd1316_4_wire_spi[25] PROGMEM = {
        0xae, /*display off*/
        0x00, /*set lower column address*/
        // ... 省略其余初始化数据
    };

    extern const uint8_t _init_sequence_for_ssd1306_2_wire_i2c[23] PROGMEM = {
        0xAE,
        0xD5,
        // ... 省略其余初始化数据
    };

}  // namespace oled_basic

方案2：使用C++17 inline变量（推荐） #

如果项目支持C++17（在PlatformIO的platformio.ini中添加build_flags = -std=c++17），可以直接在头文件中定义inline变量，无需分开声明和定义：
修改oled_basic_init_sequence.h：

#pragma once

#include <stdint.h>
#include <Arduino.h>

namespace oled_basic {

    inline const uint8_t _init_sequence_for_ssd1316_4_wire_spi[25] PROGMEM = {
        0xae, /*display off*/
        0x00, /*set lower column address*/
        // ... 省略其余初始化数据
    };

    inline const uint8_t _init_sequence_for_ssd1306_2_wire_i2c[23] PROGMEM = {
        0xAE,
        0xD5,
        // ... 省略其余初始化数据
    };

}  // namespace oled_basic

之后可以删除oled_basic_init_sequence.cpp中的对应定义，inline保证变量在多个编译单元中只会生成一个实例，同时符号对外可见。

方案3：使用编译器属性强制保留符号（不推荐） #

在.cpp文件的const数组定义后添加__attribute__((used))，告诉编译器不要优化删除该符号：

#include <Arduino.h>

namespace oled_basic {

    const uint8_t _init_sequence_for_ssd1316_4_wire_spi[25] PROGMEM __attribute__((used)) = {
        0xae, /*display off*/
        0x00, /*set lower column address*/
        // ... 省略其余初始化数据
    };

    const uint8_t _init_sequence_for_ssd1306_2_wire_i2c[23] PROGMEM __attribute__((used)) = {
        0xAE,
        0xD5,
        // ... 省略其余初始化数据
    };

}  // namespace oled_basic

此方案依赖AVR-GCC的编译器属性，不具备跨编译器兼容性，仅作为临时替代方案。

内容的提问来源于stack exchange，提问作者ke_bitter