C++合并头文件布局下如何禁止跨库引用其他库的私有头文件

按优先级从高到低排列，优先从根源规避问题，再用工具兜底：

1. CMake层面从路径配置上限制（最优方案） #

大部分违规引用的根源是头文件搜索路径配置不规范，完全可以在编译期就杜绝绝大多数问题：

• 每个库的头文件搜索路径严格区分PRIVATE和INTERFACE属性：

  # 以libB的CMake配置为例
  target_include_directories(libB
    # 仅libB自身编译时可搜索src/libB目录，能直接引用内部头
    PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}
    # 依赖libB的目标仅能搜索src目录，引用必须带libB/前缀，无法直接引用libB目录下的内部头
    INTERFACE $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/..>
    INTERFACE $<INSTALL_INTERFACE:include>
  )
  

• 明确指定库的公开头列表，安装时仅安装公开头，所有带-internal.h后缀的私有头完全不进入安装目录：

  set_target_properties(libB PROPERTIES
    PUBLIC_HEADER B.h # 仅列出对外公开的头文件
  )
  install(TARGETS libB PUBLIC_HEADER DESTINATION include/libB)
  

2. clang-tidy检查兜底 #

如果因为历史问题没法改CMake配置，可以用clang-tidy做编译期检查：

• Clang 15及以上版本自带include-cleaner功能，可以为每个库配置公开头白名单，将*-internal.h、details/目录下的头标记为库内部私有，跨库引用直接抛出编译错误。
• 也可以自定义正则匹配规则：所有#include指令命中\w+-internal.h或/details/格式，且引用路径前缀和当前文件所属库名不一致时，直接判定违规。

3. CI阶段轻量脚本检查 #

实现成本最低的兜底方案，在CI流水线最前置位置运行，不用等编译完成就能拦阻违规提交：

• 遍历所有.h、.cpp文件，提取所有#include路径，按两条规则校验：
  • 引用路径包含-internal.h时，路径前缀必须和当前文件所属库名一致
  • 引用路径包含/details/时，路径前缀必须和当前文件所属库名一致
• 不符合规则直接阻断CI流程，通知提交人修改。

4. include-what-you-use（IWYU）支持 #

IWYU确实支持这类引用规则检查，你可以为每个库配置头文件映射规则，仅允许外部引用库约定的公开头，不符合映射规则的引用会直接报错。

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