memlnaut-nisps/vcv/DISTRIBUTION.md

Distributing the MEMLNaut VCV Rack plugin

How the MEMLNaut plugin is built for every platform and published to the public download page at https://meml.lnfinitemonkeys.org/next/vcv/.

Plugin slug: MEMLNaut. Version comes from plugin.json (jq -r .version).

---

1. Build artefacts (.vcvplugin)

A .vcvplugin is a tar.zst archive of a MEMLNaut/ directory containing the platform binary (plugin.so / .dll / .dylib), plugin.json, and res/. The official plugin.mk dist target produces it, named <slug>-<version>-<platform>.vcvplugin (e.g. MEMLNaut-0.2.0-lin-x64.vcvplugin). Platforms: lin-x64, win-x64, mac-x64, mac-arm64.

Linux x64 — locally (works today)

The Rack 2 SDK is installed at $HOME/.local/share/Rack2/Rack-SDK:

cd vcv
RACK_DIR=$HOME/.local/share/Rack2/Rack-SDK make dist
# -> vcv/dist/MEMLNaut-<version>-lin-x64.vcvplugin

This is the only platform we build on the server: the host toolchain is native Linux x64 and the SDK is already present. Build products (build/, dist/, plugin.so, *.vcvplugin) are git-ignored — they are publish artefacts, not source.

Windows / macOS — cross-built on CI (NOT on the server)

The other three platforms are cross-built by the official VCVRack/rack-plugin-toolchain, the same Docker cross-builder the VCV Library uses. We do not run that toolchain on the production VPS — its image build compiles mingw + osxcross and pulls the Apple SDK (multi-GB, multi-hour), which would overload a host that serves live services. macOS additionally requires the Apple SDK, which we never redistribute. CI is the right place for all of this; for a local-only macOS build the operator can use a Mac with the native SDK.

---

2. CI: .github/workflows/vcv-plugin.yml

Builds all four platforms on ubuntu-latest runners via the pinned toolchain (TOOLCHAIN_REF, currently Rack SDK 2.6.6 / toolchain image v19). Triggers on:

• pushes touching vcv/** (smoke-build the matrix),
• pull requests touching vcv/**,
• tag pushes v* (build and attach to a GitHub Release),
• manual workflow_dispatch.

Per matrix platform the job: checks out the plugin + pinned toolchain, fetches the per-platform Rack SDKs (make rack-sdk-all), builds/loads the cached toolchain Docker image, then runs make docker-plugin-build-<platform> PLUGIN_DIR=$GITHUB_WORKSPACE/vcv. The resulting .vcvplugin is uploaded as a workflow artifact. On a v* tag the release job downloads all four and attaches them to the release via softprops/action-gh-release.

The heavy toolchain image is cached by TOOLCHAIN_REF, so only the first run on a new pin pays the build cost.

Cutting a release

# bump version in vcv/plugin.json, commit, then:
git tag v0.2.0
git push origin v0.2.0

CI builds lin-x64 / win-x64 / mac-x64 / mac-arm64 and attaches the four .vcvplugin files to the GitHub release for v0.2.0.

Bumping the toolchain

Edit TOOLCHAIN_REF (and TOOLCHAIN_IMAGE_VERSION if the image version changes) in .github/workflows/vcv-plugin.yml. Pin to a commit — never float on master.

---

3. Publishing to /next/vcv

The download page lives in the live a-immersive docroot at /home/w1n5t0n/deployments/meml-aimmersive/next/vcv/. It is purely additive — a new subdir alongside /next/animations, disturbing nothing else.

Files:

• index.html — the download page (Manifold design tokens: dark, JetBrains Mono, --accent #ff6a00). Lists each platform with a download link, the version, VCV install instructions, and which platforms are available now vs built by CI.
• a-immersive.html — a byte-identical copy of index.html. nginx for meml.lnfinitemonkeys.org sets index a-immersive.html, so /next/vcv/ resolves via this alias (same trick /next/animations uses). No nginx change is needed for a new subdir.
• MEMLNaut-<version>-<platform>.vcvplugin — the artefact(s).

Adding CI release artifacts to /next/vcv

After a v* release builds on CI, copy the new .vcvplugin files into the publish dir and refresh the cards/links in both HTML copies:

# from a checkout, with the release tag's artifacts downloaded e.g. via:
#   gh release download v0.2.0 -p '*.vcvplugin' -D /tmp/vcvrel
PUB=/home/w1n5t0n/deployments/meml-aimmersive/next/vcv
cp /tmp/vcvrel/*.vcvplugin "$PUB"/
# then edit $PUB/index.html: flip the win/mac cards from "built by CI"
# (.dl.disabled) to live download links, and copy index.html -> a-immersive.html:
cp "$PUB/index.html" "$PUB/a-immersive.html"

Bumping the version means updating the v0.2.0 strings and the filenames in the two HTML copies. Keep index.html and a-immersive.html identical.

Verify

curl -sk -o /dev/null -w '%{http_code}\n' https://meml.lnfinitemonkeys.org/next/vcv/
curl -sk -o /dev/null -w '%{http_code}\n' \
  https://meml.lnfinitemonkeys.org/next/vcv/MEMLNaut-0.2.0-lin-x64.vcvplugin

Both should return 200. Don't disturb /next/, /next/animations/, or the live a-immersive at /.