clion 依赖 cmake 配置而非文件系统结构来构建项目模型。新建头文件需在 cmakelists.txt 中通过 target_include_directories() 声明路径，并用 add_subdirectory() 管理子模块；glob 会导致 ide 功能失效，必须显式声明源文件并手动 reload 项目。
CLion 本身不管理项目结构，它只解析和响应 CMakeLists.txt 的声明。你看到的“项目树”是 CMake 构建系统告诉 CLion “哪些文件属于哪个目标”，而不是 CLion 自己扫描目录得出的结论。
为什么新建的 .h 文件在 CLion 里找不到？
因为 CMake 没有被告知这个头文件要被哪个 target 使用。即使文件物理存在、也在项目视图中显示，只要没在 CMakeLists.txt 中通过 target_include_directories() 或 include_directories() 声明路径，也没被 add_executable() / add_library() 的源文件列表引用，CLion 就无法建立符号索引。
- 常见错误现象：
#include "utils.h"报红，但文件确实在include/utils.h - 根本原因：缺少
target_include_directories(MyApp PUBLIC include)或类似声明 - 路径必须是相对于
CMAKE_SOURCE_DIR的相对路径（如include），不能写成${CMAKE_SOURCE_DIR}/include—— 后者在target_include_directories()中反而会破坏 IDE 的路径解析 - 如果头文件只供本 target 内部使用，用
PRIVATE；若要导出给依赖它的其他 target，才用PUBLIC或INTERFACE
如何让 CLion 正确识别子模块目录？
靠 add_subdirectory()，不是靠右键新建目录。CLion 的图形化操作只是创建文件系统路径，不会自动写入 CMake 配置。
- 在顶层
CMakeLists.txt中显式添加：add_subdirectory(drivers)、add_subdirectory(components/module_a) - 每个子目录下必须有自己的
CMakeLists.txt，且至少定义一个 target（哪怕只是空的add_library(dummy INTERFACE)） - 删除子目录后，务必手动删掉对应的
add_subdirectory()行，否则 CMake 配置失败，CLion 会卡在 “Loading CMake project…” 状态 - 修改完任何
CMakeLists.txt后，必须触发 Reload CMake Project（右键项目根目录 → Reload project，或点击右上角弹窗中的 Reload）
递归添加源文件时要注意什么？
file(GLOB_RECURSE SOURCES "src/*.cpp") 看起来省事，但在 CLion 中会导致增量构建失效和代码模型错乱。
- CLion 依赖 CMake 的 File API 获取准确的源文件列表；
GLOB是运行时求值，IDE 无法静态推导 - 新增一个
.cpp文件后，CLion 不会自动感知，必须手动 Reload，否则补全、跳转、重构都不可用 - 更可靠的做法是显式列出关键文件：
set(SOURCES src/main.cpp src/utils.cpp)，或用file(GLOB ...)+ 注释说明“仅用于快速原型，正式项目请显式维护” - 对 STM32 等嵌入式项目，常用模式是按目录分组：
file(GLOB CORE_SOURCES "Core/Src/*.c")，再统一传给add_executable()
最易被忽略的一点：CLion 的代码导航、补全、重命名等功能，全部依赖 CMake 解析后的 target 依赖图。一旦 target_include_directories() 路径写错、add_subdirectory() 漏写、或 CMake 缓存过期，这些功能就立刻降级为纯文本编辑器——而问题往往不报错，只“默默失效”。
