Build and run Oscyl
This guide builds and runs the desktop app and the command line tool on each system. For the Android and iOS apps, see Build, run and test the mobile apps.
Every system needs Rust 1.92 or newer, through rustup.
Linux: the desktop app and the command line
-
Install the development packages of GTK 4.20 or newer, libadwaita 1.8 or newer, ALSA (
alsa-lib) and gettext. -
Run the app or the command line:
cargo run -p oscyl-gtk # the desktop app cargo run -p oscyl-gtk -- --simulator # with simulated synths cargo run -p oscyl-cli -- --help # the command line tool cargo run -p oscyl-cli -- --simulator info # try it without a synth -
Connect the synth over USB. Oscyl finds its port by name.
To build the Flatpak, see packaging/flatpak.
macOS and Windows: the command line
Rust is all that you need:
cargo run -p oscyl-cli -- --help
macOS: the desktop app
-
Install the libraries with Homebrew:
brew install pkgconf gtk4 libadwaita gettext adwaita-icon-theme -
Run the app:
GETTEXT_DIR="$(brew --prefix gettext)" cargo run -p oscyl-gtk -- --simulator
To make Oscyl.app, also install dylibbundler and librsvg, then run:
GETTEXT_DIR="$(brew --prefix gettext)" cargo build --release -p oscyl-gtk
packaging/desktop/bundle-macos.sh target/release/oscyl-gtk 0.0.0 dist
The release’s Oscyl.app is signed ad hoc but not notarised, so macOS
refuses to open it the first time. Do one of these:
- In Finder, Control-click the app, choose Open, then choose Open in the dialog.
- On macOS 15 and later, try to open the app. Then go to System Settings, Privacy & Security, and choose Open Anyway.
- Clear the quarantine flag:
xattr -dr com.apple.quarantine Oscyl.app.
macOS has no hotplug yet. If you plug the synth in after Oscyl starts, choose Connect.
Windows: the desktop app
-
In an MSYS2 UCRT64 shell, install the toolchain and the libraries:
pacman -S --needed mingw-w64-ucrt-x86_64-{toolchain,rust,pkgconf,gtk4,libadwaita,gettext-tools} -
Run the app:
cargo run -p oscyl-gtk -- --simulator
To make the folder that a release ships (bin/Oscyl.exe runs it):
cargo build --release -p oscyl-gtk
packaging/desktop/bundle-windows.sh target/release/oscyl-gtk.exe "$MSYSTEM_PREFIX" dist/Oscyl
To make the installer from that folder, install
mingw-w64-ucrt-x86_64-nsis, then run:
eval "$(scripts/version.sh)"
makensis -DVERSION="$version" -DNUMERIC="$marketing" -DSRC="$(cygpath -w "$PWD/dist/Oscyl")" \
-DOUT="$(cygpath -w "$PWD/dist/oscyl-setup.exe")" packaging/desktop/oscyl.nsi
The installer is for the current user only, and needs no admin rights. It
puts Oscyl in %LOCALAPPDATA%\Programs\Oscyl and adds it to the Start
menu. To remove Oscyl, open Settings > Apps > Installed apps, choose Oscyl,
then choose Uninstall. Your settings and libraries stay.
You can also build the Windows app on Linux:
- Install
mingw-w64-gcc. - Unpack the same MSYS2 packages into a directory.
- Point
PKG_CONFIG_SYSROOT_DIR,PKG_CONFIG_LIBDIRandMSYSTEM_PREFIXinto it, and setPKG_CONFIG_ALLOW_CROSS=1. - Run
cargo build -p oscyl-gtk --target x86_64-pc-windows-gnu.
The installer and the app are not signed, so SmartScreen can warn the first time you run one of them. Choose More info, then Run anyway. As on macOS, if you plug the synth in after Oscyl starts, choose Connect.
To try the app on a Windows PC with a synth, from Linux, see Test on Windows hardware from Linux.
The optional tools of the checks
scripts/ci.sh uses these tools when they are installed, and skips their
stages when they are not. Run the checks says what
each stage does.
- actionlint and zizmor: the workflows.
- Ruby: the issue forms.
- typos: spelling.
- cargo-deny: the licences
and advisories of the dependencies (
cargo install cargo-deny --locked). - mdBook, Vale and lychee: the book, its prose and its links.
scripts/docs-tools.sh DIRdownloads the versions that CI uses, for x86_64 Linux.