updated ci and docs

Author: deftio

.github/workflows/ci.yml

@@ -1,6 +1,6 @@
 # CI for qf_math — tests, strict library build, 100% line coverage on src/qf_math.c,
-# and sync of an annotated git tag v<QF_MATH_VERSION> so the version appears under
-# the GitHub repo “Tags” / Releases sidebar when pushing to main.
+# and sync of an annotated git tag + GitHub Release for v<QF_MATH_VERSION> when
+# pushing to main.
 
 name: CI
 
@@ -36,8 +36,10 @@ jobs:
           v=$(awk '/^#define QF_MATH_VERSION[[:space:]]/ {gsub(/"/,"",$3); print $3; exit}' src/qf_math.h)
           echo "value=$v" >> "$GITHUB_OUTPUT"
 
-      - name: Push tag v${{ steps.ver.outputs.value }} (main only, if missing)
+      - name: Tag and release v${{ steps.ver.outputs.value }} (main only, if missing)
         if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        env:
+          GH_TOKEN: ${{ github.token }}
         run: |
           set -euo pipefail
           TAG="v${{ steps.ver.outputs.value }}"
@@ -50,3 +52,6 @@ jobs:
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
           git tag -a "$TAG" -m "qf_math ${{ steps.ver.outputs.value }}" "$GITHUB_SHA"
           git push origin "refs/tags/$TAG"
+          gh release create "$TAG" --title "qf_math ${{ steps.ver.outputs.value }}" \
+            --notes "Release ${{ steps.ver.outputs.value }} — see [README](https://github.com/${{ github.repository }}#readme) for API overview and [CHANGELOG commits](https://github.com/${{ github.repository }}/commits/$TAG)." \
+            --verify-tag

README.md

@@ -13,7 +13,7 @@
 
 **qf_math** is a compact, dependency-free C99 library for **fast approximate math on IEEE-754 `float`**. It targets embedded firmware where you want predictable cost and small flash footprint: table-driven trig, logarithms, exponentials, `sqrt`, `hypot`, waveform helpers, and a floating-point ADSR envelope—without pulling in full libm semantics on platforms where that matters.
 
-[github.com/deftio/fr_math](github.com/deftio/fr_math) is the fixed point (pure integer) cousin of this library with identical apis.
+[fr_math](github.com/deftio/fr_math) is the fixed point (pure integer) cousin of this library with identical apis.
 
 | | |
 |---|---|
@@ -24,7 +24,6 @@
 
 Version macros live in [`qf_math.h`](src/qf_math.h): `QF_MATH_VERSION` / `QF_MATH_VERSION_HEX`. When you bump the version string, update the **Version** badge at the top of this README to match.
 
----
 
 ## Why use this?
 
@@ -33,13 +32,11 @@ Version macros live in [`qf_math.h`](src/qf_math.h): `QF_MATH_VERSION` / `QF_MAT
 - **Explicit trade-offs**: worst-case errors are documented in headers (e.g. trig ~3e-5 class behavior vs libm doubles).
 - **No heap**, minimal stack depth in normal use, integer-friendly helpers (`QF_*` macros, BAM phase, fixed-radix bridges).
 
----
 
 ## FPU-less alternative: [`fr_math`](https://github.com/deftio/fr_math)
 
 For targets **without a hardware FPU** (or when you want to avoid soft-float cost), use **[fr_math](https://github.com/deftio/fr_math)**—a **battle-tested** sister library that exposes the **same API** using **pure fixed-point** math, with **16-bit** platform support when that is a requirement.
 
----
 
 ## Repository layout
 
@@ -57,7 +54,6 @@ build/         compiled binaries, CMake outputs, cloned deps (gitignored)
 
 Everything that resembles an artifact—including vendored comparison libraries—stays under **`build/`** (for example `build/compare/third_party/`) so your tree stays clean.
 
----
 
 ## Build & test (host)
 
@@ -78,7 +74,6 @@ make coverage-check  # CI-style gate: 100% lines covered in src/qf_math.c
 make clean
 ```
 
----
 
 ## Cross-compile code sizes (Docker)
 
@@ -91,7 +86,6 @@ make docker-sizes-rebuild   # force docker image rebuild first
 
 Details: **[docker/README.md](docker/README.md)**.
 
----
 
 ## Comparisons vs other math stacks (`compare/`)
 
@@ -114,32 +108,19 @@ Documentation tables live under **`compare/`** (`LIBRARIES.md` for platforms/rep
 
 **Host vs MCU (relative only):** **[compare/BENCHMARK_CROSSPLATFORM.md](compare/BENCHMARK_CROSSPLATFORM.md)** merges **Speed vs libm** tables from [`compare/BENCHMARK_REPORT.md`](compare/BENCHMARK_REPORT.md) (POSIX snapshot) and the MCU snapshots (`MCU_BENCHMARK_SNAPSHOT*.md` — ESP32-S3, Pico 2 ARM, Pico 2 RISC-V); regenerate with **`make benchmark-crossplatform`** after refreshing those files.
 
----
 
 ## Packaging & integration
 
 ### PlatformIO
 
-- **Manifest:** [`library.json`](library.json) (registry: [deftio/qf_math](https://registry.platformio.org/libraries/deftio/qf_math)).
-- **`lib_deps`:** `deftio/qf_math` or `https://github.com/deftio/qf_math.git`
-- **Lean subset** (smaller ROM, no `log10` / `pow10` / waves / ADSR): add to the env `build_flags = -DQF_MATH_LEAN`
-- **`export` exclude** in the manifest trims compare/tests/docs from the PIO-installed copy; clones via **git URL** still get the full repo (including **`examples/`**).
-- Sanity check locally: `pio pkg pack .` must succeed before publishing.
-
-### Arduino Library Manager / Arduino IDE
-
-- **Manifest:** [`library.properties`](library.properties) beside `library.json` (Arduino 2.x discovers `src/` layout).
-- Install from ZIP of the repo or symlink the folder under `Arduino/libraries/`; include `#include <qf_math.h>` (Arduino adds library `src/` to the include path).
+Use `library.json` at the repo root: add this folder as a local library or publish following [PlatformIO library format](https://docs.platformio.org/en/latest/manifests/library-json/index.html). Headers resolve from `src/` (`#include "qf_math.h"` for C, `#include "qf_math.hpp"` for C++).
 
 ### Espressif ESP-IDF
 
-- **Component Manager:** [`idf_component.yml`](idf_component.yml) + [`CMakeLists.txt`](CMakeLists.txt). Component tarball excludes bulky trees (`examples/`, `compare/`, …); **`src/`**, root **`CMakeLists.txt`**, **`LICENSE.txt`**, and **`README.md`** remain usable.
-- **Consumer projects:** `#include "qf_math.h"`; optional **`QF_MATH_LEAN`** via `target_compile_definitions` on your target or **`idf.py menuconfig`/CMake extra flags**.
-- **Warnings:** component build uses `-Wall -Wextra -Wshadow -Wconversion` **without** `-Werror` so toolchain/IDF updates are less likely to break downstream apps.
+`idf_component.yml` registers the component for the ESP-IDF Component Manager. `CMakeLists.txt` wraps `idf_component_register` for `src/qf_math.c` with include path `src/`.
 
-Add as a dependency (path or git URL) per Espressif docs.
+Add as a dependency (path or git URL) per Espressif docs; then `#include "qf_math.h"` from application components.
 
----
 
 ## API overview
 
@@ -153,7 +134,6 @@ Public surface is declared in `src/qf_math.h`:
 
 Domain violations (`sqrt` of negative, `log` of non-positive) return `QF_DOMAIN_ERROR`.
 
----
 
 ## Documentation for automation
 
@@ -167,15 +147,13 @@ Domain violations (`sqrt` of negative, `log` of non-positive) return `QF_DOMAIN_
 | `llms.txt` | Compact index for LLM tooling / crawling |
 | `agents.md` | Conventions for coding agents working in this repo |
 
----
 
 ## Contributing & correctness
 
 - Prefer extending tests in `test/qf_math_test.c` when adjusting numerical behavior.
 - Keep binaries and fetched trees under `build/` only.
 - Match existing comment and license style in touched files.
 
----
 
 ## Credits
 

pages/index.html

@@ -25,22 +25,22 @@ <h2>Accuracy &amp; speed sweep vs libm</h2>
 <p>This table is generated by <code>tools/qf_math_bench.c --html-table</code> (same grids as <code>make bench</code>). Numbers are from the machine that last ran <code>make docs-pages</code> or the GitHub Actions Pages deploy — <strong>not MCU timings</strong>.</p>
 
 <!--QF_MATH_BENCH_TABLE_BEGIN-->
-<p class="qf-meta"><small>Generated UTC <strong>2026-05-08 03:36:06Z</strong> — 10000-sample grids, 100000 outer × 100-inner timing loops; error vs C <code>double</code>; libm = matching <code>*f</code> call. Compiler: <code>Apple LLVM 21.0.0 (clang-2100.0.123.102)</code>.</small></p>
+<p class="qf-meta"><small>Generated UTC <strong>2026-05-09 09:09:51Z</strong> — 10000-sample grids, 100000 outer × 100-inner timing loops; error vs C <code>double</code>; libm = matching <code>*f</code> call. Compiler: <code>Apple LLVM 21.0.0 (clang-2100.0.123.102)</code>.</small></p>
 <h3>Accuracy sweep vs libm (<code>float</code>)</h3>
 <table class="qf-table"><thead><tr><th scope="col">Function</th><th scope="col">Bench note</th><th scope="col">Max</th><th scope="col">Mean</th><th scope="col"><code>qf</code> ms</th><th scope="col">libm ms</th><th scope="col">libm ÷ qf</th></tr></thead>
 <tbody>
-<tr><td><code>qf_sin()</code></td><td>radians; ref = sin in double</td><td>0.009691% amp</td><td>0.003225% amp</td><td>49.31</td><td>21.57</td><td><strong>0.44</strong>×</td></tr>
-<tr><td><code>qf_cos()</code></td><td>radians; ref = cos in double</td><td>0.009733% amp</td><td>0.003226% amp</td><td>33.05</td><td>23.46</td><td><strong>0.71</strong>×</td></tr>
-<tr><td><code>qf_tan()</code></td><td>excludes inputs within 0.05 rad of poles</td><td>1.71% amp</td><td>0.04845% amp</td><td>61.59</td><td>29.32</td><td><strong>0.48</strong>×</td></tr>
-<tr><td><code>qf_acos()</code></td><td>domain [-1, 1]; radians out</td><td>0.007487% of pi</td><td>0.000372% of pi</td><td>76.82</td><td>22.90</td><td><strong>0.30</strong>×</td></tr>
-<tr><td><code>qf_atan2()</code></td><td>swept (y,x) magnitudes; ref = atan2 double</td><td>0.02969% of pi</td><td>0.006815% of pi</td><td>57.21</td><td>26.28</td><td><strong>0.46</strong>×</td></tr>
-<tr><td><code>qf_log2()</code></td><td>x in (0.001, 100]; absolute Δ vs double</td><td>4.353e-05 abs</td><td>1.615e-05 abs</td><td>16.40</td><td>23.07</td><td><strong>1.41</strong>×</td></tr>
-<tr><td><code>qf_ln()</code></td><td>x in (0.001, 100]; absolute Δ vs double</td><td>3.03e-05 abs</td><td>1.119e-05 abs</td><td>22.99</td><td>22.84</td><td><strong>0.99</strong>×</td></tr>
-<tr><td><code>qf_pow2()</code></td><td>relative vs double; libm ref = exp2f</td><td>0.001473% rel</td><td>0.0009778% rel</td><td>20.28</td><td>16.77</td><td><strong>0.83</strong>×</td></tr>
-<tr><td><code>qf_exp()</code></td><td>relative vs double on grid</td><td>0.001512% rel</td><td>0.0009779% rel</td><td>21.95</td><td>16.68</td><td><strong>0.76</strong>×</td></tr>
-<tr><td><code>qf_sqrt()</code></td><td>relative vs double</td><td>0.0004702% rel</td><td>0.0001786% rel</td><td>16.28</td><td>6.33</td><td><strong>0.39</strong>×</td></tr>
-<tr><td><code>qf_hypot()</code></td><td>relative vs double hypot</td><td>0.0004676% rel</td><td>0.0001906% rel</td><td>13.22</td><td>12.96</td><td><strong>0.98</strong>×</td></tr>
-<tr><td><code>qf_hypot_fast8()</code></td><td>qf piecewise-linear; timed vs hypotf reference</td><td>0.1372% rel</td><td>0.05112% rel</td><td>22.70</td><td>13.17</td><td><strong>0.58</strong>×</td></tr>
+<tr><td><code>qf_sin()</code></td><td>radians; ref = sin in double</td><td>0.001885% amp</td><td>0.0007992% amp</td><td>10.64</td><td>21.39</td><td><strong>2.01</strong>×</td></tr>
+<tr><td><code>qf_cos()</code></td><td>radians; ref = cos in double</td><td>0.001887% amp</td><td>0.0008006% amp</td><td>10.46</td><td>22.70</td><td><strong>2.17</strong>×</td></tr>
+<tr><td><code>qf_tan()</code></td><td>excludes inputs within 0.05 rad of poles</td><td>0.4535% amp</td><td>0.02151% amp</td><td>29.42</td><td>28.64</td><td><strong>0.97</strong>×</td></tr>
+<tr><td><code>qf_acos()</code></td><td>domain [-1, 1]; radians out</td><td>0.01482% of pi</td><td>0.002432% of pi</td><td>94.05</td><td>22.36</td><td><strong>0.24</strong>×</td></tr>
+<tr><td><code>qf_atan2()</code></td><td>swept (y,x) magnitudes; ref = atan2 double</td><td>0.04097% of pi</td><td>0.01276% of pi</td><td>28.63</td><td>25.71</td><td><strong>0.90</strong>×</td></tr>
+<tr><td><code>qf_log2()</code></td><td>x in (0.001, 100]; absolute Δ vs double</td><td>8.104e-07 abs</td><td>2.15e-07 abs</td><td>19.19</td><td>22.23</td><td><strong>1.16</strong>×</td></tr>
+<tr><td><code>qf_ln()</code></td><td>x in (0.001, 100]; absolute Δ vs double</td><td>6.235e-07 abs</td><td>1.676e-07 abs</td><td>25.55</td><td>22.30</td><td><strong>0.87</strong>×</td></tr>
+<tr><td><code>qf_pow2()</code></td><td>relative vs double; libm ref = exp2f</td><td>0.000322% rel</td><td>3.64e-05% rel</td><td>22.48</td><td>16.13</td><td><strong>0.72</strong>×</td></tr>
+<tr><td><code>qf_exp()</code></td><td>relative vs double on grid</td><td>0.0003402% rel</td><td>4.163e-05% rel</td><td>25.65</td><td>16.28</td><td><strong>0.63</strong>×</td></tr>
+<tr><td><code>qf_sqrt()</code></td><td>relative vs double</td><td>0.0004702% rel</td><td>0.0001786% rel</td><td>16.08</td><td>6.27</td><td><strong>0.39</strong>×</td></tr>
+<tr><td><code>qf_hypot()</code></td><td>relative vs double hypot</td><td>0.0004676% rel</td><td>0.0001906% rel</td><td>13.35</td><td>13.02</td><td><strong>0.98</strong>×</td></tr>
+<tr><td><code>qf_hypot_fast8()</code></td><td>qf piecewise-linear; timed vs hypotf reference</td><td>0.1372% rel</td><td>0.05112% rel</td><td>22.89</td><td>13.17</td><td><strong>0.58</strong>×</td></tr>
 </tbody></table>
 <p class="qf-footnote"><small><strong>Error column:</strong> <em>amp</em> = % of ±1 output (sin/cos/tan). <em>rel</em> = max relative error vs double × 100. <em>of pi</em> = absolute radian error as % of π (acos, atan2). <em>abs</em> = absolute Δ vs double on the grid (log2, ln). <strong>libm ÷ qf</strong> uses total loop time; &gt; 1 means qf_math was faster on this host (microbenchmark only; profile on your MCU).</small></p>
 <!--QF_MATH_BENCH_TABLE_END-->

tools/check_coverage.sh

@@ -36,8 +36,6 @@ else
 fi
 
 echo "--- gcov line summary (src/qf_math.c) ---"
-grep -v '^[[:space:]]*-:[[:space:]]*0:' "$GCOV_FILE" | grep '^[[:space:]]*[0-9]' | head -5 >/dev/null
-gcov -r "$GCOV_FILE" 2>/dev/null || true
 
 if grep -q '#####:' "$GCOV_FILE"; then
   echo ""

tools/qf_math_bench.c

@@ -10,6 +10,11 @@
  *  All rights reserved. BSD-2-Clause — see qf_math.h for full text.
  */
 
+/* Enable clock_gettime / CLOCK_MONOTONIC on glibc with -std=c99 */
+#if !defined(_POSIX_C_SOURCE) && !defined(__APPLE__)
+#define _POSIX_C_SOURCE 199309L
+#endif
+
 #include <stdio.h>
 #include <math.h>
 #include <stdint.h>