如何将C++多文件源码合并生成单header-only的hpp库文件

生成类似Catch2的单hpp发布文件，核心逻辑就是按规则拼接src目录下的声明、实现代码，处理好头文件保护、重复定义、引用关系几个问题即可，完全可以通过Makefile配合系统自带的文本处理命令实现，不需要依赖第三方工具。

核心约定 #

开发阶段先统一代码规则，减少后续拼接的处理成本：

• src目录下的.h文件只放声明，使用#pragma once做头文件保护（比传统的#ifndef宏更容易过滤），只include标准库/第三方依赖头文件，不要写非inline的函数实现
• src目录下的.cpp文件只放实现，开头include对应的本地.h文件即可，不需要额外加头文件保护
• 文件名按依赖顺序命名，比如被依赖的模块文件名字典序更靠前，保证拼接后声明在前、实现在后，不会出现编译时找不到声明的问题

Makefile实现逻辑 #

三个构建目标的核心处理逻辑如下：

• make library：按固定格式拼接所有源码生成最终的library.hpp
• make tests：先触发library生成，再编译test目录下的代码，编译时开启实现宏，运行测试用例
• make console：先触发library生成，再编译console_app目录下的代码生成可执行文件

可直接复用的Makefile示例 #

CXX ?= g++
CXXFLAGS ?= -std=c++17 -Wall -Wextra
SRC_DIR = src
TEST_DIR = tests
CONSOLE_DIR = console_app
OUT_LIB = library.hpp

# 收集源码文件，排序保证拼接顺序稳定
HEADERS = $(sort $(wildcard $(SRC_DIR)/*.h))
SRCS = $(sort $(wildcard $(SRC_DIR)/*.cpp))

.PHONY: library tests console clean

library: $(OUT_LIB)

$(OUT_LIB): $(HEADERS) $(SRCS)
	@echo "Generating single header library..."
	# 写入头文件保护开头
	@echo "#ifndef MY_LIBRARY_HPP" > $@
	@echo "#define MY_LIBRARY_HPP" >> $@
	@echo "" >> $@
	# 拼接所有头文件内容，过滤掉开发阶段用的#pragma once
	@for header in $(HEADERS); do \
		echo "// ====== $$(basename $$header) ======" >> $@; \
		sed '/^#pragma once$$/d' $$header >> $@; \
		echo "" >> $@; \
	done
	# 加入实现开关宏，和Catch2逻辑一致：用户只在一个编译单元定义宏开启实现
	@echo "#ifdef MY_LIBRARY_IMPLEMENTATION" >> $@
	# 拼接所有cpp实现，过滤掉对本地.h的include（前面已经拼过声明）
	@for src in $(SRCS); do \
		echo "// ====== $$(basename $$src) ======" >> $@; \
		sed '/^#include ".*\.h"$$/d' $$src >> $@; \
		echo "" >> $@; \
	done
	# 闭合宏和头文件保护
	@echo "#endif // MY_LIBRARY_IMPLEMENTATION" >> $@
	@echo "#endif // MY_LIBRARY_HPP" >> $@
	@echo "Generate done: $(OUT_LIB)"

tests: library
	@echo "Building tests..."
	@$(CXX) $(CXXFLAGS) -DMY_LIBRARY_IMPLEMENTATION $(TEST_DIR)/*.cpp -o test_runner
	@echo "Running tests..."
	@./test_runner
	@rm -f test_runner

console: library
	@echo "Building console app..."
	@$(CXX) $(CXXFLAGS) -DMY_LIBRARY_IMPLEMENTATION $(CONSOLE_DIR)/main.cpp -o console_app_bin
	@echo "Build done: ./console_app_bin"

clean:
	@rm -f $(OUT_LIB) test_runner console_app_bin

注意事项 #

• 上面的实现用了和Catch2一致的实现开关宏设计：用户使用库的时候，只需要在一个.cpp文件里先定义#define MY_LIBRARY_IMPLEMENTATION再include你的library.hpp，其他文件直接include即可，不会出现多编译单元重复定义的问题，比纯全inline的header-only编译速度更快。
• 如果不需要宏开关，想做到include直接用，删掉Makefile里宏开关相关的两行即可，但是要给所有类外定义的自由函数、类外实现的成员函数加上inline修饰，否则链接阶段会报重复定义错误。
• 如果模块间有严格的依赖顺序，不要完全依赖sort排序，可以手动给HEADERS和SRCS变量赋值按顺序写文件路径，保证依赖的模块先被拼接。
• 如果需要做注释精简、代码压缩，可以在拼接步骤里加sed命令删掉多余的空行、注释，小型库没必要做这步，保留源码注释反而方便使用者调试。

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