build-keil

Build a Keil MDK project

Applicable scenarios

• Project Profile specified in build_system: keil or if .uvprojx / .uvproj file exists in the workspace.
• The user wants to compile, rebuild, or confirm firmware artifacts for a Keil MDK project.
• The flashing or debugging process requires a new AXF（ELF）、HEX or BIN。
• It is necessary to confirm whether the Keil MDK environment is ready before compiling (UV4.exe, ARMCC/ARMCLANG).

Required inputs

• Workspace path or .uvprojx / .uvproj project file path, or an existing Project Profile。
• Optional build target name, UV4.exe path, and log output path.

Automatic detection

• On startup, the script automatically reuses the last successful profile in the project root directory .em_skill.json as default parameters (explicit parameters take precedence; there is no need to manually pass --resume）；--resume only used to assert that the cache must exist; if there is no cache, it exits with a non-zero code. If there is no cache or the user explicitly requests re-detection, the script automatically falls back to a normal scan.
• The script automatically searches common Keil MDK installation paths and environment variables (KEIL_ROOT、MDK_ROOT) to locate UV4.exe.
• Parse .uvprojx the Target list in the project file, extracting the chip model, output directory, and toolchain (ARMCC/ARMCLANG).
• If no target is specified, the first Target in the project is used by default.
• Search the output directory for AXF, HEX, and BIN artifacts, sorted by ELF > HEX > BIN .
• If multiple equally reasonable project files or targets exist, list the candidates instead of silently guessing.

Execution steps

1. First read references/usage.md, and confirm whether this is environment detection, project scanning, listing targets, or performing a compile.
2. For the common single-project, single-target scenario, prefer completing detection + compilation in one call:

   python scripts/keil_builder.py --detect --project <工程文件> --target <目标名>
   

   This starts the Python process only once, avoiding --detect → --list-targets → --build the overhead of three serial calls.
3. Only when interactive selection is needed (multiple project files or multiple targets require user confirmation) should --scan、--list-targets。
4. Read the script output's build results and artifact scan report, focusing on the preferred artifact (AXF/ELF > HEX > BIN), error/warning statistics, and failure classification.
5. Write the build target, artifact path, chip model, and toolchain information back to Project Profile, and hand it off to downstream skills when needed.

Failure triage

• When Keil MDK is not installed or UV4.exe is unavailable, return environment-missing。
• When the project file is corrupted, the target name is invalid, or compilation fails due to configuration issues, return project-config-error。
• When compilation appears to succeed but no flashable or debuggable artifact is found, return artifact-missing。
• When multiple equally reasonable project files or targets exist, and any choice is unsafe, return ambiguous-context。

Platform notes

• Keil MDK runs natively only on Windows, and UV4.exe command-line compilation requires a Windows environment.
• The bundled script can still perform project parsing (--list-targets), project scanning (--scan), and artifact scanning (--scan-artifacts) on non-Windows platforms, but the actual compilation will be blocked.
• Build logs may contain Chinese characters in GBK encoding; the script automatically tries multiple encodings.
• Artifact paths in the output should remain absolute paths, so that downstream flashing and debugging skills can reuse them directly.

Output conventions

After the script finishes executing, the following key information must be extracted and presented to the user:

• Build status (success/failure)
• Project file and target name
• Chip model and toolchain (e.g., STM32F103RC [ARMCC])
• Firmware size details (Code, RO-data, RW-data, ZI-data) and Flash/RAM summary
• Build duration
• Artifact list (AXF/HEX/BIN and file sizes)
• Error/warning statistics
• If failed: failure classification and log evidence

Example output format:

编译成功 ✅
  工程: Demo02.uvprojx → 目标: Demo02
  芯片: STM32F103RC | 工具链: ARMCC
  固件大小: Flash ≈ 3.2 KB  RAM ≈ 1.6 KB
  产物: Demo02.axf (518.9 KB), Demo02.hex (9.0 KB)
  编译耗时: 00:00:05

• Use artifact_path、artifact_kind、target_mcu and toolchain to update Project Profile。
• On success, recommend flash-keil、flash-openocd or debug-gdb-openocd。

Handoff relationships

• When the next step's intent is to flash the program to hardware, hand off the successful build result to flash-keil(using the Keil built-in debugger) or flash-openocd(using OpenOCD).
• When the next step requires symbol information or a debugging session, hand off the successful build result to debug-gdb-openocd。