Troubleshooting

zig build fails with undefined libc symbols

Zig 0.14.1 cannot link against the SDK shipped with Xcode 26. Either use Zig 0.15.2 or install an older SDK. Setting SDKROOT does not help, because the SDK itself is the incompatibility.

Check which SDK you have:

xcodebuild -version
xcrun --show-sdk-path

lipo -info reports only one architecture

You looked at zig-out/lib/libDanzigGain.dylib, which is the native-only build. The universal binary is inside the bundle:

lipo -info zig-out/DanzigGain.vst3/Contents/MacOS/DanzigGain

If the bundle itself is single-architecture, zig build vst3 did not run. zig build alone does not produce the bundle.

The DAW does not list the plugin

The plugin validates (see Current state), so a missing entry is usually the host's cache or the install location rather than the bundle. First confirm the factory symbol is exported:

nm -gU zig-out/DanzigGain.vst3/Contents/MacOS/DanzigGain | grep -i factory

00000000000004c8 T _GetPluginFactory

Then check the bundle is in ~/Library/Audio/Plug-Ins/VST3/ (see Install it) and force the host to rescan its plugin list. Many hosts cache a failed scan, so a bundle fixed after a first bad scan stays hidden until the cache is cleared. Validate the copy directly with pluginval to rule the bundle in or out:

/Applications/pluginval.app/Contents/MacOS/pluginval \
  --validate ~/Library/Audio/Plug-Ins/VST3/DanzigGain.vst3 --strictness-level 5

danzig-webui starts but the browser shows nothing

The server binds 127.0.0.1:3000. If something else already holds that port you will reach the other service instead. Check with:

lsof -nP -iTCP:3000 -sTCP:LISTEN

The port is a constant in examples/danzig-webui/root.zig. Change it and rebuild.

danzig-webui exits with an error about ui/index.html

It reads the UI from a relative path at startup, so it has to be run from the repository root:

cd /path/to/danzig
./zig-out/bin/danzig-webui

danzig-gain-standalone rejects the input file

It handles 32-bit float PCM WAV only, with a canonical 44-byte header. Anything else gives Only 32-bit float PCM WAV files are supported. To make a test file without extra tools:

python3 - <<'PY'
import struct, math
sr, n, ch = 48000, 48000, 1
data = b''.join(struct.pack('<f', 0.5 * math.sin(2 * math.pi * 440 * i / sr)) for i in range(n))
hdr = struct.pack('<4sI4s4sIHHIIHH4sI', b'RIFF', 36 + len(data), b'WAVE', b'fmt ',
                  16, 1, ch, sr, sr * ch * 4, ch * 4, 32, b'data', len(data))
open('sine.wav', 'wb').write(hdr + data)
PY

The GUI example does not build

It needs the webview dependency, which Zig fetches lazily. Run zig build once with a network connection. On macOS it also links CoreAudio and CoreFoundation, so the command line tools must be installed.

zig build -Dtarget=... fails on webviewStatic

error: unable to find framework 'WebKit'. searched paths:  none

The GUI example's webview dependency is C++ and links WebKit, which does not cross-compile. The Zig code does cross-compile fine, which is why zig build vst3 produces both architectures. Build the library and the non-GUI examples for another target directly, or build natively.

AtomicParam must be 64 bytes for cache line alignment

You added or resized a field in AtomicParam without adjusting _pad. Shrink _pad by the number of bytes you added. The check is there on purpose. See Why exactly one cache line.

A parameter change clicks

The parameter has no smoothing. Pass a non-zero smooth_ms to add:

_ = store.add(-24.0, 24.0, 0.5, 20.0, sample_rate);
//                                ^^^^ 20 ms one-pole ramp

Then read it with tick inside the per-sample loop rather than once per block.