如何验证C++库主头文件已包含所有子头文件？

项目结构 #

├── CMakeLists.txt
├── include/
│   ├── lib.hpp
│   └── lib/
│       ├── a.hpp
│       ├── b.hpp
│       └── c.hpp
├── test/

我们使用CMake构建系统，所有头文件通过#pragma once实现重复包含防护，要求include/lib.hpp必须包含include/lib/目录下的所有.hpp文件，需要实现自动化检查，确保新增子头文件时不会遗漏在主头文件中包含，且能在持续集成流程中触发检查。

1. 直接包含的验证方案 #

核心思路 #

编写一个仅包含主头文件lib.hpp的测试源文件，尝试引用每个子头文件中的唯一标识符（如类名、全局常量、函数声明等）。如果某个子头文件未被lib.hpp直接包含，编译器会抛出未定义标识符的错误。

具体实现 #

在test/目录下创建test_all_included.cpp：

#include <lib.hpp>

int main() {
    // 引用a.hpp中的唯一实体（示例：假设存在类A）
    [[maybe_unused]] A a_instance;
    // 引用b.hpp中的唯一实体（示例：假设存在函数func_b）
    [[maybe_unused]] auto func_b_ptr = &func_b;
    // 引用c.hpp中的唯一实体（示例：假设存在常量C_CONST）
    [[maybe_unused]] int c_const_val = C_CONST;
    return 0;
}

注：如果子头文件没有公开的可引用实体，可以在每个子头文件中添加测试专用标记：

// 在a.hpp中添加
inline constexpr bool TEST_MARKER_A = true;

之后在测试文件中引用TEST_MARKER_A即可。

CMake集成 #

在CMakeLists.txt中添加测试目标：

add_executable(test_all_included test/test_all_included.cpp)
target_include_directories(test_all_included PRIVATE include/)
add_test(NAME test_all_included COMMAND test_all_included)

构建时只要有子头文件未被lib.hpp包含，编译该测试程序就会失败，CI流程会直接触发报错。

2. 自动生成验证代码（进阶方案） #

如果子头文件数量多或频繁新增，可通过CMake自动生成测试代码，避免手动维护测试文件：

CMake脚本实现 #

在CMakeLists.txt中添加：

# 收集lib/目录下所有.hpp文件
file(GLOB LIB_SUB_HEADERS include/lib/*.hpp)

# 生成自动测试代码文件
set(TEST_FILE ${CMAKE_BINARY_DIR}/generated_test_all_included.cpp)
file(WRITE ${TEST_FILE} "#include <lib.hpp>\n\nint main() {\n")

foreach(HEADER ${LIB_SUB_HEADERS})
    # 提取文件名（不含路径和后缀），例如a.hpp -> a
    get_filename_component(HEADER_NAME ${HEADER} NAME_WE)
    # 引用对应头文件的测试标记
    file(APPEND ${TEST_FILE} "    [[maybe_unused]] bool marker_${HEADER_NAME} = TEST_MARKER_${HEADER_NAME};\n")
endforeach()

file(APPEND ${TEST_FILE} "    return 0;\n}")

# 添加测试目标
add_executable(test_all_included ${TEST_FILE})
target_include_directories(test_all_included PRIVATE include/)
add_test(NAME test_all_included COMMAND test_all_included)

同时要求每个lib/下的子头文件添加对应测试标记：

// a.hpp
#pragma once
inline constexpr bool TEST_MARKER_a = true;
// 其他业务代码...

新增子头文件时，只需添加对应的TEST_MARKER_xxx，CMake会自动生成测试代码并检查是否被lib.hpp包含。

3. 间接包含的验证思路 #

如果需要验证间接包含（例如a.hpp包含b.hpp，lib.hpp仅包含a.hpp也算符合要求），可借助编译器预处理器输出：

1. 编译仅包含lib.hpp的文件，生成预处理器输出：

   g++ -E include/lib.hpp -o lib_preprocessed.txt
   

2. 编写脚本检查所有子头文件的路径是否出现在预处理器输出中。
3. 将该脚本加入CI流程作为检查步骤。

该方法需要处理预处理器输出的路径格式问题，复杂度较高，一般优先采用直接包含的验证方案。

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