在GCC中跨翻译单元使用头文件仅声明未定义的inline函数问题

我正在将Windows MSVC开发的C代码迁移到Linux GCC环境，现有代码库存在大量不符合C标准的inline函数用法：仅在头文件声明inline函数，定义只放在单个.cxx文件中，却被其他翻译单元调用。原本以为GCC的链接时优化（-flto）能解决问题，但添加后仍报未定义引用错误，尝试各种extern组合也无效，且我无法修改现有代码架构，只能通过编译选项适配。

最小复现代码 #

func.hxx #

inline int func();

func.cxx #

#include "func.hxx"
inline int func()
{
    return 1;
}

main.cxx #

#include "func.hxx"

int main()
{
    return func();
}

编译错误信息 #

使用-flto编译时 #

执行命令：

gcc -fpermissive -std=c++17 -flto main.cxx func.cxx

报错输出：

In file included from main.cxx:1:
func.hxx:1:19: warning: inline function 'int func()' used but never defined
    1 | inline int func();
      |            ^~~~
/usr/bin/ld:  /tmp/ccuZDsOM.ltrans0.ltrans.o: in function 'main':
<artificial>:(.text+0x9): undefined reference to 'func()'
collect2: error: ld returned 1 exit status

不使用-flto编译时 #

执行命令：

gcc -fpermissive -std=c++17 main.cxx func.cxx

报错输出：

In file included from main.cxx:1:
func.hxx:1:19: warning: inline function 'int func()' used but never defined
    1 | inline int func();
      |            ^~~~
/usr/bin/ld:  /tmp/cc4x65H5v.o: in function 'main':
main.cxx:(.text+0x9): undefined reference to 'func()'
collect2: error: ld returned 1 exit status

可行的编译选项解决方案 #

方案1：为包含inline定义的TU添加-fkeep-inline-functions #

这个选项会强制GCC为标记为inline的函数生成外部可见的符号，即使编译器认为可以内联它。这样其他翻译单元调用时就能链接到该符号，同时不影响其他inline函数的内联优化。

分步编译命令示例：

# 编译定义inline函数的文件，添加-fkeep-inline-functions
gcc -fpermissive -std=c++17 -flto -c func.cxx -o func.o -fkeep-inline-functions
# 编译主文件并链接
gcc -fpermissive -std=c++17 -flto main.cxx func.o

如果是用Makefile，只需给对应源文件的编译规则加上该选项即可。

方案2：全局使用-fno-inline（简单但牺牲性能） #

这个选项会禁用所有函数的内联优化，强制所有inline函数生成外部符号，完全模拟MSVC对inline的处理逻辑（MSVC的inline仅作为编译器的内联建议，而非强制要求）。但代价是失去内联带来的性能提升。

编译命令示例：

gcc -fpermissive -std=c++17 -fno-inline main.cxx func.cxx

为什么-flto之前没用？ #

GCC的LTO需要每个使用inline函数的翻译单元都能看到函数定义，才能进行跨TU内联优化。而你的代码中，调用函数的TU只有inline声明没有定义，LTO无法找到函数体进行内联，自然会报未定义引用。加上-fkeep-inline-functions后，定义函数的TU会生成外部符号，LTO在链接阶段就能找到该符号，确保程序正常链接。

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