build-makefile

构建 Makefile 工程

适用场景

• Project Profile 中标明 build_system: makefile。
• 工作区存在 Makefile / makefile / GNUmakefile，但没有 CMakeLists.txt、platformio.ini、.uvprojx 或 .ewp。
• 用户希望对裸 Makefile MCU 工程执行编译或确认固件产物。
• 烧录或调试流程需要新的 ELF、HEX 或 BIN。

必要输入

• 工作区路径，或一份已有的 Project Profile。
• 可选的 make 目标名、额外变量（如 CROSS_COMPILE、MCU）、make 标志和并行任务数。

自动探测

• 若工作区根目录存在 Makefile / makefile / GNUmakefile，脚本自动识别。
• 解析 Makefile 变量：CROSS_COMPILE、CC、TARGET、MCU、BOARD、CFLAGS、LDFLAGS 等。
• 从 CROSS_COMPILE 前缀推断工具链家族（arm-none-eabi- → gnu-arm，riscv32-unknown-elf- → gnu-riscv，xtensa-esp32-elf- → gnu-esp）。
• 从 MCU 变量、-mcpu= 标志或链接脚本名推断目标芯片。
• 检测 make / gmake / mingw32-make 是否可用。
• 若 Makefile 包含 # Generated by CMake，提示用户使用 build-cmake skill。

执行步骤

1. 先阅读 references/usage.md，确认本次是环境探测、解析 Makefile、列出目标、执行构建，还是仅扫描产物。
2. 若不确定环境是否就绪，先运行自带脚本 scripts/makefile_builder.py 的 --detect 模式确认。
3. 运行 --parse-makefile 检查解析出的变量和工具链信息，确认目标芯片和编译器。
4. 若需查看可用目标，运行 --list-targets。
5. 使用 --source 运行构建，按需指定 --target、--clean、--extra-args 和 -j。
6. 读取脚本输出的构建结果和产物扫描报告，将产物路径写回 Project Profile 并交给下游 skill。

失败分流

• 当缺少 make 或交叉编译器时，返回 environment-missing。
• 当 Makefile 语法错误、链接失败或目标名无效时，返回 project-config-error。
• 当构建成功但未在源目录及 build/、output/、out/ 中找到可烧录产物时，返回 artifact-missing。
• 当工作区存在多个顶层 Makefile 且意图不明确时，返回 ambiguous-context。

平台说明

• Linux / macOS 上 make 通常已预装。
• Windows 上需要 MSYS2、MinGW 或 WSL 提供 make。脚本会依次尝试 make、gmake、mingw32-make。
• 输出中的构建目录应保持为绝对路径，方便下游烧录和调试 skill 直接复用。

输出约定

• 输出构建命令、构建目录、解析的工具链信息和首选产物路径。
• 用 artifact_path、artifact_kind、toolchain 和 target_mcu 更新 Project Profile。
• 成功后推荐 flash-openocd、flash-jlink 或 debug-gdb-openocd。

交接关系

• 当下一步意图是给硬件烧录程序时，将成功构建结果交给 flash-openocd 或 flash-jlink。
• 当下一步需要符号信息或调试会话时，将成功构建结果交给 debug-gdb-openocd 或 debug-jlink。