tronone-h7-scaffold/doc/CMake.md

项目构建说明（CMake）
=====================

本文档概述本仓库使用的 CMake 构建系统、主要配置项，以及对用户最相关的自动包含规则（特别是 `User_Code`
目录中的源文件与头文件）。目标读者是开发者或维护者，希望快速了解如何配置、构建以及把新代码加入工程。

快速概览
--------

- 构建系统：CMake >= 3.22，生成器默认使用 Ninja（参见 `CMakePresets.json`）。
- 预设（presets）：仓库提供 `Debug` 和 `Release` 两个 configure/build preset（见 `CMakePresets.json`）。
- 目标可执行文件名：由顶层 CMake 项目名（`TronOneH7_Scaffold`）创建一个可执行目标。
- 工具链：默认通过 `cmake/starm-clang.cmake` 指定交叉/宿主工具链（在 presets 中通过 `toolchainFile` 引用）。
- 自动包含：`User_Code` 目录下的所有 `.c`、`.cpp` 源文件会被递归搜集并添加到目标；同目录下的 `.h`、`.hpp` 头文件所在目录也会被自动加入目标的
  include 路径。

文件和关键配置点
----------------

- 顶层配置：`CMakeLists.txt`
    - 设置了 C/C++ 标准（C23, C++23）并启用 ASM 支持。
    - 导出 `compile_commands.json` 以便 clangd / IDE 索引（`set(CMAKE_EXPORT_COMPILE_COMMANDS TRUE)`）。
    - 根据 `CMAKE_BUILD_TYPE` 设置编译器的优化/调试选项（Debug/Release/RelWithDebInfo/MinSizeRel）。
    - 通过 `add_subdirectory(cmake/stm32cubemx)` 引入由 STM32CubeMX 生成的构建片段（包括启动文件、链接脚本、HAL 库设置等）。
    - 将 `stm32cubemx` 静态/目标库和 `rpl::rpl`（项目中的第三方或子模块库）链接到可执行目标。

- 预设：`CMakePresets.json`
    - `default` preset 指明生成器（Ninja）、二进制输出目录（`build/${presetName}`）与工具链文件。
    - `Debug`/`Release` preset 分别继承 `default` 并设置 `CMAKE_BUILD_TYPE`。
    - 构建命令示例（在仓库根目录运行）：

```sh
cmake --preset Debug
cmake --build --preset Debug
```

（Windows 下的 shell 为 cmd.exe，上面命令同样适用；若使用 VS Developer Prompt 或 PowerShell，可在相应环境中运行）

User_Code 的自动包含行为
----------------------
顶层 `CMakeLists.txt` 中有两段与 `User_Code` 有关的逻辑：

1. 自动收集源文件：

```cmake
file(GLOB_RECURSE USER_SOURCES "${PROJECT_SOURCE_DIR}/User_Code/*.c" "${PROJECT_SOURCE_DIR}/User_Code/*.cpp")

target_sources(${CMAKE_PROJECT_NAME} PRIVATE
        ${USER_SOURCES}
)
```

该逻辑会递归查找 `User_Code` 下所有 `.c` 和 `.cpp` 文件，并把它们加入到可执行目标中。开发者只要把源文件放在 `User_Code`
子目录（或其子目录）下，CMake 在下一次 configure 时会将其纳入构建。

2. 自动加入头文件目录：

```cmake
file(GLOB_RECURSE USER_HEADERS "${CMAKE_SOURCE_DIR}/User_Code/*.h" "${CMAKE_SOURCE_DIR}/User_Code/*.hpp")

foreach (header ${USER_HEADERS})
    get_filename_component(dir ${header} DIRECTORY)
    target_include_directories(${CMAKE_PROJECT_NAME} PRIVATE ${dir})
endforeach ()
```

这个片段会递归查找 `User_Code` 下的 `.h`/`.hpp` 文件，并将每个头文件所在的目录添加为目标的私有 include 目录。换句话说：

- 如果你的头文件位于 `User_Code/my_module/include/mymod.h`，该 `include` 目录会被自动添加到编译器的 include 路径中。
- 如果多个源/头文件位于同一目录，该目录只会被多次添加（可接受，但可通过改进避免重复，如需要我可以帮忙优化）。

如何添加/组织代码（建议）
------------------------

- 源文件：把 `.c`/`.cpp` 放在 `User_Code/<subdir>/` 下。CMake 会自动发现并编译。
- 头文件：把 `.h`/`.hpp` 放在与源文件同目录或子目录的 `include/` 目录中，CMake 会将头文件所在目录纳入 include 路径。
- 如果你想限制某些文件不被自动编译，可以：
    - 改名（例如添加后缀 `.inert`）或者
    - 将需要排除的文件放到项目外，或修改 `CMakeLists.txt` 来有选择性地添加源文件（我可以帮助你实现更精细的控制）。

拓展说明（链接库、工具链、CubeMX）
-----------------------------

- STM32CubeMX：`add_subdirectory(cmake/stm32cubemx)` 会把生成的 HAL/启动/链接脚本等加入工程，相关源通常在
  `cmake/stm32cubemx` 子项目中管理。
- 工具链：`CMakePresets.json` 中 `default` preset 指向 `cmake/starm-clang.cmake`。如果你使用不同编译器或调试器，请修改对应
  preset 的 `toolchainFile` 或在命令行提供 `-DCMAKE_TOOLCHAIN_FILE=...`。
- 第三方库：示例中 `rpl::rpl` 被链接到目标上；如果需要新增库，请在 `FindModules.cmake` 或 `cmake/Modules` 中添加查找逻辑，或直接使用
  `add_subdirectory` 引入并 `target_link_libraries`。

诊断与调试
---------

- 若 clangd / IDE 没有正确索引，请确认 `build/Debug/compile_commands.json`（或对应 preset 的 build 目录）存在。若不存在，请使用
  `cmake --preset Debug` 重新 configure。
- 若新加入的源文件未被编译：
    - 确认文件扩展名是 `.c` / `.cpp` 并放在 `User_Code` 子目录下；
    - 重新运行 `cmake --preset <preset>` 以刷新 CMake cache（Ninja incremental build 不会改变 configure 阶段的 glob 结果）；
    - 如果希望不依赖 glob，可以手动在 `CMakeLists.txt` 里使用 `target_sources` 显式列出文件列表。