Building CMake Projects

Applicable Scenarios

```
Project Profile
```
indicates
```
build_system: cmake
```
.
Users want to configure, recompile, or confirm firmware artifacts for CMake MCU projects.
The flashing or debugging process requires new
```
ELF
```
,
```
HEX
```
, or
```
BIN
```
files.
Need to confirm if the environment is ready before building (cmake, generator, toolchain).

Workspace path, or an existing
```
Project Profile
```
.
Optional build presets, build directory, target name, generator, build type, and toolchain file.

If
```
CMakePresets.json
```
exists, prioritize using the script's
```
--list-presets
```
to list and select presets.
Otherwise, check
```
CMakeLists.txt
```
, existing build directories, and toolchain files.
If there is an existing successful build directory that matches the current intent, reuse it first.
The generator is automatically detected by the script, prioritizing
```
Ninja
```
, followed by the Make tool installed on the host machine.
For debugging-oriented requests,
```
Debug
```
is used by default; otherwise,
```
RelWithDebInfo
```
is the default.

First read references/usage.md to confirm whether this is environment detection, listing presets, executing a build, or just scanning artifacts.
If unsure whether the environment is ready, first run the built-in script scripts/cmake_builder.py in
```
--detect
```
mode to confirm.
If CMakePresets.json exists, use
```
--list-presets
```
to list presets, then use
```
--preset <name>
```
to build.
If no presets exist, manually configure the build using
```
--source
```
,
```
--build-dir
```
,
```
--generator
```
,
```
--build-type
```
,
```
--toolchain
```
.
Read the build results and artifact scan report output by the script, focusing on the preferred artifacts (ELF > HEX > BIN) and failure categories.
Write the build directory, artifact path, artifact type, and generator information back to
```
Project Profile
```
, and pass it to downstream skills when needed.

When
```
cmake
```
or the required generator is missing, return
```
environment-missing
```
.
When configuration or build fails due to corrupted presets, missing toolchain files, or invalid target names, return
```
project-config-error
```
.
When the build appears successful but no flashable or debuggable artifacts are found, return
```
artifact-missing
```
.
When there are multiple equally reasonable presets or firmware targets, and any selection is unsafe, return
```
ambiguous-context
```
.

On Windows, unless the workspace explicitly requires a specific Visual Studio shell, prioritize
```
Ninja
```
to avoid dependency on a specific developer command environment.
The built-in script uses Python standard libraries and subprocess to call cmake, so the build scheduling path itself is cross-platform.
The build directory in the output should remain an absolute path for direct reuse by downstream flashing and debugging skills.

Output configuration commands, build commands, build directory, selected generator, and preferred artifact path.
Update
```
Project Profile
```
with
```
artifact_path
```
,
```
artifact_kind
```
, and detected toolchain details.
After success, recommend
```
flash-openocd
```
or
```
debug-gdb-openocd
```
.

When the next step is to flash the program to hardware, pass the successful build result to
```
flash-openocd
```
.
When the next step requires symbol information or a debugging session, pass the successful build result to
```
debug-gdb-openocd
```
.