clangd集成

.clangd

@@ -0,0 +1,7 @@
+# clangd 配置：指向 CMake 导出的编译数据库。
+# 前提：配置时带 -DCMAKE_EXPORT_COMPILE_COMMANDS=ON（或用 CMakePresets，
+# 已默认打开），生成 build/compile_commands.json。
+# 若用 preset 构建（binaryDir = build/<preset名>），把下行改成对应目录，
+# 例如 CompilationDatabase: build/dev。
+CompileFlags:
+  CompilationDatabase: build

CMakeLists.txt

@@ -12,6 +12,15 @@ cmake_minimum_required(VERSION 3.30)
 # 它只是元数据——发版时同步到最新 tag，实际版本以 git tag / gh release 为准）
 project(neuralnet.cpp VERSION 1.13.0 LANGUAGES CXX)
 
+# ── IDE / clangd：导出 compile_commands.json（仅顶层工程时）───────────────
+# include 路径（include/ + extern/*/include + build/generated）全部来自
+# target_include_directories，clangd 没有编译数据库就解析不到
+# <neuralnet.cpp/xxx.hpp>。Ninja/Makefile 生成器有效，MSVC/Xcode 忽略；
+# 嵌入消费方是否导出由其顶层工程决定，这里不越权。
+if(PROJECT_IS_TOP_LEVEL)
+    set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+endif()
+
 # ══════════════════════════════════════════════════════════════════════════
 #  作为库被消费（add_subdirectory / FetchContent 嵌入 3rd_party）的门控
 # ══════════════════════════════════════════════════════════════════════════

docs/development/01-cmake-integration.md

@@ -188,6 +188,16 @@ tokenizer_infer,dataset_gen,dataset_convert}`，另有 `layer_bench`（性能）
 **已知构建坑**：链接报 `permission denied`（`build/` 下 exe 正在运行被占用 → 构建中止）
 → 追加 `-- -k 0` 让 ninja 跳过失败目标继续建其余目标（被占用目标仍需关掉进程后重链）。
 
+### IDE（clangd）如何解析 `<neuralnet.cpp/xxx.hpp>`
+
+include 路径全部来自 `target_include_directories`（`include/` + `extern/*/include` +
+`build/generated`），clangd 必须拿到编译数据库才能解析。顶层配置时 CMake 自动
+导出 `build/compile_commands.json`（`CMAKE_EXPORT_COMPILE_COMMANDS`，仅 Ninja/Makefile
+生成器有效）；仓库根的 `.clangd` 已指向 `build/`，clangd 打开任意头/源文件即可。
+用 preset 构建时编译数据库在 `build/<preset名>/`，把 `.clangd` 的
+`CompilationDatabase` 改成对应目录（或传 `--compile-commands-dir`）。
+改完 CMake 后记得重新 configure 一次，让数据库里的 `-I` 与目标保持同步。
+
 ---
 
 ## 8. 编译耗时

scripts/doc_audit.py

@@ -47,6 +47,8 @@
     '--test-dir', '--parallel', '--target-env', '--dtype', '--adam-eps', '--device',
     '--task', '--compress', '--list', '--image', '--list-backends', '--summary', '--include',
     '--preset', '--workflow', '--list-presets', '--output-on-failure',
+    # clangd 自带选项（IDE 集成文档用）：clangd --compile-commands-dir <build>
+    '--compile-commands-dir',
     # git 自带选项（文档命令用）：git clang-format --diff / clone --recurse-submodules / tag --tags
     '--diff', '--recurse-submodules', '--tags',
 }