一种可复用的 STM32 工程组织方式：目录、构建与 Agent 新建模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

<project>/
├── <project>.ioc                 # CubeMX 硬件配置
├── CMakeLists.txt                # 根工程、唯一固件可执行目标
├── CMakePresets.json             # 构建配置与输出目录
├── startup_<mcu>.s               # 启动文件
├── <mcu>_FLASH.ld                # Flash/RAM 布局
├── README.md                     # 从打开工程到操作任务的说明
│
├── .vscode/
│   ├── settings.json             # CMake、STM32、代码索引设置
│   └── tasks.json                # 用户操作菜单
├── .settings/                    # STM32 扩展设备与工具链元数据
│
├── Core/
│   ├── Inc/                      # 平台接口、HAL 配置、外设头文件
│   └── Src/                      # main、初始化、IRQ、MSP、系统代码
├── Drivers/
│   ├── CMSIS/
│   └── STM32<family>xx_HAL_Driver/
│
├── App/
│   ├── CMakeLists.txt             # 汇总应用模块
│   ├── Config/
│   ├── Measurement/
│   ├── Control/
│   ├── Hardware/
│   └── Display/
│       └── <Module>/
│           ├── CMakeLists.txt
│           ├── Inc/
│           └── Src/
│
├── cmake/
│   ├── gcc-arm-none-eabi.cmake    # 工具链与目标架构参数
│   └── stm32cubemx/
│       └── CMakeLists.txt         # Core、HAL、宏、包含路径的构建清单
├── tools/
│   ├── <workflow>.ps1            # 构建、下载、工作台等操作实现
│   ├── verify_*.ps1              # 可重复执行的检查
│   └── web_workbenches/          # 配套网页（需要时保留）
├── tests/
│   └── host/                     # 独立配置的主机测试工程
├── design/                       # 设计资料
├── verification/                 # 验证记录
└── build/                        # 构建输出，排除在源码版本控制之外

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

cmake_minimum_required(VERSION 3.22)

set(CMAKE_C_STANDARD 11)
set(CMAKE_C_STANDARD_REQUIRED ON)
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

project(my_stm32_project LANGUAGES C ASM)

# 根目录拥有固件可执行目标。
add_executable(${CMAKE_PROJECT_NAME})

# 子目录补充平台源码和应用库。
add_subdirectory(cmake/stm32cubemx)
add_subdirectory(App)

target_link_libraries(${CMAKE_PROJECT_NAME}
    stm32cubemx
    app
)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

my_stm32_project          Executable
STM32_Drivers            Object library
adc_acquisition          Static library
analog_sample_conversion Static library
chopper_pwm_output       Static library
chopper_runtime          Static library
open_loop_chopper        Static library
open_loop_power_map      Static library
workbench_protocol       Static library
uart_transport           Static library
ssd1306                  Static library
stm32_hal_i2c_adapter    Static library
oled_pwm_mirror          Static library

1
2
3
4
5
6
7
8

# App/Measurement/AnalogSampleConversion/CMakeLists.txt
add_library(analog_sample_conversion STATIC
    Src/analog_sample_conversion.c
)

target_include_directories(analog_sample_conversion PUBLIC
    ${CMAKE_CURRENT_SOURCE_DIR}/Inc
)

1
2
3
4
5

# App/CMakeLists.txt：只展示一个模块的最小示例
add_subdirectory(Measurement/AnalogSampleConversion)

add_library(app INTERFACE)
target_link_libraries(app INTERFACE analog_sample_conversion)

1
2
3
4
5

打开工程根目录
    → Terminal / Run Task
    → 选择任务和动作
    → tools 中的脚本执行
    → build 中生成对应配置的产物

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

请按以下目录与构建约定，新建一个 STM32 单固件工程。

新工程目录：<目标绝对路径>
工程名称：<工程名>
目标板和芯片：<开发板、MCU 完整型号>
本次功能范围：<例如 UART 回显，或复用指定的控制与测量模块>
可复用代码路径（可选）：<已有模块的绝对路径；没有则填无>

请先检查目标目录、已安装工具和提供的可复用代码，然后实施。
以下约定同时约束目录布局、CMake 目标归属和 VSCode 操作流程。

结构要求：
1. 新工程目录就是 VSCode 打开的工程根目录。
2. 根目录直接包含 .ioc、CMakeLists.txt、CMakePresets.json、
   启动文件、链接脚本、README、.vscode 和所需的 STM32 元数据。
3. Core/Inc、Core/Src、Drivers、App、cmake、tools、tests
   直接位于工程根目录；配套网页放在 tools/web_workbenches。
4. 不增加 firmware 包装层，不要求用户打开内部子目录。

构建要求：
5. 固件的 project() 和 add_executable() 在根 CMakeLists.txt 中。
6. 由 cmake/stm32cubemx 提供平台源码和依赖，HAL/系统代码形成
   STM32_Drivers 等对象库。App 的实际功能模块形成独立静态库，
   根可执行目标链接这些库；不要把全部 App/Core/Drivers 源码
   直接塞进 Executable，也不要在子目录创建第二个固件入口。
   优先复用已有模块 CMakeLists.txt，按目标芯片调整真实依赖。
   不创建空库装饰 Outline，不重复编译源码，不机械引入旧芯片模块。
   CPU/FPU 参数、平台宏和头文件路径要正确作用到相关库目标。
7. 主机测试单独配置，不接入 ARM 固件构建树。
8. 使用根目录 Presets，输出到 build/<配置>；生成 ELF 和 HEX。

复用和操作要求：
9. 保留适用的业务模块，优先调整平台接口，不改变控制与协议语义。
   若目标是完整控制应用，通信、ADC、PWM 的迁移均服务于完整应用，
   不把整体目标缩减为通信验证。
   若已有 firmware_identity/firmware_candidate 等身份和网页打包流程，
   保留其功能与依赖顺序，把生成头文件依赖挂到实际使用它的模块。
10. 使用目标芯片对应的启动文件、链接脚本、HAL/CMSIS、时钟和引脚。
    明确生成文件与项目维护文件的边界。
11. 用户从根目录 VSCode 任务菜单操作。不要让用户通过多 CMake
    项目选择来完成日常构建、下载或打开配套网页。
12. 不复制原工程的 build、缓存、旧产物、机器绝对路径或凭据。
13. 如果目标目录已有未提交改动，保留它们，不覆盖或混入本次提交。

交付与验证：
14. 给出最终目录树、实际 CMake 目标清单及依赖关系，说明各模块职责。
15. 执行适用的配置、固件构建和主机检查，报告真实结果与产物位置。
16. 检查 CMake File API：唯一固件可执行目标归属根目录；
    功能模块确实是 STATIC_LIBRARY，平台目标采用 OBJECT_LIBRARY 等
    合适类型，源码归属正确。确认生成身份及打包依赖未被破坏。
17. 重新打开 VSCode，分别检查：
    Project Setup 只有一个预期工程入口；
    Project Outline 可见实际功能静态库与平台对象库，能够展开模块源码。
    若无法操作 GUI，明确记录该项未执行，不用静态检查代替。
18. README 写清楚打开哪个目录、运行哪个任务、输出在哪里。
19. 编译成功与上板验证分开报告；下载、复位和硬件操作按已授权范围执行。

请按上述模板完成，不要另行设计目录层级。
若芯片工具确实要求偏离模板，请指出具体原因和最小差异。