gcc

GCC Embedded Project Build

This skill provides embedded project discovery, preset enumeration, configuration generation, incremental compilation, full rebuild, cleaning, and ELF size analysis capabilities based on CMake + arm-none-eabi-gcc.

Scope note: currently only CMake-based GCC embedded projects are supported; pure Makefile projects are not covered.

Configuration

Environment-level configuration (skill/config.json)

The config.json in the skill directory contains environment-level configuration. Before first use, confirm that the cmake_exe path is correct:

{
  "cmake_exe": "cmake",
  "toolchain_prefix": "arm-none-eabi-",
  "toolchain_path": "",
  "operation_mode": 1
}

• cmake_exe: path to the cmake executable; by default found from PATH
• toolchain_prefix: toolchain prefix; default arm-none-eabi-, used to locate tools such as size
• toolchain_path: toolchain bin directory; when empty, found from PATH
• operation_mode：1 execute directly / 2 output a risk summary but do not block / 3 confirm before execution

Project-level configuration (workspace/.embeddedskills/config.json)

Project-level shared configuration is uniformly stored in the workspace's .embeddedskills/config.json :

{
  "gcc": {
    "project": "",
    "preset": "",
    "log_dir": ".embeddedskills/build"
  }
}

• project: default project path (relative to workspace); automatically updated after a successful build
• preset: default CMake preset name; automatically updated after a successful build
• log_dir: build log output directory; default .embeddedskills/build

Parameter resolution priority

Parameter resolution order (from highest to lowest):

1. Explicit CLI parameters
2. Environment-level configuration (skill/config.json)
3. Project-level configuration (.embeddedskills/config.json)
4. state.json (last build record)
5. Search/ask

Conflict resolution rule: when the same parameter has multiple sources, the source with the smallest number takes precedence; a higher-numbered source takes effect only when the lower-numbered source does not provide that parameter. For example: if the CLI has specified --preset Debug, then the last preset recorded in state.json is ignored.

Subcommands

Subcommand	Purpose	Risk
scan	Search for CMake embedded projects in the current directory	Low
presets	List configure/build presets in CMakePresets.json	Low
configure	Execute cmake --preset to generate the build system	Medium
build	Incremental compilation cmake --build	Medium
rebuild	Full rebuild after cleaning	Medium
clean	Clean the build directory	High
size	Analyze ELF file size (text/data/bss and memory usage)	Low

Execution flow

1. Read config.json, confirm that the cmake_exe path is valid
2. When no valid subcommand is provided, execute scan
3. When no project path is provided, first execute scan to search for projects
4. When multiple projects or multiple presets are discovered, list the options for the user to choose; never guess automatically
5. configure/build/rebuild/clean according to operation_mode determine whether confirmation is required
6. build Automatically detect whether configure has already been run before; if not configured, prompt the user to run configure first
7. build/rebuild On success, return elf_filefor jlink/openocd to continue using
8. size By default, analyze the .elf file of the most recent build artifact

Script invocation

There are three Python scripts in the skill directory, implemented using the standard library with no additional dependencies.

gcc_project.py — project scanning and preset enumeration

# 扫描工程
python <skill-dir>/scripts/gcc_project.py scan --root <搜索目录> --json

# 列出 preset
python <skill-dir>/scripts/gcc_project.py presets --project <工程目录> --json

gcc_build.py — configure / build / rebuild / clean

python <skill-dir>/scripts/gcc_build.py <configure|build|rebuild|clean> \
  --cmake <cmake路径> \
  --project <工程根目录> \
  --preset <preset名称> \
  --log-dir <日志目录> \
  --json

gcc_size.py — ELF size analysis

# 基本分析
python <skill-dir>/scripts/gcc_size.py analyze \
  --elf <elf文件路径> \
  --toolchain-prefix arm-none-eabi- \
  --linker-script <链接脚本路径> \
  --json

# 对比分析
python <skill-dir>/scripts/gcc_size.py compare \
  --elf <elf文件1> \
  --compare <elf文件2> \
  --toolchain-prefix arm-none-eabi- \
  --json

Output format

All scripts return in JSON format, with the base field being status（ok/error）、action、summary、details, and may also include context、artifacts、metrics、state、next_actions、timing。

Success example:

{
  "status": "ok",
  "action": "build",
  "summary": "build 成功，errors=0 warnings=2",
  "details": { "project": "...", "preset": "Debug", "build_dir": "...", "elf_file": "...", "log_file": "..." },
  "metrics": { "errors": 0, "warnings": 2, "flash_bytes": 99328, "ram_bytes": 46080 }
}

Error example:

{
  "status": "error",
  "action": "build",
  "error": { "code": "not_configured", "message": "构建目录不存在，请先执行 configure" }
}

Core rules

• Do not modify CMakeLists.txt or any CMake configuration files
• The current skill only covers CMake-based GCC projects and does not recognize or build pure Makefile projects
• Do not automatically guess the project path or preset; when ambiguous, the user must be asked
• Parameter parsing priority is: explicit CLI parameters > environment-level configuration > project-level configuration > .embeddedskills/state.json > search/ask
• clean is not implicitly executed in the automated flow
• When a build fails, prioritize showing the first error and the log file path
• The result echo always includes the project name, preset name, and build directory path; on a successful build, prioritize echoing elf_file