Surge

CI: Release:

Surge is an open-source digital synthesizer, originally written and sold as a commercial product by @kurasu/Claes Johanson at Vember Audio. In September 2018, Claes chose to release a partially completed version of Surge 1.6 under GPL3, and a group of developers have been improving it since. You can learn more about the team at https://surge-synth-team.org/ or connect with us on Discord.

If you are a musician only looking to use Surge, please download the appropriate binary from our website. The Surge developer team makes regular releases for all supported platforms.

If you would also like to participate in discussions, testing and design of Surge, we have details below and also in the contributors section of the Surge website.

Surge currently builds on macOS as a 64-bit AU, VST2 and VST3, Windows as a 64- and 32-bit VST2 and VST3, and Linux as a 64-bit VST2, VST3 and LV2. We provide binary distributions of the AU and VST3 on our webpage.

This README serves as the root of developer documentation for Surge.

Developing Surge

We welcome developers! Our workflow revolves around GitHub issues in this repository and conversations at our Discord server and IRC chatroom. You can read our developer guidelines in our developer guide doc.

The developer guide also contains information about testing and debugging in particular hosts on particular platforms.

We are also in the process of writing a guide to the internal architecture of Surge, which can help you get oriented and answer some basic questions.

If you want to contribute and are new to Git, we also have a Git How To, tailored at Surge development.

Building Surge

As of April 2020, Surge is built using CMake. If you are familiar with CMake, you can jump to the CMake Targets section.

Windows

Additional pre-requisites:

• Visual Studio 2017 (version 15.5 or newer)
• Inno Setup for building the installer

Install pre-requisites

• Install Git, Visual Studio 2017 or newer
• If you want to build an installer, install Inno Setup
• When you install Visual Studio, make sure to include CLI tools and CMake, which are included in 'Optional CLI support' and 'Toolset for desktop' install bundles

Check out the code

• Log into your GitHub account and fork this repository
• Open Visual Studio's command prompt. This is done by running x64 Native Tools Command Prompt for VS 2017/2019 (or similar) which is installed along with Visual Studio. To do this, press Win key and start typing 'cmd', the command should pop up right away.
• In that command prompt, navigate to a writable directory where you want to check out Surge repository you've just forked
• Continuing in that same command prompt, run these commands one by one to check out the code:

git clone https://github.com/{your-user-name}/surge.git
cd surge
git submodule update --init --recursive

Your first build

All of the following commands take place in VS command prompt as above.

• If you have the VST2 SDK and want to build the VST2 plugin, set the path to it as a user environment variable. If not, don't worry. You can build the VST3 on Windows without any extra assets (we recommend all Windows users to use the VST3). If you don't want to set up an environment variable, you can tell CMake where the path to VST2 SDK is like so:

set VST2SDK_DIR=c:\path\to\vst2

• Now, run CMake to create a build directory:

cmake . -Bbuild -A x64

• Choose to build in Visual Studio or the command line
  • To build in Visual Studio, open the file build\Surge.sln created in the previous step. The Internet is full of introductions to help with Visual Studio to take it from here.
  • To build from the VS command prompt, type:

cmake --build build --config Release --target Surge-VST3-Packaged

• After a successful build, the folder build\surge_products will contain Surge.vst3, which you can use to replace Surge in VST plugin path of your DAW. Note: if you have never installed Surge, you will also need to install the assets! You can do this by either downloading an official installer from our website, or by creating an installer using Inno Setup, then running it.

Your first 32-bit build

• 32-bit build is done exactly like 64-bit build, but when you run CMake, choose a different target:

cmake . -Bbuild32 -A Win32

• To build the plugin, either open build32\Surge.sln or run the CMake build command with build32 as the directory:

cmake --build build32 --config Release --target Surge-VST3-Packaged

Building the Windows installer

If you want to build the installer, open the file installer_win\surge.iss with Inno Setup. Inno Setup will make an installer and place it in installer_win\Output\

Building with Clang

If you have clang installed with vs2019, you can do

cmake -Bbuildclang -GNinja -DCMAKE_TOOLCHAIN_FILE=cmake/x86_64-w64-clang.cmake

and get a buildable set of ninja files. Our release pipeline may shift to this soon.

macOS

To build on macOS, you need Xcode, Xcode Command Line Utilities, and CMake. Once you have installed Xcode from the App Store, the command line to install the Xcode Command Line Utilities is:

xcode-select --install

There are a variety of ways to install CMake. If you use homebrew you can:

brew install cmake

Once that's done, fork this repository, clone it, and update submodules.

git clone https://github.com/{your-user-name}/surge.git
cd surge
git submodule update --init --recursive

Building with build-osx.sh

build-osx.sh has all the commands you need to build, test, locally install, validate, and package Surge on Mac. As of April 2020, it is a very thin wrapper on CMake and Xcode. It's what the primary Mac developers use day to day. The simplest approach is to build everything with:

./build-osx.sh

build-osx.sh will give you a better output if you first gem install xcpretty, the Xcode build formatter, and you have your gem environment running. If that doesn't work, don't worry - you can still build.

This command will build, but not install, the VST3 and AU components. It has a variety of options which are documented in the ./build-osx.sh --help screen, but a few key ones are:

• ./build-osx.sh --build-validate-au will build the AU plugin, correctly install it locally in ~/Library and run au-val on it. Running any of the install options of ./build-osx will install assets on your system. If you are not comfortable removing an AU plugin by hand and the like, please exercise caution!

• ./build-osx.sh --build-and-install will build all assets and install them locally.

• ./build-osx.sh --clean-all will clean your work area of all assets.

• ./build-osx.sh --clean-and-package will do a complete clean, then a complete build, then build a Mac installer package which will be deposited in products folder.

• ./build-osx.sh --package will create a .pkg file with a reasonable name. If you would like to use an alternate version number, the packaging script is in installer_mac folder.

./build-osx.sh is also impacted by a couple of environment variables.

• VST2SDK_DIR points to a folder where VST2 SDK is located. If this is set, VST2 will build. If you set it after having done a run without VST2, you will need to ./build-osx.sh --clean-all to pick up the VST2 SDK path consistently.

Using Xcode

If you would rather use Xcode directly, all of the install and build rules are exposed as targets. You simply need to run CMake and open the Xcode project. From the command line:

cd surge
cmake . -GXcode -Bbuild
open build/Surge.xcodeproj

and you will see a set of targets like install-au-local which will compile and install the AU plugin. These are the targets used by build-osx.sh from the command line.

Linux

Most Linux systems have CMake and a modern C++ compiler installed. Make sure yours does. You will also need to install a set of dependencies:

• build-essential
• libcairo-dev
• libxkbcommon-x11-dev
• libxkbcommon-dev
• libxcb-cursor-dev
• libxcb-keysyms1-dev
• libxcb-util-dev

For VST2, you will need the VST2 SDK - unzip it to a folder of your choice and set VST2SDK_DIR to point to it:

export VST2SDK_DIR="/your/path/to/VST2SDK"

Then fork this repository, git clone Surge and update the submodules:

git clone https://github.com/{your-user-name}/surge.git
cd surge
git submodule update --init --recursive

Building with build-linux.sh

build-linux.sh is a wrapper on the various CMake and make commands needed to build Surge. As with macOS, it is getting smaller every day as we move more things direclty into CMake. As of Surge 1.7.1, build-linux.sh only works on x86 platforms. If you are building 1.7.1 on ARM, please use the ARM specific instructions below. This is fixed at the head of the codebase, so ARM builds can use build-linux.sh in the nightlies, or the upcoming 1.8 release.

You can build with the command:

./build-linux.sh build

or if you prefer a specific flavor:

./build-linux.sh build --project=lv2

which will run CMake and build the assets.

To use the VST2, VST3, or LV2, you need to install it locally along with supporting files. You can do this manually if you desire, but the build script will also do it using the install option:

./build-linux.sh install --project=lv2 --local

Script will install VST2 to $HOME/.vst dir, VST3 to $HOME/.vst3 and LV2 to $HOME/lv2 in local mode. To change this, edit vst2_dest_path and so forth to taste. Without --local, files will be installed to system locations (needs sudo).

For other options, you can do ./build-linux.sh --help.

Build using CMake directly

A build with CMake is also really simple:

cd surge
cmake . -Bbuild
cd build
make -j 2 Surge-VST3-Packaged

This will build the VST3 and deposit it in surge/products folder.

Building for ARM platforms

As of August 4, build-linux.sh supports ARM builds. If you are building the 1.7.0 or 1.7.1 release, though, you need to follow these instructions.

With 1.7.0, we have merged changes needed to build with ARM platforms and have done some Raspberry Pi testing. Due to a variety of choices an ARM user needs to make and due to us not having a RPi in our pipeline (although we do a cross-compile test), we are not building a binary of the ARM executable on Linux today, but you can build it easily.

You need to install the pre-requisites (grep apt-get azure-pipelines.yml) and also install the packages cairo-dev and libxcb-util0-dev. Then the steps to build using your native architecture on RPi are:

cmake -Bbuild -DARM_NATIVE=native
cmake --build build --config Release --target Surge-VST3-Packaged

The -DARM_NATIVE=native will include cmake/arm-native.cmake, which sets up native CPU flags. If you want specific flags, copy that file to cmake/arm-whatever.cmake, edit the flags, and use -DARM_NATIVE=whatever. If you set up an ARM build on a particular architecture, we would appreciate a small CMake stub in a pull request from you!

Targets available are Surge-VST3-Packaged, Surge-LV2-Packaged, Surge-VST2-Packaged (if you have the VST2 SDK) and surge-headless.

These commands will place your final product in build/surge_products. Since we have not updated the build-linux.sh script for ARM yet, you need to do a couple of extra steps:

1. Copy the contents of resources/data to /usr/share/Surge or ~/.local/share/Surge

2. Put your plugin in the appropriate location. For instance:

cd resources/data/
tar cf - . | ( cd ~/.local/share/Surge/; tar xf - )
cd ../../build/surge_products
mv Surge.vst3 ~/.vst3

3. There's a runtime requirement to install the free Lato font family, which is not a build requirement. sudo apt-get install fonts-lato

...and you should be good to go!

We welcome pull requests and contributions which would improve the ARM build experience!

CMake Targets

If you are familiar with CMake, you can use it directly to build on any of our platforms, and use it to install the build on Mac and Linux.

As normal, a CMake process begins by generating make assets:

OS	CMake Generation
mac	cmake -Bbuild -GXcode
win64	cmake -Bbuild
win32	cmake -Bbuild -A Win32
linux	cmake -Bbuild -DCMAKE_INSTALL_PREFIX=/usr
linux-arm	cmake -Bbuild -DARM_NATIVE=native

At this point, you will have a build directory. You can now build targets using the command:

cmake --build build --config Release --target (target-name)

Available build targets are:

Target	Description
Surge-VST3-Packaged	Produces the VST3 in build/surge_products
Surge-VST2-Packaged	Produces the VST2 in build/surge_products (only if VST2 is enabled)
Surge-AU-Packaged	Produces the AU in build/surge_products (Mac only)
Surge-LV2-Packaged	Produces the LV2 in build/surge_products (Linux only)
surge-headless	Builds the headless test component
all-components	Builds everything available on your OS

On Mac and Linux, the CMake file also provides installation targets:

Target	Description
install-everything-local	Install all components and resoures in the appropriate local location for your OS
install-everything-global	Install all components and resources in the appropriate global location (driven by CMAKE_INSTALL_PREFIX on Linux)
install-resources-(global/local)	Install just the resources locally or globally
install-(vst2/vst3/au/lv2)-(global/local)	Install the plugin and associated resources locally or globally

A reasonable session, then, could be (say, on Linux):

cmake -Bbuild -DCMAKE_INSTALL_PREFIX=/g/ins
cmake --build build --config Release --target all-components
sudo cmake --build build --config Release --target install-everything-global

which would result in the VST3 in /g/ins/lib/vst3/Surge.vst3, and so on.

Continuous Integration

In addition to the build commands above, we use Azure pipelines for continuous integration. This means that each and every pull request will be automatically built in all our environments, and a clean build on all platforms is an obvious pre-requisite. If you have questions about our CI tools, don't hesitate to ask on our Discord server. We are grateful to Microsoft for providing Azure pipelines for free to the open source community!

JUCE and SurgeEffectsBank

Since Nov 28, 2020, formerly separate SurgeEffectsBank plugin is a part of the main Surge codebase, built with the master CMakeLists.txt file. SurgeEffectsBank bank uses JUCE and we have adapted our environment to be able to build both JUCE and hand-crafted VST3SDK builds.

By default, JUCE builds are disabled for developers, but they are enabled in our CI and pipeline environments.

If you want to use the JUCE builds, you should add the -DBUILD_SURGE_JUCE_PLUGINS=TRUE command to your first cmake command. This will download and activate JUCE and add additional targets to your project. For instance, on Windows:

cmake -Bbuild -A x64 -DBUILD_SURGE_JUCE_PLUGINS=TRUE

will make a Surge solution file in build folder, which contains the standard Surge targets (like Surge-VST3-Packaged) and also the SurgeEffectsBank targets (Surge-Effects-Bank-Packaged). You can then build using your platform favorite approach. A portable approach is:

cmake --build build --config Release --target Surge-Effects-Bank-Packaged

Building this target will create build/surge_products directory which contains the platform specific targets. For instance, on macOS it contains :

SurgeEffectsBank.app
SurgeEffectsBank.component
SurgeEffectsBank.vst3

The installer scripts generated by the pipeline will install the assets in the correct place, but we don't have CMake install targets for SurgeEffectsBank yet. So for now you would need to move the built component to the appropriate location on your system.

Note that JUCE creates VST3 specification adhering results, so on Windows and Linux, VST3 plugin is a directory which contains a DLL in a path. That top level directory is your asset to be copied to C:\Program Files\Common Files\VST3 on Windows, or ~/.vst3 on Linux.

References

• Most Surge-related conversation happens on the Surge Synthesizer Discord server. You can join via this link
• IRC channel at #surgesynth at irc.freenode.net. The logs are available at https://freenode.logbot.info/surgesynth/.
• Discussion at KvR forum here