Publish the book to Pages; compile the C ABI in CI; export tap::mu - #32
Merged
Conversation
MuTap was the only repo in the family that ships a book/ with no way to build or publish it: ci.yml never invoked mdbook, so "Quieting the Loop" was neither deployed nor gated -- a SUMMARY.md entry pointing at a missing file would have gone unnoticed until someone built the book by hand. Adds docs.yml on TapTools' pattern (itself AmbiTap's), minus the Doxygen site since this repo has no Doxyfile: build on every push and pull request, deploy to Pages only from main. The pull-request path is build-only, which makes this the repo's book gate as well as its publisher -- book.toml sets create-missing = false, so a SUMMARY entry without a matching file fails the build rather than silently generating a stub. mdBook is pinned by URL and SHA256, matching the sibling workflows. Also corrects site-url, which was "/MuTap/book/" while the book is published at the site root. mdBook only uses site-url for the absolute links in the generated 404 page; with the mismatch, that page's home link pointed at /MuTap/book/ and would itself have 404'd. Asset paths are relative and were never affected, so the impact was narrow -- but the value was simply wrong. It is now "/MuTap/", so the 404 page's home link resolves to where the book actually lives. The workflow's header records that a future Doxygen site should be assembled into a site/ directory the way AmbiTap does, rather than moving the book into a subdirectory, so site-url stays correct. Verified with the pinned mdBook v0.4.40 (checksum confirmed): the book builds clean with no warnings, all three SUMMARY targets exist, the artifact directory the workflow uploads (book/book) contains index.html, and the regenerated 404 page's home link is /MuTap/. The workflow YAML parses, with the expected build and deploy jobs and push/pull_request triggers. book/book/ is already gitignored, so the build output stays out of the tree. Note the same site-url mismatch exists in AmbiTap and TapTools -- both declare ".../book/" while publishing the book at the root (AmbiTap assembles site/ with the book at root and Doxygen under api/; TapTools uploads book/book directly). SampleRateTap is the consistent one. Not touched here. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JhhQ93r2E1QTnCx46YfX8j
This repo ships a C ABI under tools/capi that the notebook generators drive via ctypes, but MUTAP_BUILD_CAPI defaults to OFF and CI never turned it on -- so nothing in the pipeline compiled it, and a kernel signature change could break the ABI with CI staying green. AmbiTap and DspTap already build theirs; this brings MuTap in line. Enabled on the Linux and macOS legs only. tools/capi carries no __declspec(dllexport) (unlike DspTap's), so an MSVC build would link a DLL that exports nothing -- it would pass without gating anything. Recorded in the matrix comment and in taphouse's known-divergences list, to be flipped on in the same change that gives the C ABI an export decoration. Also exports `tap::mu`, the alias taphouse's namespace convention has documented all along but that this repo never created. `MuTap::MuTap` stays, so existing consumers are unaffected. Verified locally: configure and build succeed with MUTAP_WERROR=ON, the shared library links and exports its 34 mutap_* entry points, and the full suite passes 181/181. Worth noting for issue #31: itu_echo.EchoStability<float> and the float32 parity tests -- the two that fail on macOS -- pass here on Linux, which is consistent with the vDSP-backend hypothesis in that issue rather than a platform-independent regression. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JhhQ93r2E1QTnCx46YfX8j
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this changes
Two commits:
docs.yml— builds the mdBook ("Quieting the Loop") on every push and PR, deploys to GitHub Pages frommain; fixesbook.toml'ssite-urlto match where the book is actually served.tap::mualias.Why
The book had no workflow at all —
ci.ymldoes not build it, so a brokenSUMMARY.mdentry or a missing chapter file could land unnoticed, and the book was never published. It now builds on PRs (catching breakage in review) and deploys only frommain.MUTAP_BUILD_CAPIdefaults to OFF and CI never turned it on, so nothing in the pipeline compiled the C ABI that the notebook generators drive via ctypes. A kernel signature change could break the ABI and the notebooks with CI staying green. AmbiTap and DspTap already build theirs.tap::muis the alias taphouse's namespace convention documented but this repo never created (see tap/TapHouse#6).Verification
index.html;404.html's home link is now/MuTap/.book/book/is gitignored.docs.ymlparses as YAML;configure-pages@v5withenablement: truecreates the Pages site on first run.MUTAP_WERROR=ON;libmutap_capi.solinks and exports its 34mutap_*entry points (nm -D).Notes for the reviewer
tools/capicarries no__declspec(dllexport)(unlike DspTap's), so an MSVC build would link a DLL exporting nothing — it would pass without gating anything. That is stated in the matrix comment and in taphouse's known-divergences list, to be flipped on in the same change that gives the C ABI an export decoration.path: book/book), not under/book/. If a Doxygen site is ever added under/api/, assemble asite/directory the way AmbiTap'sdocs.ymldoes rather than moving the book into a subdirectory — otherwisesite-urlgoes wrong again. There is a comment in the workflow saying so.submodules/dsptapstays at9cbfbca, 11 commits behind its siblings, on account of macOS: two float32 tests fail under AppleClang 21 / Xcode 26.5 (Float32Parity.ToneRowWithNarrowbandGuard, itu_echo.EchoStability<float>) #31 — though see below: the suspected cause is probably not in the FFT backend, so that hold may be buying nothing.MuTap::MuTapstays alongsidetap::mu, so no consumer changes.include/mutap/does not yet match the convention'stap/mu/; renaming breaks every consumer#include.Why this PR shows a red check, and a finding for #31
Nothing in this PR is failing.
ci.ymltriggers on bothpushandpull_request, so commite989c569got two runs, and GitHub shows the union of their check runs on the PR. One of them went red on macOS; the other went green:e989c569pushe989c569pull_requestSame commit, same tree, same workflow, opposite outcomes. I have re-run the failed job so the PR reflects reality.
The two macOS failures were:
This corrects what an earlier version of this description said. It claimed the Linux pass was "consistent with the vDSP-backend hypothesis" in #31. That is wrong: a fixed backend difference cannot produce pass-and-fail on an identical commit.
main's own macOS job shows the same pattern historically — red atd2a3abcand2e024739, green at0682238and others.What fits is nondeterministic state, most likely an uninitialized read: one root cause that explains a marginal 1.1% miss and a catastrophic 97 dB miss coexisting, explains why it is macOS-mostly (allocator fill behaviour, not different arithmetic), and explains why Linux ASan+UBSan stays green — ASan does not detect uninitialized reads. MSan or Valgrind on those two tests is the cheap next probe; the
-DTAP_DSP_FFT_ACCELERATE=OFFbisection is now the second step, since if the cause is uninitialized state, toggling vDSP may move the failure rate without being the cause. Written up in #31.I could not reproduce either failure directly — no macOS here, and both tests pass on Linux where I ran the full 181 clean.