CMake多子目录项目包含路径配置及项目结构优化咨询

一、实现<myproject/xxx.h>形式的头文件引用 #

要让代码可以用#include <myproject/logger.h>这种方式引用头文件，核心是让编译器能找到myproject命名空间目录，同时调整文件结构和CMake配置：

1. 调整文件结构 #

推荐采用大型C/C++项目的标准布局，将公开头文件与源文件分离：

root/
├── include/
│   └── myproject/
│       ├── helpers/
│       │   └── helper.h
│       └── logger.h
├── src/
│   ├── helpers/
│   │   └── helper.cpp
│   ├── logger.cpp
│   ├── main.cpp
│   └── CMakeLists.txt
└── CMakeLists.txt

• include/myproject/：存放所有公开头文件，用项目名作为命名空间目录，避免头文件命名冲突
• src/：存放源文件，结构与include目录对应，便于维护

2. 修改CMake配置 #

顶层CMakeLists.txt

cmake_minimum_required(VERSION 3.14)
project(
    myproject
    VERSION 1.0.0
    LANGUAGES CXX C
)

add_executable(${PROJECT_NAME})

# 把include目录加入公共包含路径，所有源文件均可继承此配置
target_include_directories(${PROJECT_NAME}
    PUBLIC
        ${PROJECT_SOURCE_DIR}/include
)

add_subdirectory(src)

src/CMakeLists.txt

target_sources(${PROJECT_NAME} PRIVATE 
    main.cpp
    logger.cpp
)

add_subdirectory(helpers)

src/helpers/CMakeLists.txt

target_sources(${PROJECT_NAME} PRIVATE 
    helper.cpp
)

3. 修改代码中的头文件引用 #

替换所有相对路径引用为命名空间形式：

• 原#include "../logger.h" → #include <myproject/logger.h>
• 原#include "helper.h"（如main.cpp中）→ #include <myproject/helpers/helper.h>

二、为什么之前的target_include_directories无效？ #

大概率是以下原因之一：

• 路径设置错误：未指向能找到myproject目录的父路径
• 作用域错误：使用PRIVATE而非PUBLIC，导致子目录源文件无法继承包含路径
• 时机错误：在add_subdirectory之后才添加包含路径，部分源文件已完成预处理配置

三、CMake最佳实践建议 #

• 优先使用target_*系列命令（如target_sources、target_include_directories），避免全局命令（如include_directories），作用域更清晰，不会污染其他目标
• 公开头文件与源文件分离，后续若要将项目打包为静态库/动态库，仅需修改顶层CMake为add_library即可，无需大幅调整结构
• 用项目名作为头文件命名空间目录，彻底避免与其他项目的头文件重名冲突

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