# app_common

Shared header-only utilities for the Mcwhirter / bannister /
brasher fleet. Single source of truth for code that used to be
hand-copied (and had drifted) between the three repos.

## Contents

- `inc/app_utils.hpp` — byte/span casts (`as_bytes`), `overloads`, `deferrer`,
  `to_mac_string` (only when the toolchain has `<format>`; guarded by
  `__cpp_lib_format`).
- `inc/app_clock.hpp` — monotonic microsecond `TrivialClock`. The only
  OS-specific code in this repo: `now()` is `k_uptime_ticks()` on Zephyr and
  `esp_timer_get_time()` on ESP-IDF, selected by `__ZEPHYR__` / `ESP_PLATFORM`.
- `inc/app_clock_instant.hpp` — `Instant`, Rust-style elapsed-time helper on
  top of `clock_t`. Pure `std::chrono`, no OS dependency.

Everything requires C++23 (all consumers build with `-std=gnu++23` /
`CONFIG_STD_CPP2B`).

## Consuming

**ESP-IDF**: add as a git submodule under `components/app_common`. The root
`CMakeLists.txt` registers the component; add `app_common` to your `REQUIRES`.

**Zephyr**: add as a git submodule (e.g. `modules/app_common`) and append it to
`EXTRA_ZEPHYR_MODULES` in the application CMakeLists before
`find_package(Zephyr)`. The include directory is registered globally; targets
`app_common` / `app_utils` / `app_utils_clock` exist for explicit linking.

## Rules

- Nothing platform-specific beyond the `app_clock.hpp` seam. If a helper needs
  ESP-IDF or Zephyr APIs, it belongs in the consuming repo, not here.
- Never copy these headers back into a consumer repo. Bump the submodule.