From ed07d3659fae8cc14c2f04ba1f303662dd8d7a26 Mon Sep 17 00:00:00 2001 From: MoonFeather Date: Mon, 10 Nov 2025 16:30:07 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=20CMake=20=E6=94=AF=E6=8C=81?= =?UTF-8?q?=E4=BB=A5=E8=87=AA=E5=8A=A8=E6=9F=A5=E6=89=BE=E5=92=8C=E9=93=BE?= =?UTF-8?q?=E6=8E=A5=20rpl=20=E5=BA=93=EF=BC=8C=E5=B9=B6=E5=88=9B=E5=BB=BA?= =?UTF-8?q?=20CMake=20=E6=9E=84=E5=BB=BA=E8=AF=B4=E6=98=8E=E6=96=87?= =?UTF-8?q?=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: MoonFeather --- CMakeLists.txt | 2 + cmake/FindModules.cmake | 2 + cmake/Modules/FindRPL.cmake | 10 ++++ doc/CMake.md | 99 +++++++++++++++++++++++++++++++++++++ 4 files changed, 113 insertions(+) create mode 100644 cmake/FindModules.cmake create mode 100644 cmake/Modules/FindRPL.cmake create mode 100644 doc/CMake.md diff --git a/CMakeLists.txt b/CMakeLists.txt index b146c96..9b17923 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -43,6 +43,7 @@ message("Build type: ${CMAKE_BUILD_TYPE}") add_executable(${CMAKE_PROJECT_NAME}) include(CompileOptions) +include(FindModules) # Add STM32CubeMX generated sources add_subdirectory(cmake/stm32cubemx) @@ -50,6 +51,7 @@ add_subdirectory(cmake/stm32cubemx) # 添加链接库 target_link_libraries(${CMAKE_PROJECT_NAME} stm32cubemx + rpl::rpl ) file(GLOB_RECURSE USER_SOURCES "${PROJECT_SOURCE_DIR}/User_Code/*.c" "${PROJECT_SOURCE_DIR}/User_Code/*.cpp") diff --git a/cmake/FindModules.cmake b/cmake/FindModules.cmake new file mode 100644 index 0000000..7543dd5 --- /dev/null +++ b/cmake/FindModules.cmake @@ -0,0 +1,2 @@ +include(FetchContent) +include(Modules/FindRPL) \ No newline at end of file diff --git a/cmake/Modules/FindRPL.cmake b/cmake/Modules/FindRPL.cmake new file mode 100644 index 0000000..58ae31c --- /dev/null +++ b/cmake/Modules/FindRPL.cmake @@ -0,0 +1,10 @@ +find_package(rpl QUIET) + +if (NOT rpl_FOUND) + FetchContent_Declare( + rpl + GIT_REPOSITORY https://gitee.com/dlmu-cone/rpl + GIT_TAG main + ) + FetchContent_MakeAvailable(rpl) +endif () \ No newline at end of file diff --git a/doc/CMake.md b/doc/CMake.md new file mode 100644 index 0000000..1c406df --- /dev/null +++ b/doc/CMake.md @@ -0,0 +1,99 @@ +项目构建说明（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//` 下。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 ` 以刷新 CMake cache（Ninja incremental build 不会改变 configure 阶段的 glob 结果）； + - 如果希望不依赖 glob，可以手动在 `CMakeLists.txt` 里使用 `target_sources` 显式列出文件列表。