From 761b6d5b865a7eb939bce9ba234fe4f50d882925 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 28 Jul 2026 13:04:54 +0000 Subject: [PATCH 1/2] Publish the book to GitHub Pages, and fix its site-url 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 Claude-Session: https://claude.ai/code/session_01JhhQ93r2E1QTnCx46YfX8j --- .github/workflows/docs.yml | 78 ++++++++++++++++++++++++++++++++++++++ book/book.toml | 2 +- 2 files changed, 79 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/docs.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..9ccd616 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,78 @@ +name: Docs + +# Build the mdBook ("Quieting the Loop", book/) and publish it to GitHub Pages +# on every push to main. On pull requests, build only (no deploy) so breakage is +# caught in review without touching the live site — this is also the repo's only +# gate on the book, since ci.yml does not build it. +# +# TapTools' docs.yml pattern (itself AmbiTap's), minus the Doxygen site: this +# repo has no Doxyfile, so the book is the whole site and is published at the +# root. book.toml's site-url is /MuTap/ to match that; if a Doxygen site is ever +# added under /api/, assemble a site/ directory the way AmbiTap does rather than +# moving the book into a subdirectory, so site-url stays correct. + +on: + push: + branches: [main] + pull_request: + +permissions: + contents: read + pages: write + id-token: write + +# Allow one concurrent deployment; a newer push supersedes an in-flight one. +concurrency: + group: pages + cancel-in-progress: false + +env: + MDBOOK_URL: https://github.com/rust-lang/mdBook/releases/download/v0.4.40/mdbook-v0.4.40-x86_64-unknown-linux-gnu.tar.gz + MDBOOK_SHA256: "9ef07fd288ba58ff3b99d1c94e6d414d431c9a61fdb20348e5beb74b823d546b" + +jobs: + build: + name: build book + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - uses: actions/checkout@v4 + + - name: Install mdBook (pinned) + run: | + curl -sSL "$MDBOOK_URL" -o mdbook.tar.gz + echo "$MDBOOK_SHA256 mdbook.tar.gz" | sha256sum -c - + tar -xzf mdbook.tar.gz mdbook + ./mdbook --version + + # book.toml sets create-missing = false, so a SUMMARY.md entry without a + # matching file fails the build rather than silently generating a stub. + - name: Build the book + run: ./mdbook build book + + - name: Upload Pages artifact + if: github.ref == 'refs/heads/main' + uses: actions/upload-pages-artifact@v3 + with: + path: book/book + + deploy: + name: deploy to Pages + if: github.ref == 'refs/heads/main' + needs: build + runs-on: ubuntu-latest + timeout-minutes: 10 + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + # Creates/enables the Pages site (Source: GitHub Actions) if the repo + # doesn't have one yet — deploy-pages 404s otherwise. + - name: Enable Pages + uses: actions/configure-pages@v5 + with: + enablement: true + + - name: Deploy + id: deployment + uses: actions/deploy-pages@v4 diff --git a/book/book.toml b/book/book.toml index 1a681c2..0e02cf1 100644 --- a/book/book.toml +++ b/book/book.toml @@ -11,4 +11,4 @@ create-missing = false [output.html] default-theme = "rust" git-repository-url = "https://github.com/tap/MuTap" -site-url = "/MuTap/book/" +site-url = "/MuTap/" From e989c5690a1a85826cbf9d190c3a4b2fc9817c42 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 28 Jul 2026 15:45:04 +0000 Subject: [PATCH 2/2] Compile the C ABI in CI, and export the tap::mu alias 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 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 Claude-Session: https://claude.ai/code/session_01JhhQ93r2E1QTnCx46YfX8j --- .github/workflows/ci.yml | 9 +++++++++ CMakeLists.txt | 5 +++++ 2 files changed, 14 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5591d80..196cbc6 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -21,19 +21,27 @@ jobs: cc: gcc cxx: g++ werror: ON + capi: ON - name: Linux Clang os: ubuntu-latest cc: clang cxx: clang++ werror: ON + capi: ON # Warnings stay non-fatal on MSVC until /W4 output has been triaged # on a Windows runner (same policy as the sibling *Tap repos). - name: macOS AppleClang os: macos-latest werror: ON + capi: ON + # capi stays OFF on Windows: tools/capi carries no __declspec(dllexport) + # (unlike DspTap's), so an MSVC build would link a DLL exporting nothing + # — it would pass without gating anything. Turn this ON in the same + # change that gives the C ABI an export decoration. - name: Windows MSVC os: windows-latest werror: OFF + capi: OFF steps: - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6 with: @@ -47,6 +55,7 @@ jobs: cmake -B build -DCMAKE_BUILD_TYPE=Release -DMUTAP_WERROR=${{ matrix.werror }} + -DMUTAP_BUILD_CAPI=${{ matrix.capi }} - name: Build run: cmake --build build --config Release -j 4 diff --git a/CMakeLists.txt b/CMakeLists.txt index a819472..44eef7b 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -18,6 +18,11 @@ add_subdirectory(submodules/dsptap) add_library(mutap INTERFACE) add_library(MuTap::MuTap ALIAS mutap) +# The family-wide alias, per the namespace convention in taphouse's README: one +# `tap::` sub-namespace per repo, and the CMake alias matches it. The +# older spelling above stays so existing consumers keep working; prefer +# `tap::mu` in new code. +add_library(tap::mu ALIAS mutap) target_include_directories(mutap INTERFACE $ $)