使用BigInt头文件的文件配置为何引发链接器错误？

问题背景 #

为避免标准整数类型溢出，实现生成前n个斐波那契数的函数时，从GitHub下载了BigInt头文件并放置在Ubuntu 22.04.4的/usr/include目录中。单.cpp文件编译运行无错误，但将斐波那契相关代码移至独立翻译单元后，触发了链接器多重定义错误。

复现代码 #

test.cpp #

#include "test_import.h"

int main() {}

test_import.h #

#ifndef TEST_IMPORT
#define TEST_IMPORT

#include <BigInt.hpp>

#endif

test_import.cpp #

#include "fibonacci.h"

链接错误信息 #

/usr/bin/ld: CMakeFiles/test.dir/test_import.cpp.o: in function bool std::__constant_string_p<char>(char const*)': /usr/include/BigInt.hpp:140: multiple definition of is_valid_number(std::__cxx11::basic_string<char, std::char_traits, std::allocator > const&)'; CMakeFiles/test.dir/test.cpp.o:/usr/include/BigInt.hpp:140: first defined here

环境与CMake配置 #

• 编译器：gcc (Ubuntu 11.4.0-1ubuntu1~22.04) 11.4.0
• CMakeLists.txt：

set(PROJECT_NAME chap8)
cmake_minimum_required(VERSION 3.22)
project(${PROJECT_NAME} VERSION 1.0)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

include_directories("/usr/include/boost_1_85_0") #adds boost library headers (most does not need to be built)

set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)

set(TARGET_NAME test) 
add_executable(${TARGET_NAME} "${TARGET_NAME}.cpp" "test_import.cpp") 


target_compile_options(${TARGET_NAME} PRIVATE 
    -std=c++17 
    -fexceptions 
    -Wall
    -g
    -Wmissing-declarations
)

问题原因 #

核心问题在于BigInt.hpp头文件中包含了函数的完整定义（实现代码），而非仅函数声明。当多个翻译单元（test.cpp、test_import.cpp，后者通过fibonacci.h间接包含BigInt.hpp）都引入这个头文件时，每个单元都会生成一份头文件中所有函数的副本。链接器合并目标文件时，发现同一个函数存在多份定义，因此触发多重定义错误。

单文件编译时只有一个翻译单元，不会出现重复定义；拆分到多单元后，重复实例化的函数副本就会引发冲突。

解决方案 #

方案1：分离头文件与实现文件 #

将BigInt.hpp中的函数实现（比如is_valid_number的函数体）提取到单独的BigInt.cpp文件，头文件中仅保留函数声明。编译时将BigInt.cpp加入项目，链接时就只会存在一份函数定义。

方案2：为头文件函数添加inline关键字 #

给BigInt.hpp中的所有函数定义添加inline修饰符。inline关键字允许多个翻译单元中存在同一函数的定义，链接器会自动合并这些副本，不会触发错误。注意：inline函数的定义必须在所有包含它的翻译单元中完全一致。

方案3：使用内部链接属性（不推荐） #

给头文件中的函数添加static关键字，或者将整个头文件内容放在匿名命名空间中。这样每个翻译单元中的函数都是独立的副本，不会产生链接冲突，但会增加可执行文件体积，不建议用于通用库。

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