Repository navigation
Building and Bundling
Corrosion ships as two plugin formats (VST3 and CLAP) on three platforms (Linux, Windows, macOS), plus a web app. All of them come from one Rust library crate, corrosion, built as a cdylib: the same shared library, placed in the folder layout each format and platform expects. This page covers the build targets, how scripts/bundle.sh lays out the bundles, how they are checked and validated, the full local check script, the third-party notices, the vendored and patched crates, the editor's font files, and how to check the plugin in REAPER from a headless Linux session.
CI runs the same scripts; see CI and Releases. The repository's directories are mapped on Repository Layout.
.cargo/config.toml is written for the maintainer's Windows machine, which has the MinGW-w64 GCC toolchain and no MSVC:
| Setting | Value | Effect |
|---|---|---|
[build] target |
x86_64-pc-windows-gnu |
Every cargo command builds for Windows GNU unless told otherwise |
[build] target-dir |
../corrosion-target |
Build output goes next to the repository, not inside it |
[target.x86_64-pc-windows-gnu] linker |
x86_64-w64-mingw32-gcc |
The MinGW linker |
[target.x86_64-unknown-linux-gnu] linker |
gcc |
|
[target.x86_64-unknown-linux-musl] |
rust-lld, -C link-self-contained=yes
|
A static musl build without a musl toolchain installed |
On any other machine, set your host target first, or every build tries to cross-compile to Windows:
export CARGO_BUILD_TARGET=x86_64-unknown-linux-gnu # aarch64-apple-darwin, x86_64-pc-windows-msvc, …The environment variable overrides the config file. CI also sets CARGO_TARGET_DIR to target/ inside the workspace so its cache can keep it.
Other build facts:
-
Toolchain: stable Rust 1.99 or newer.
src/lib.rsallows the lintsemicolon_in_expressions_from_non_local_macros, which older compilers reject under-D warnings. -
Features (
Cargo.toml):default = ["gui"]builds the egui editor (and the native file dialogs,rfd).--no-default-featuresbuilds the engine only, which is what the CI test lane, the benchmarks and the offline tools use.web-hostandweb-guibuild only inside theweb/workspace; see Web App. -
Linux GUI builds need the X11 and GL development packages (
pkg-config libx11-dev libx11-xcb-dev libxau-dev libxcb1-dev libxcursor-dev libxext-dev libxfixes-dev libxft-dev libxi-dev libxinerama-dev libxkbcommon-dev libxrandr-dev libxrender-dev libxtst-dev libxxf86vm-dev libgl-dev). -
Binaries: besides the library, the crate has five command-line tools under
src/bin/:renderandrender_presets(Testing),seed_presets(Factory Bank),export_guide_dataandrender_guide_clips(Site and User Wiki Tooling).
A host doesn't load a bare .so or .dll: VST3 wants a bundle directory with a fixed inner layout, and on macOS both formats are bundles with an Info.plist. bundle.sh builds the library and arranges it.
scripts/bundle.sh <linux|windows|macos> [release|debug]flowchart LR
B["cargo build --lib --target T<br/>(release by default)"] --> LIB["libcorrosion.so / corrosion.dll /<br/>libcorrosion.dylib"]
LIB --> L["linux:<br/>Corrosion.vst3/Contents/x86_64-linux/Corrosion.so<br/>Corrosion.clap"]
LIB --> W["windows:<br/>Corrosion.vst3/Contents/x86_64-win/Corrosion.vst3<br/>Corrosion.clap"]
LIB --> M["macos: arm64 + x86_64 → lipo<br/>Corrosion.vst3/Contents/MacOS/Corrosion<br/>Corrosion.clap/Contents/MacOS/Corrosion<br/>+ Info.plist, PkgInfo, ad-hoc codesign"]
| Platform | Target(s) | Output in target/bundled/<platform>/
|
|---|---|---|
linux |
x86_64-unknown-linux-gnu |
Corrosion.vst3/Contents/x86_64-linux/Corrosion.so; Corrosion.clap is the same library renamed |
windows |
x86_64-pc-windows-msvc (what CI ships); set CORROSION_WINDOWS_TARGET=x86_64-pc-windows-gnu for the MinGW build |
Corrosion.vst3/Contents/x86_64-win/Corrosion.vst3 (the DLL); Corrosion.clap is the same DLL |
macos |
aarch64-apple-darwin and x86_64-apple-darwin
|
Both libraries joined by lipo into one universal binary, copied into Corrosion.vst3/Contents/MacOS/Corrosion and Corrosion.clap/Contents/MacOS/Corrosion, each with an Info.plist (bundle ID com.corrosion.corrosion.<format>, version from Cargo.toml) and PkgInfo, then ad-hoc signed with codesign --sign -
|
Notes:
- The library is looked up under
$CARGO_TARGET_DIR, or../corrosion-targetwhen that is unset, but the bundles always go totarget/bundled/<platform>/inside the repository. The script deletes that folder first. - macOS bundles are ad-hoc signed, not notarized: Apple Silicon refuses to load unsigned code, but Gatekeeper still quarantines a downloaded bundle. The release notes tell users to clear the quarantine attribute.
- One library is both formats because nih-plug's export macros put the VST3 and CLAP entry points in the same binary.
-
scripts/archive/keeps two thin wrappers for old habits:bundle.sh(runsscripts/bundle.sh linux) andbundle-win.sh(runs it forwindowswith the GNU target). Usescripts/bundle.shdirectly.
scripts/check_bundle.sh <linux|windows|macos> [dir]It checks each file sits where hosts look for it and is the right kind of binary (by file): ELF 64-bit … shared object on Linux, PE32+ executable … DLL on Windows, Mach-O universal binary on macOS. On macOS it also requires both arm64 and x86_64 slices (lipo -archs), an Info.plist and a PkgInfo, and a strict codesign --verify. It exits non-zero on the first failure, naming it.
scripts/validate-plugins.sh [linux|windows|macos] [dir]The platform defaults to the host's (by uname). If the bundles are missing it builds them first. Then:
-
pluginval (Tracktion's plugin validator) loads the VST3 at strictness level 5 with
--skip-gui-tests; -
clap-validator (free-audio's) runs
validateon the CLAP.
A validator missing from PATH is skipped with a message, unless CORROSION_REQUIRE_VALIDATORS=1, which CI sets so a missing tool is an error. CI pins clap-validator 0.3.2 and pluginval v1.0.4, and on Linux runs pluginval under xvfb-run because JUCE wants a display even without GUI tests. Locally, put the validators' executables on PATH from their GitHub releases.
One command that mirrors most of CI on a Linux machine. It stops at the first failure:
cargo fmt --checkpython3 scripts/third_party_notices.py --checkcargo clippy --workspace --all-targets --no-default-features -- -D warnings-
cargo test --workspace --no-default-features(the CI lane) -
cargo test --lib --target x86_64-unknown-linux-gnu(the GUI lane) -
render --suite familyinto/tmp/corrosion-local-verify-render, thencheck_wav.pyonpipe_comparison.wav -
scripts/bundle.sh linux releaseandscripts/check_bundle.sh linux
Steps 1–4 and 7 use whatever target CARGO_BUILD_TARGET says, so export it first. It doesn't run cargo doc, the explicit no_alloc step (the CI lane includes tests/no_alloc.rs anyway, in debug), the validators or the web and user-Wiki checks. The other checks are listed on Testing.
Corrosion is GPLv3-or-later and ships other people's code: about 270 crates, fonts, vendored crates, generated files. Their licenses ask for their notices to travel with the binaries, so THIRD-PARTY-NOTICES.md collects them, and CI copies it into every release zip next to LICENSE.
| Section | Written by | Holds |
|---|---|---|
| 1. Material in this repository | Hand | The OpenSpec-generated skills and commands under .claude/ and .opencode/, vendor/nih_log, the editor fonts, vendor/egui-baseview, the NIH-plug patch the web build applies |
| 2. The website | Hand | The npm packages whose client code the site ships (Astro, Starlight, Expressive Code, Pagefind) |
| 3. Trademarks | Hand | VST and CLAP |
| 4. Rust crates | scripts/third_party_notices.py |
Between <!-- BEGIN GENERATED … --> and <!-- END GENERATED -->: a table of every shipped crate, then each distinct license text once with the crates it covers |
flowchart TB
F["web/scripts/fetch-nih-plug.sh<br/>(patched NIH-plug for the web workspace)"] --> M
M["cargo metadata --locked --filter-platform T<br/>per workspace and target"] --> W["Walk normal (non-dev, non-build)<br/>dependencies from the root packages"]
W --> C{"License on ALLOWED?<br/>Crate in FORBIDDEN?"}
C -->|no / yes| X["Fail, naming the crate"]
C -->|ok| T["Collect license files<br/>(or repository root, or standard text)"]
T --> G["Group identical texts,<br/>write between the markers"]
G --> K{"--check?"}
K -->|yes| D["Fail if the file would change"]
K -->|no| WR["Rewrite the file"]
- It runs
web/scripts/fetch-nih-plug.shfirst, because the web workspace's dependency graph points at a patched NIH-plug inweb/vendor/nih-plug. - For each workspace and target it runs
cargo metadata --locked --filter-platform <target>: the root workspace forcorrosiononx86_64-unknown-linux-gnu,x86_64-pc-windows-msvc,x86_64-pc-windows-gnu,x86_64-apple-darwinandaarch64-apple-darwin; thewebworkspace forcorrosion-web-engineandcorrosion-web-editoronwasm32-unknown-unknown. The list is the union, so a crate may ship on only some targets. - It walks the normal-dependency closure from the root packages (dev and build dependencies don't ship), leaving out Corrosion's own packages.
- Each crate's SPDX expression must use only identifiers in
ALLOWED, a GPLv3-compatible allowlist (MIT, Apache-2.0, BSD variants, ISC, Zlib, MPL-2.0, Unicode, BSL-1.0, CC0, GPL-3.0 and a few more). A crate inFORBIDDENfails the run: today onlyepaint_default_fonts, egui's built-in fonts, which the editor replaces with its own. - License texts come from the crate's own files (
LICENSE*,COPYING*,NOTICE*, …). A crate published without one gets its git repository root's license files when the root declares the same license, otherwise the standard MIT, ISC or BSL text with the authors from itsCargo.toml; those crates are listed in their own subsection. - Texts that differ only in whitespace (and
httpvshttps) are grouped and printed once. Apache-2.0 copies are cut at "END OF TERMS AND CONDITIONS", since copies differ only in the appendix.
python3 scripts/third_party_notices.py # rewrite section 4
python3 scripts/third_party_notices.py --check # fail if it is staleIt needs the network or a warm Cargo cache. Rerun it after any change to Cargo.lock or web/Cargo.lock, cargo update included, and commit the result. CI's web job and verify-local.sh run --check. If a new license fails the allowlist, ask the maintainer; don't widen ALLOWED yourself. Third-party material that isn't a crate (vendored code, fonts, generated files, site code) needs a hand-written entry in sections 1–3.
Two dependencies are carried as local copies with one change each, wired in through [patch] sections of the root Cargo.toml. Each folder's PATCHED.md says what was taken from where, the one change, and when to drop the copy.
| Copy | Upstream | The change | Why | Patched in |
|---|---|---|---|---|
vendor/nih_log |
nih_log 0.3.1 at 0f3819a (ISC) |
atty removed: src/target.rs uses std::io::stderr().is_terminal()
|
atty is unmaintained and has an open advisory (RUSTSEC-2021-0145) |
[patch.crates-io] in Cargo.toml and web/Cargo.toml
|
vendor/egui-baseview |
egui-baseview 0.5.0 at ec70c3f, the revision nih_plug_egui pins (MIT) |
default_fonts is no longer a default feature (default = ["opengl"]); src/ untouched |
nih_plug_egui enables egui-baseview's defaults, which would embed egui's default fonts in every binary |
[patch."https://github.com/BillyDM/egui-baseview.git"] in Cargo.toml
|
Trap: if NIH-plug moves to another egui-baseview revision, the patch no longer matches and egui's fonts come back. The notices script's FORBIDDEN check then fails, which is the intended alarm: refresh the copy from the new revision and reapply the change.
The web workspace also patches NIH-plug itself, with web/nih-plug-public-setters.patch applied by web/scripts/fetch-nih-plug.sh to a clone at the revision Cargo.lock pins; see Web App.
The editor and the web app embed two font files, unmodified, both under the SIL Open Font License 1.1 with their license texts beside them:
| File | Font | Used for |
|---|---|---|
Inter-Regular.ttf |
Inter 4.1 Regular | The whole interface |
IBMPlexSans-SemiBold.ttf |
IBM Plex Sans 1.1.0 SemiBold | The brand block in the header |
assets/fonts/README.md records each file's source release. IBM Plex Sans carries the Reserved Font Name "Plex", so a modified copy may not keep the name: don't subset or edit it. A third font, Corrosion Icons (the triangles egui draws on submenus), is built in code by icon_font() in src/gui/fonts.rs and has no file. Changing a font means replacing the file and updating the README's table, the cap-height notes behind UI_EM_SCALE in src/gui/fonts.rs, and section 1 of the notices. How the fonts are loaded and scaled is on Editor.
The development sessions run in a Linux container with no screen and no audio device. docs/REAPER_TESTING.md is the step-by-step recipe for checking the editor in a real host there anyway; it takes about five minutes to set up, everything lives under /tmp/claude-0/, and a recycled container loses it.
-
Display: Xorg with the
dummyvideo driver on:98at 1920 × 1200. Not Xvfb: egui needs an OpenGL context, and only the dummy driver with Mesa gave one. -
REAPER: the Linux tarball, run unpacked, in evaluation mode. A
__startup.luascript inserts a track, addsCLAP: Corrosion, opens its window and logs what it found. -
A screenshot build: the dummy server has no sRGB framebuffer config, so the normal editor fails with
InvalidFBConfig. Build from a separate worktree whoseCargo.tomlpatches NIH-plug to a local clone (at the pinned revision) withsrgb: falseinnih_plug_egui's editor. This build is only for screenshots; colours differ slightly. -
Install the library as
~/.clap/Corrosion.clap, start REAPER, and drive it withxdotool(clicks, drags, scrolls, typing, the computer keysA W S E D F T G Y H U J K), taking screenshots with ImageMagick'simport. At the default 75 % UI Scale the plugin window is 810 × 658 including REAPER's title bar. -
Other actions (save and reopen a project, read a parameter) go through Lua scripts run with
reaper -nonewinst.
Limits: nothing can be heard (no audio device; check sound with the offline renderer and the tests), it says nothing about Windows or macOS hosts, and none of it is automated in CI. The scripts in tests/daw/ are early placeholders, not this recipe; see Testing.
-
scripts/bundle.sh: builds and lays out the VST3 and CLAP bundles per platform -
scripts/check_bundle.sh: checks the bundle layout, binary kind, architectures and signature -
scripts/validate-plugins.sh: runs pluginval and clap-validator -
scripts/verify-local.sh: the full local lane -
scripts/third_party_notices.py: generates and checks section 4 of the notices -
THIRD-PARTY-NOTICES.md: the notices that ship with every release -
docs/REAPER_TESTING.md: the REAPER recipe for headless Linux sessions -
.cargo/config.toml: default target, target directory and linkers -
scripts/archive: old bundling wrappers kept for habit -
vendor/nih_log/PATCHED.md: what the nih_log copy changes and why -
vendor/egui-baseview/PATCHED.md: what the egui-baseview copy changes and why -
assets/fonts/README.md: the editor's font files and their sources -
Cargo.toml: features, binaries, per-target dependencies and the[patch]sections -
web/scripts/fetch-nih-plug.sh: the patched NIH-plug the notices script and the web build need
Corrosion Internals is generated from docs/internals/ in the repository. Edits made here are overwritten on the next publish: change the pages there, in a pull request.
Start
Plugin
Engine
- Modal resonator
- Objects
- Exciters
- Hit exciters
- Friction exciters
- Specialty exciters
- Interaction bus and contact
- Envelopes and modulation
- Material transformations
- DSP utilities
- Sample-rate rule
Post chain
State
Front ends
Quality
Process