Skip to content

agents.md

Latest commit

 

History

History
53 lines (41 loc) · 5.17 KB

agents.md

File metadata and controls

53 lines (41 loc) · 5.17 KB
Raw

Agents — qf_math

Guidance for automated coding agents editing this repository.

Layout (do not fight it)

  • src/ — Library only (qf_math.c, qf_math.h, optional C++ facade qf_math.hpp). Keep this TU self-contained and allocation-free unless explicitly requested.
  • test/ — Host-side regression (qf_math_test.c) plus C++ wrapper smoke test (qf_math_cpp_test.cpp). Extend here when changing numerical behavior or wrapper surface.
  • compare/ — Peer-library matrices (*.md), benchmark harness (benchmark_suite.c, benchmark_core.c — shared with ESP examples/ trees), fetch/report scripts. All clones/build artifacts stay under build/compare/.
  • examples/ — Optional on-device benches: examples/lilygo_t_display_s3_bench/ (PlatformIO, LilyGO T-Display-S3), examples/esp32s3_benchmark/ (ESP-IDF), and examples/pico2_benchmark/ (Arduino, Raspberry Pi Pico 2).
  • docs/ — Markdown documentation (algorithms, API reference, fr_math relationship, integration guide).
  • pages/ — GitHub Pages HTML site (compact single-page bench + overview); deploy via GitHub Actions.
  • tools/ — Host helpers (qf_math_bench.c, run_libfixmath_tests.sh); keep MCU-light.
  • build/ — All binaries, CMake trees, cloned deps. Never commit; never author primary sources only here.

Build commands

  • Unit tests: make test
  • Lean C++ wrapper smoke test: make test-lean-cpp
  • Library object: make lib
  • Lean library object: make lib-lean (QF_MATH_LEAN, minimal float core)
  • qf vs libm benchmark: make bench
  • Multi-library compare bench + matrices docs: see compare/README.md; run make compare / make compare-report
  • Regenerate GitHub-facing Markdown report: make compare-github-report → compare/BENCHMARK_REPORT.md
  • Upstream libfixmath tests: make compare-tests
  • Upstream fr_math tests: make compare-fr-tests
  • Cross-target ROM/code-size matrix (Docker, fr_math-style): make docker-sizes → build/docker_sizes.csv, then refreshes the compact generated section in compare/README.md (see docker/README.md)
  • Release prep: make make-release VERSION=x.y.z (wrapper around tools/make_release.py; pass RELEASE_ARGS="--dry-run --skip-docker" when needed). It updates version metadata, runs tests, regenerates reports/pages, and refreshes Docker size data.
  • MCU compare benchmark (needs make compare-deps): examples/lilygo_t_display_s3_bench/ (pio run -t upload -t monitor), examples/esp32s3_benchmark/ (idf.py), or examples/pico2_benchmark/ (Arduino IDE / arduino-cli).
  • Silicon snapshot: make mcu-benchmark-snapshot → compare/MCU_BENCHMARK_SNAPSHOT*.md (pio / Arduino, pyserial, USB).

Editing rules

  • Preserve SPDX/license headers and existing comment tone.
  • Prefer -std=c99 compatible code; avoid GCC-only extensions unless already present nearby.
  • Numerical changes require coordinated tolerance updates in test/qf_math_test.c when behavior shifts.
  • Do not add silent network fetches outside compare/fetch_deps.sh (invoked by Makefile compare-deps) and documented compare targets.
  • QF_MATH_LEAN is a minimal float core: radian trig, inverse trig, log2/ln, pow2/exp/pow, sqrt, and qf_hypot_fast8. It intentionally excludes degree/BAM trig entry points, exact qf_hypot, qf_hypot_fast2, log10/pow10, waves, and ADSR.
  • Full builds still expose the degree/BAM trig APIs, exact/fast hypot variants, log10/pow10, waves, ADSR, and the full C++ wrapper surface.
  • For size comparisons, prefer generated CSV (build/docker_sizes.csv) over adding new Markdown tables. The committed docs should stay compact.

Manifests

  • library.json — PlatformIO; keep src/ as include dir.
  • idf_component.yml + root CMakeLists.txt — ESP-IDF component wiring only; fatal-error if configured standalone without ESP_PLATFORM. Published component uses strong warnings but not -Werror on the component target.
  • Version is currently 1.0.1 (QF_MATH_VERSION_HEX = 0x010001). When bumping, use python3 tools/qf_version.py update x.y.z so src/qf_math.h, README.md, docs/API.md, library.json, library.properties, idf_component.yml, pages/, llms.txt, and this file stay synchronized.
  • python3 tools/qf_version.py show --format json|shell|markdown emits release-friendly forms for tags, badges, manifests, docs, and scripts.

Markdown policy

Root README.md is canonical user-facing. docs/ holds Markdown documentation (algorithms, API, fr_math, integration, float tradeoffs). pages/ holds the GitHub Pages HTML site. compare/*.md holds methodology matrices; compare/BENCHMARK_REPORT.md is the tooling-generated host snapshot (make compare-github-report), compare/BENCHMARK_CROSSPLATFORM.md merges host + ESP32-S3 (make benchmark-crossplatform), compare/QF_MATH_ARCH_SPEED.md is the qf-vs-libm speed grid (make benchmark-arch-speed).

MCU snapshots are intentionally split by target: MCU_BENCHMARK_SNAPSHOT_ESP32S3.md, MCU_BENCHMARK_SNAPSHOT_PICO2_ARM.md, and MCU_BENCHMARK_SNAPSHOT_PICO2_RISCV.md. Refresh hardware snapshots only when the board is available and the user asks for it.