Skip to content

ci_desktop_builds.md

Latest commit

 

History

History
108 lines (97 loc) · 6.86 KB

ci_desktop_builds.md

File metadata and controls

108 lines (97 loc) · 6.86 KB

Desktop CI: loud, literal, and future-proof

This repo already runs PlatformIO tests; the new desktop CI keeps the JUCE side honest. Think of it as a backstage checklist taped to the amp: clear about what we build, which arch we aim at, and how to debug it if something pops.

What each workflow does

  • Starter bundle smoke. Runs ./scripts/starter_bundle.sh on Ubuntu so the documented newcomer path (pio pkg install + pio test -e native) stays executable in CI.
  • macOS universal (x86_64 + arm64). Builds both the VST3 bundle (explicitly drives the format-specific SeedboxVST3_VST3 target so the actual plugin binary exists) and the standalone app from the same CMake tree with CMAKE_OSX_ARCHITECTURES="x86_64;arm64" on the macOS 14 runner. The runner stays on macOS 14 for CI stability, but the repo currently pins JUCE 8.0.12, which already includes JUCE's macOS 26 support work, so local Tahoe builds can target the current SDKs cleanly. The deployment target remains 11.0 so both Intel and Apple Silicon hosts stay happy, and we upload the bundled artifacts so testers can drag-drop without a local toolchain. CI now hunts for the VST3 bundle with find and then hunts for the actual binary inside the bundle before running lipo, so we catch staging-layout changes instead of bombing out with a missing file—feel free to use the same trick locally when JUCE shuffles its output folders. We also flip JUCE_VST3_CAN_REPLACE_VST2=OFF so JUCE skips the legacy VST2 compatibility shim and never chases Steinberg’s archived VST2 headers during a VST3-only build. The repo’s CMakeLists.txt also bakes in JUCE_VST3_CAN_REPLACE_VST2=0 and JUCE_PLUGINHOST_VST=0 for the plugin targets, so local builds inherit the same VST3-only posture even if you forget to pass the flag by hand.
  • Linux host dependency sweep. Installs JUCE’s usual suspects (libx11-dev, libgtk-3-dev, libwebkit2gtk-4.1-dev, pkg-config, etc.), configures the JUCE targets, and builds both the plugin and the app to ensure the headers and pkg-config hints stay lined up. We set JUCE_USE_CURL=0 in the CMake targets and workflows so JUCE never tries to pull in libcurl on CI (too many distros ship it without the dev bits), but you can still re-enable it locally if you need HTTP in a custom host harness. We also export a PKG_CONFIG_PATH that points at the default /usr/lib/x86_64-linux-gnu and /usr/share/pkgconfig roots and run pkg-config --cflags --libs gtk+-3.0 explicitly so broken GTK discovery fails fast instead of puzzling you with a missing gtk/gtk.h 15 minutes into a build.
  • Windows host dependency sweep. Leans on the Visual Studio toolchain that GitHub Actions ships with (explicitly boots the MSVC developer command prompt), layers Ninja on top, and drives the same CMake targets so we know JUCE + Windows stay in lockstep with the rest of the project.

Current verification matrix

Surface What CI proves What still needs a human
Starter bundle The documented native newcomer path runs on Ubuntu A human still decides whether the docs feel legible
Native golden Golden fixtures can be regenerated, hashed, staged, and uploaded A human still listens for musical intent when a fixture changes
macOS JUCE Universal app + VST3 build, bundle layout, and binary slices are present Manual host playback and UI smoke on a real Mac/DAW
Linux JUCE Dependency discovery and app + VST3 build stay wired up Manual runtime checks on the target distro/audio stack
Windows JUCE MSVC/Ninja build and artifact staging stay healthy Manual runtime checks in actual Windows hosts

For those manual runtime passes, use docs/JUCESmokeChecklist.md.

Tips for running these steps locally

  • macOS universal builds: pass -DCMAKE_OSX_ARCHITECTURES="x86_64;arm64" when configuring and remember to build the format-specific target (cmake --build build/juce --target SeedboxVST3_VST3) so the bundle actually contains a binary. lipo -info on the VST3 binary inside the bundle should list both architectures. On CI we still use the macOS 14 runner, but local Tahoe builds with the pinned JUCE are valid too; a current SDK should stamp the resulting binary with sdk 26.x while keeping the configured deployment target. Resist the urge to override the VST3 target’s output directories—the JUCE helper that writes moduleinfo.json expects the default bundle layout (.../SeedBox.vst3/Contents/...), and short-circuiting that with custom RUNTIME_OUTPUT_DIRECTORY values will trick it into treating the naked .so as a bundle and erroring out.
  • Linux builds: if you hit missing X11/WebKit dev packages, mirror the apt-get list from the workflow (note the libwebkit2gtk-4.1-dev rename and the explicit pkg-config install on Ubuntu 24.04) and rerun CMake out-of-tree (cmake -S . -B build/juce -G Ninja ...). If GTK/WebKit still refuse to show up, echo the CI trick locally: set PKG_CONFIG_PATH=/usr/lib/x86_64-linux-gnu/pkgconfig:/usr/share/pkgconfig and run pkg-config --cflags --libs gtk+-3.0 plus pkg-config --cflags --libs webkit2gtk-4.1—you should see include paths like -I/usr/include/gtk-3.0 and -I/usr/include/webkitgtk-4.1. No output? Install the packages or add the matching pkg-config search path before blaming JUCE. If CMake still pretends GTK/WebKit do not exist, bolt the pkg-config output straight into your configure line with -DCMAKE_CXX_FLAGS_INIT="$(pkg-config --cflags gtk+-3.0 webkit2gtk-4.1)" and -DCMAKE_SHARED_LINKER_FLAGS_INIT="$(pkg-config --libs gtk+-3.0 webkit2gtk-4.1)"— it’s loud but guarantees JUCE compiles against the headers we just installed. We ship with JUCE_USE_CURL=0 baked in to dodge missing libcurl-dev packages; flip it back on if you explicitly need HTTP support in your host harness. Do the same with -DJUCE_VST3_CAN_REPLACE_VST2=OFF if you see VST2 header errors; that flag intentionally disables the “VST3 can replace VST2” compatibility path so we never need the VST2 SDK to ship a VST3. (It’s already wired into the plugin targets in CMakeLists.txt, but adding it to your ad-hoc configure lines keeps third-party build scripts honest.)
  • Windows builds: open a "x64 Native Tools" shell before running CMake (or run vcvarsall.bat x64 in PowerShell) to inherit the MSVC environment, then reuse the same flags as the workflow.

Why bother

Desktop builds are our glue between the firmware world and DAWs. Keeping these workflows green means:

  • VST drops are always reproducible from CI instead of mythical local setups.
  • Dependency churn on Linux/Windows gets caught early instead of during a live demo.
  • The macOS universal artifact doubles as a teaching bundle: unzip, drop into a host, and you’re hearing the latest commit with zero extra steps.