# memllib — vendored, not a submodule

This directory is a **vendored copy** of the load-bearing subset of
[`MusicallyEmbodiedML/memllib`](https://github.com/MusicallyEmbodiedML/memllib), the
hardware-abstraction library for the MEMLNaut board (audio driver, TFT display, MIDI
I/O, peripherals). It replaced the `src/memllib` git submodule during the Phase 4
PlatformIO migration (2026-07-21).

## Provenance

- **Upstream repo**: `https://github.com/MusicallyEmbodiedML/memllib.git`
- **Vendored at commit**: `e291192d8e4f2fca7b79670c4df9c2ec8bdf03cd` (upstream `main`,
  "l r input swap")
- **License**: MPL-2.0 (`LICENSE` in this directory, copied verbatim from upstream)

## What was copied, what was dropped

Copied verbatim, directory structure unchanged, under `src/`: `audio/`, `hardware/`,
`interface/`, `synth/`, `utils/`, `PicoDefs.hpp`. `LICENSE` sits at this directory's
root (metadata, not source). These are exactly the subdirectories the firmware sketch
used to reach via its symlink forest (`firmware/MEMLNaut-NISPS/src/memllib` before this
migration) — only the wrapping `src/` folder and the `library.properties` manifest are
new, both required for PlatformIO to discover and recursively compile this tree (see
below).

Dropped: `examples/` (17 files — never compiled; the firmware never referenced it, and
its content that mattered was already ported into `nisps/ml/{jolt,ou_noise,feedback,
geo_push}.hpp` per the pre-Phase-4 submodule-bump decision), `.git` (submodule gitlink),
`.gitignore` (build-artifact patterns, meaningless once vendored — this repo's own
`.gitignore` covers it), `README.md` (described the old Arduino-IDE TFT_eSPI
`User_Setup_Select.h` copy-paste workflow, which PlatformIO replaces with
`-D USER_SETUP_LOADED=1` + explicit build flags in `platformio.ini` — see there).

98 files, ~1.9 MB total — all of memllib bar `examples/`; there is no smaller subset to
lift (every one of the 24 `.cpp` translation units here is reached by at least one
compiled firmware variant).

## Internal include convention (do not break)

Files inside this tree include each other with paths relative to `src/` as the root
(e.g. `src/hardware/memlnaut/MEMLNaut.cpp` does `#include "../PicoDefs.hpp"`,
`src/hardware/memlnaut/display/View.cpp` does `#include "../../PicoDefs.hpp"`).

This directory is consumed as a PlatformIO Arduino-format library (`lib/memllib/`, with
`library.properties` + a `src/` subfolder — the standard 1.5 Arduino library layout).
PlatformIO's Library Dependency Finder therefore adds `lib/memllib/src` (not
`lib/memllib` itself) to the include search path and recursively compiles every source
file under `src/`.

**Do not vendor these five subdirectories directly under `lib/memllib/`** (i.e. without
the `src/` wrapper) — that was tried first and silently compiles nothing: PlatformIO's
`ArduinoLibBuilder`, when it finds no `src/` subfolder, falls back to a *non-recursive*
"files directly in the library root" scan (the historical Arduino 1.0 library format,
which only special-cases a `utility/` subfolder). Nested folders like `audio/` or
`hardware/` are silently invisible to the build under that fallback — it links, or
rather fails to link, with `undefined reference to MEMLNaut::...` for every symbol in
this library. The `src/` subfolder switches PlatformIO onto the recursive path.

Firmware code outside this tree (`../../src/main.cpp`, `../../glue/*.hpp`) includes
headers here relative to `src/` as the root, e.g. `#include "audio/AudioDriver.hpp"`,
`#include "hardware/memlnaut/MEMLNaut.hpp"` — no `memllib/` or `src/` prefix, because
`lib/memllib/src/` *is* the include root PlatformIO adds.

## Re-syncing with upstream

There is no submodule to bump anymore, so a re-sync is a manual, documented diff:

1. Clone upstream at the desired commit: `git clone
   https://github.com/MusicallyEmbodiedML/memllib.git /tmp/memllib-upstream`
2. Diff the five subdirs + `PicoDefs.hpp` against this directory's `src/`, e.g.:
   ```
   diff -ru /tmp/memllib-upstream/audio firmware/MEMLNaut-NISPS/lib/memllib/src/audio
   # ...repeat for hardware/ interface/ synth/ utils/ PicoDefs.hpp
   ```
3. Copy over the changed files (`cp -a`), re-run `diff -ru` both ways to confirm nothing
   outside the tracked subset leaked in and nothing was silently dropped.
4. Update the "Vendored at commit" line above to the new upstream SHA + its subject
   line.
5. Rebuild every `platformio.ini` env (`pio run`) and diff flash/RAM sizes against the
   previous vendored commit's numbers — a size jump with no corresponding upstream
   feature is a signal something unexpected changed.
6. Commit the vendored-file changes and this doc update together.

If upstream ever restructures these directories (renames, new cross-subdir relative
includes), the internal-include convention above may need re-verification — grep for
`#include "\.\./` inside this tree and confirm every relative path still resolves.