Skip to content

agents.md

Latest commit

 

History

History
115 lines (87 loc) · 4.35 KB

agents.md

File metadata and controls

115 lines (87 loc) · 4.35 KB

agents.md — Coding Agent Guide for FR_Math

This file helps AI coding agents (Claude Code, Copilot, Cursor, Cody, etc.) work effectively with this codebase. For a machine-readable API summary, see llms.txt.

Project overview

FR_Math is a pure-C fixed-point math library for embedded systems. Integer-only, zero dependencies, caller-selectable radix (binary point).

Repository layout

src/                  Core library (this is what ships)
  FR_math.h           Public API — all macros, function declarations, constants
  FR_math.c           All function implementations
  FR_defs.h           Type aliases (s8, s16, s32, u8, u16, u32)
  FR_trig_table.h     Precomputed sine table
  FR_math_2D.h/.cpp   Optional C++ 2D transform class

tests/                Test suite (7 programs, run via `make test`)
examples/             Arduino .ino sketches + POSIX example
docs/                 Markdown documentation
pages/                HTML documentation (mirrors docs/)
scripts/              Build, release, version sync helpers
tools/                Coefficient generators (Python, C++)
dev/                  Development notes and planning (not shipped)

Build and test

make lib              # compile library objects
make test             # run all 7 test suites (27+ tests)
make examples         # build POSIX example
make clean            # remove build artifacts

All tests must pass before committing. Zero compiler warnings required.

Conventions — follow these when writing code

Naming

  • Functions: FR_ prefix for public C functions, fr_ for lowercase-style functions
  • Macros: ALL UPPERCASE with FR_ prefix (e.g., FR_ADD, FR_CLAMP)
  • Types: Use s32, u16, etc. from FR_defs.h — never raw int or unsigned

Fixed-point pattern

Most functions take a radix parameter specifying the binary point position. Always pass radix explicitly; never hardcode a radix inside library functions.

s32 result = FR_sqrt(I2FR(2, R), R);  // R is the caller's chosen radix

Adding a new function

  1. Declare in src/FR_math.h inside the extern "C" block
  2. Implement in src/FR_math.c
  3. Add tests in tests/test_full_coverage.c (pass/fail) and/or tests/test_tdd.cpp (characterization)
  4. Update keywords.txt (KEYWORD2 for functions, LITERAL1 for macros)
  5. Update llms.txt with the new function signature
  6. Update docs/api-reference.md and pages/guide/api-reference.html

Documentation mirroring

docs/*.md and pages/guide/*.html contain the same content in different formats. When updating documentation, update both. The HTML files are hand-authored (no build step).

Version management

Single source of truth: FR_MATH_VERSION_HEX in src/FR_math.h.

# After editing FR_MATH_VERSION_HEX:
./scripts/sync_version.sh          # propagate to all versioned files
./scripts/sync_version.sh --check  # verify everything is in sync

Versioned files (all synced automatically):

  • src/FR_math.h, VERSION, README.md, pages/assets/site.js
  • src/FR_math_2D.h, src/FR_math_2D.cpp
  • library.properties, library.json, idf_component.yml, llms.txt

Release checklist (abbreviated)

  1. Bump FR_MATH_VERSION_HEX in src/FR_math.h
  2. Run ./scripts/sync_version.sh
  3. Run ./tools/make_release.sh (full validation gate)
  4. Verify llms.txt and agents.md are current with any API changes
  5. Commit, tag, push

Platform targets

The library compiles on: AVR (Arduino), ARM Cortex-M0/M4, ESP32, RISC-V, x86/x64, MSP430, 68k, 8051. Code is 4–8 KB at -Os on 32-bit targets.

Library publishing

FR_Math is published to multiple package registries:

Registry Metadata file Auto-publish trigger
Arduino Library Manager library.properties GitHub release tag
PlatformIO library.json GitHub release tag
ESP-IDF Component Registry idf_component.yml + CMakeLists.txt GitHub release tag

What NOT to do

  • Don't add floating-point dependencies (the whole point is integer-only)
  • Don't use float or double in library source (tests/examples are OK)
  • Don't change the extern "C" wrapping in FR_math.h
  • Don't hardcode a radix inside library functions — always parameterize
  • Don't add #include dependencies beyond <stdint.h>