182 lines
6.7 KiB
Markdown
182 lines
6.7 KiB
Markdown
# Building
|
|
|
|
This document describes how to build Cardinal from source,
|
|
if you rather use Cardinal pre-built binaries please check [this wiki page](https://github.com/DISTRHO/Cardinal/wiki/Install) instead.
|
|
|
|
Before you begin, make sure you have the needed tools installed to build code, such as gcc or clang.
|
|
How to install those for your system is a bit outside the scope of this document.
|
|
It is expected you generally know how to build software by yourself.
|
|
|
|
Worth noting that, if cloning Cardinal from git, use of submodules is required.
|
|
So either clone with `--recursive` or use `git submodule update --init --recursive` after cloning.
|
|
If you are building from a release tarball you do not need to care about git.
|
|
|
|
## Build options
|
|
|
|
Cardinal uses [GNU Make](https://www.gnu.org/software/make/) as build system.
|
|
So you just got to run `make` within the Cardinal main directory in order to build.
|
|
|
|
There are a few useful options you can pass as arguments when building though.
|
|
Use them as `make SOMEOPTION=SOMEVALUE` syntax. You can specify as many options as you want.
|
|
|
|
Developer related options:
|
|
|
|
* `DEBUG=true` build non-stripped debug binaries (terrible performance, only useful for developers)
|
|
* `NOPLUGINS=true` build only the Cardinal Core plugins (not recommended, only useful for developers)
|
|
|
|
Packaging related options:
|
|
|
|
* `DESTDIR=/path` typical extra install target path (if you are used to packaging, this does what you expect)
|
|
* `PREFIX=/usr` prefix used for installation (note that it **must** be set during build time as well)
|
|
* `NOOPT=true` do not automatically set well-known optimization flags
|
|
* `SKIP_STRIPPING=true` do not automatically strip the binaries
|
|
* `SYSDEPS=true` use jansson, libarchive, samplerate and speexdsp system libraries, instead of vendored
|
|
* `WITH_LTO=true` enable Link-Time-Optimization, which has performance benefits but significantly increases the build time
|
|
|
|
Advanced options:
|
|
|
|
* `HEADLESS=true` build headless version (without gui), useful for embed systems
|
|
* `STATIC_BUILD=true` skip building Cardinal core plugins that use local resources (e.g. audio file and plugin host)
|
|
|
|
The commonly used build environment flags such as `CC`, `CXX`, `CFLAGS`, etc are respected and used.
|
|
|
|
## FreeBSD
|
|
|
|
The use of vendored libraries doesn't work on FreeBSD, as such the `SYSDEPS=true` build option is automatically set.
|
|
This means some dependencies that are optional in other systems are required under FreeBSD.
|
|
|
|
The use of `gmake` instead of `make` is also required.
|
|
|
|
Dependencies for using system libraries:
|
|
|
|
```
|
|
# common
|
|
sudo pkg install -A dbus libglvnd liblo libsndfile libX11 libXcursor libXext libXrandr python3
|
|
# system libraries
|
|
sudo pkg install -A libarchive libsamplerate jansson speexdsp
|
|
```
|
|
|
|
## Linux
|
|
|
|
There are a few differences between Linux distributions, this document covers the most common ones.
|
|
Adjust as needed if your distribution is not based on one of these.
|
|
|
|
### ArchLinux
|
|
|
|
Dependencies for using system libraries, that is, with `SYSDEPS=true`:
|
|
|
|
```
|
|
# common
|
|
sudo pacman -S dbus file libgl liblo libsndfile libx11 libxcursor libxext libxrandr python3
|
|
# system libraries
|
|
sudo pacman -S libarchive libsamplerate jansson speexdsp
|
|
```
|
|
|
|
Dependencies for vendored libraries:
|
|
|
|
```
|
|
# common
|
|
sudo pacman -S dbus file libgl liblo libsndfile libx11 libxcursor libxext libxrandr python3
|
|
# nedeed by vendored libraries
|
|
sudo pacman -S cmake wget
|
|
```
|
|
|
|
### Debian
|
|
|
|
Dependencies for using system libraries, that is, with `SYSDEPS=true`:
|
|
|
|
```
|
|
# common
|
|
sudo apt install libdbus-1-dev libgl1-mesa-dev liblo-dev libmagic-dev libsndfile1-dev libx11-dev libxcursor-dev libxext-dev libxrandr-dev python3
|
|
# system libraries
|
|
sudo apt install libarchive-dev libjansson-dev libsamplerate0-dev libspeexdsp-dev
|
|
```
|
|
|
|
Dependencies for vendored libraries:
|
|
|
|
```
|
|
# common
|
|
sudo apt install libdbus-1-dev libgl1-mesa-dev liblo-dev libmagic-dev libsndfile1-dev libx11-dev libxcursor-dev libxext-dev libxrandr-dev python3
|
|
# nedeed by vendored libraries
|
|
sudo apt install cmake wget
|
|
```
|
|
|
|
## macOS
|
|
|
|
Installing Xcode and the "Command-Line utilities" add-on is required.
|
|
Additionally you will need `python3` and `wget` from either Homebrew or MacPorts, whatever you prefer.
|
|
You can also install libsndfile in order to make Cardinal's audio file module work. (Otherwise it will support only mp3 files)
|
|
|
|
If you want to have universal builds similar to the ones officially published by Cardinal, simply setup the environment like this:
|
|
|
|
```
|
|
export CFLAGS="-DMAC_OS_X_VERSION_MAX_ALLOWED=MAC_OS_X_VERSION_10_12 -mmacosx-version-min=10.12 -arch x86_64 -arch arm64"
|
|
export CXXFLAGS="${CFLAGS}"
|
|
# make etc..
|
|
```
|
|
|
|
## Windows
|
|
|
|
Cardinal does not support msvc, using mingw is required.
|
|
You can either cross-compile Cardinal for Windows from Linux, or install and use msys2 natively on a Windows system.
|
|
|
|
### Cross-compile
|
|
|
|
For cross-compilation, first install the relevant mingw packages.
|
|
On Ubuntu these are `binutils-mingw-w64-x86-64 g++-mingw-w64-x86-64 mingw-w64`.
|
|
Then build with `CC` and `CXX` pointing to the mingw compiler, like so:
|
|
|
|
```
|
|
export CC=x86_64-w64-mingw32-gcc
|
|
export CXX=x86_64-w64-mingw32-g++
|
|
# make etc..
|
|
```
|
|
|
|
# Installing
|
|
|
|
After a successful build you will find the plugin binaries in the `bin/` directory.
|
|
You can either install them to your system using e.g. `make install PREFIX=/some/prefix` (not recommended for local source builds)
|
|
or preferably just create a symbolic link on the respective plugin format folders.
|
|
|
|
Cardinal plugin binaries expect to remain *within* their parent bundle/folder.
|
|
If you move them around make sure to keep their folder structure intact.
|
|
|
|
If you are a packager you pretty much already know what to do at this point, otherwise regular users might want to do something like:
|
|
|
|
```
|
|
mkdir -p ~/.lv2 ~/.vst ~/.vst3
|
|
ln -s $(pwd)/bin/*.lv2 ~/.lv2/
|
|
ln -s $(pwd)/bin/*.vst ~/.vst/
|
|
ln -s $(pwd)/bin/*.vst3 ~/.vst3/
|
|
```
|
|
|
|
## macOS
|
|
|
|
If running macOS, use this instead:
|
|
|
|
```
|
|
mkdir -p ~/Library/Audio/Plug-Ins/LV2 ~/Library/Audio/Plug-Ins/VST ~/Library/Audio/Plug-Ins/VST3
|
|
ln -s $(pwd)/bin/*.lv2 ~/Library/Audio/Plug-Ins/LV2/
|
|
ln -s $(pwd)/bin/*.vst ~/Library/Audio/Plug-Ins/VST/
|
|
ln -s $(pwd)/bin/*.vst3 ~/Library/Audio/Plug-Ins/VST3/
|
|
```
|
|
|
|
Note: Official macOS Cardinal builds install in the system-wide `/Library/Audio/Plug-Ins` location.
|
|
Watch out for conflicts if switching between the two builds.
|
|
|
|
## Windows
|
|
|
|
Symbolic links are not supported on Windows, so this approach doesn't work there.
|
|
On Windows you will have to copy or move the plugin bundles.
|
|
If you are building from source, it is expected you know where they should go.
|
|
|
|
# Keeping up to date
|
|
|
|
Things are evolving quickly in Cardinal! To keep your local copy up to date with the changes, simply do:
|
|
|
|
```
|
|
git pull
|
|
git submodule update --init --recursive
|
|
# make etc.. again
|
|
```
|