1# Surge 2 3CI: [![CI Build Status](https://dev.azure.com/surge-synthesizer/surge/_apis/build/status/surge-synthesizer.surge?branchName=main)](https://dev.azure.com/surge-synthesizer/surge/_build/latest?definitionId=2&branchName=main) 4Release: [![Release Build Status](https://dev.azure.com/surge-synthesizer/surge/_apis/build/status/surge-synthesizer.releases?branchName=master)](https://dev.azure.com/surge-synthesizer/surge/_build/latest?definitionId=1&branchName=master) 5 6Surge is an open-source digital synthesizer, originally written and sold as a commercial product 7by @kurasu/Claes Johanson at [Vember Audio](http://vemberaudio.se). In September 2018, 8Claes chose to release a partially completed version of Surge 1.6 under GPL3, and a group 9of developers have been improving it since. You can learn more about the team at https://surge-synth-team.org/ or 10connect with us on [Discord](https://raw.githubusercontent.com/surge-synthesizer/surge-synthesizer.github.io/master/_includes/discord_invite_link). 11 12**If you are a musician only looking to use Surge, please download the appropriate binary 13[from our website](https://surge-synthesizer.github.io). The Surge developer team makes regular releases for all supported platforms.** 14 15If you would also like to participate in discussions, testing and design of Surge, we have 16details below and also in [the contributors section of the Surge website](https://surge-synthesizer.github.io/#contributors). 17 18Surge currently builds on macOS as a 64-bit AU, VST2 and VST3, Windows as a 64- and 32-bit VST2 and VST3, 19and Linux as a 64-bit VST2, VST3 and LV2. We provide binary distributions of the AU and VST3 on our webpage. 20 21This README serves as the root of developer documentation for Surge. 22 23# Developing Surge 24 25We welcome developers! Our workflow revolves around GitHub issues in this repository 26and conversations at our Discord server and IRC chatroom. You can read our developer guidelines 27in [our developer guide doc](doc/Developer%20Guide.md). 28 29The developer guide also contains information about testing and debugging in particular hosts 30on particular platforms. 31 32We are also in the process of writing a [guide to the internal architecture of Surge](doc/Architecture.md), which 33can help you get oriented and answer some basic questions. 34 35If you want to contribute and are new to Git, we also have a [Git How To](doc/git-howto.md), tailored at Surge development. 36 37# Building Surge 38 39As of April 2020, Surge is built using CMake. If you are familiar with CMake, you can 40jump to the <a href="#cmake-targets">CMake Targets</a> section. 41 42## Windows 43 44### Additional pre-requisites: 45 46* [Visual Studio 2017 (version 15.5 or newer)](https://visualstudio.microsoft.com/downloads/) 47* [Inno Setup](http://jrsoftware.org/isdl.php) for building the installer 48 49### Install pre-requisites 50 51* Install [Git](https://git-scm.com/downloads), [Visual Studio 2017 or newer](https://visualstudio.microsoft.com/downloads/) 52* If you want to build an installer, install [Inno Setup](https://jrsoftware.org/isdl.php#stable) 53* When you install Visual Studio, make sure to include CLI tools and CMake, which are included in 54'Optional CLI support' and 'Toolset for desktop' install bundles 55 56### Check out the code 57 58* Log into your GitHub account and fork this repository 59* 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. 60To do this, press Win key and start typing 'cmd', the command should pop up right away. 61* In that command prompt, navigate to a writable directory where you want to check out Surge repository you've just forked 62* Continuing in that same command prompt, run these commands one by one to check out the code: 63``` 64git clone https://github.com/{your-user-name}/surge.git 65cd surge 66git submodule update --init --recursive 67``` 68 69### Your first build 70 71All of the following commands take place in VS command prompt as above. 72 73* 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. 74You can build the VST3 on Windows without any extra assets (we recommend all Windows users to 75use 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: 76 77``` 78set VST2SDK_DIR=c:\path\to\vst2 79``` 80 81* Now, run CMake to create a build directory: 82 83``` 84cmake . -Bbuild -A x64 85``` 86 87* Choose to build in Visual Studio or the command line 88 * To build in Visual Studio, open the file `build\Surge.sln` created in the previous step. The Internet is full 89 of introductions to help with Visual Studio to take it from here. 90 * To build from the VS command prompt, type: 91 92``` 93cmake --build build --config Release --target Surge-VST3-Packaged 94``` 95 96* After a successful build, the folder `build\surge_products` will contain `Surge.vst3`, which you can use to replace 97 Surge in VST plugin path of your DAW. Note: if you have never installed Surge, you will also need to install the assets! 98 You can do this by either downloading an official installer from our website, or by 99 <a href="#building-the-windows-installer">creating an installer using Inno Setup</a>, then running it. 100 101### Your first 32-bit build 102 103* 32-bit build is done exactly like 64-bit build, but when you run CMake, choose a different target: 104 105``` 106cmake . -Bbuild32 -A Win32 107``` 108 109* To build the plugin, either open `build32\Surge.sln` or run the CMake build command with `build32` as the directory: 110 111``` 112cmake --build build32 --config Release --target Surge-VST3-Packaged 113``` 114 115### Building the Windows installer 116 117 118If you want to build the installer, open the file `installer_win\surge.iss` with [Inno Setup](https://jrsoftware.org/isdl.php#stable). 119Inno Setup will make an installer and place it in `installer_win\Output\` 120 121### Building with Clang 122 123If you have clang installed with vs2019, you can do 124 125``` 126cmake -Bbuildclang -GNinja -DCMAKE_TOOLCHAIN_FILE=cmake/x86_64-w64-clang.cmake 127``` 128 129and get a buildable set of ninja files. Our release pipeline may 130shift to this soon. 131 132## macOS 133 134To build on macOS, you need `Xcode`, `Xcode Command Line Utilities`, and CMake. Once you have installed 135`Xcode` from the App Store, the command line to install the `Xcode Command Line Utilities` is: 136 137``` 138xcode-select --install 139``` 140 141There are a variety of ways to install CMake. If you use [homebrew](https://brew.sh) you can: 142 143``` 144brew install cmake 145``` 146 147Once that's done, fork this repository, clone it, and update submodules. 148 149``` 150git clone https://github.com/{your-user-name}/surge.git 151cd surge 152git submodule update --init --recursive 153``` 154 155### Building with build-osx.sh 156 157`build-osx.sh` has all the commands you need to build, test, locally install, validate, and package Surge on Mac. 158As of April 2020, it is a very thin wrapper on CMake and Xcode. 159It's what the primary Mac developers use day to day. The simplest approach is to build everything with: 160 161``` 162./build-osx.sh 163``` 164 165`build-osx.sh` will give you a better output if you first `gem install xcpretty`, the Xcode build formatter, 166and you have your `gem` environment running. If that doesn't work, don't worry - you can still build. 167 168This command will build, but not install, the VST3 and AU components. It has a variety of options which 169are documented in the `./build-osx.sh --help` screen, but a few key ones are: 170 171* `./build-osx.sh --build-validate-au` will build the AU plugin, correctly install it locally in `~/Library` 172and run au-val on it. Running any of the install options of `./build-osx` will install assets on your 173system. If you are not comfortable removing an AU plugin by hand and the like, please exercise caution! 174 175* `./build-osx.sh --build-and-install` will build all assets and install them locally. 176 177* `./build-osx.sh --clean-all` will clean your work area of all assets. 178 179* `./build-osx.sh --clean-and-package` will do a complete clean, then a complete build, then build 180a Mac installer package which will be deposited in `products` folder. 181 182* `./build-osx.sh --package` will create a `.pkg` file with a reasonable name. If you would like to use an 183alternate version number, the packaging script is in `installer_mac` folder. 184 185`./build-osx.sh` is also impacted by a couple of environment variables. 186 187* `VST2SDK_DIR` points to a folder where VST2 SDK is located. If this is set, VST2 will build. If you set it after having 188done a run without VST2, you will need to `./build-osx.sh --clean-all` to pick up the VST2 SDK path consistently. 189 190### Using Xcode 191 192If you would rather use Xcode directly, all of the install and build rules are exposed as targets. 193You simply need to run CMake and open the Xcode project. From the command line: 194 195``` 196cd surge 197cmake . -GXcode -Bbuild 198open build/Surge.xcodeproj 199``` 200 201and you will see a set of targets like `install-au-local` which will compile and install the AU plugin. 202These are the targets used by `build-osx.sh` from the command line. 203 204## Linux 205 206Most Linux systems have CMake and a modern C++ compiler installed. Make sure yours does. 207You will also need to install a set of dependencies: 208 209- build-essential 210- libcairo-dev 211- libxkbcommon-x11-dev 212- libxkbcommon-dev 213- libxcb-cursor-dev 214- libxcb-keysyms1-dev 215- libxcb-util-dev 216 217For VST2, you will need the VST2 SDK - unzip it to a folder of your choice and set `VST2SDK_DIR` to point to it: 218 219``` 220export VST2SDK_DIR="/your/path/to/VST2SDK" 221``` 222 223Then fork this repository, `git clone` Surge and update the submodules: 224 225``` 226git clone https://github.com/{your-user-name}/surge.git 227cd surge 228git submodule update --init --recursive 229``` 230 231### Building with build-linux.sh 232 233`build-linux.sh` is a wrapper on the various CMake and make commands needed to build Surge. As with 234macOS, it is getting smaller every day as we move more things direclty into CMake. 235As of Surge 1.7.1, `build-linux.sh` only works on x86 platforms. If you are building 1.7.1 on 236ARM, please use the ARM specific instructions <a href="#building-for-arm-platforms">below</a>. This is fixed at the head of the codebase, so 237ARM builds can use `build-linux.sh` in the nightlies, or the upcoming 1.8 release. 238 239You can build with the command: 240 241``` 242./build-linux.sh build 243``` 244 245or if you prefer a specific flavor: 246 247``` 248./build-linux.sh build --project=lv2 249``` 250 251which will run CMake and build the assets. 252 253To use the VST2, VST3, or LV2, you need to install it locally along with supporting files. You can do this manually 254if you desire, but the build script will also do it using the `install` option: 255 256``` 257./build-linux.sh install --project=lv2 --local 258``` 259 260Script will install VST2 to $HOME/.vst dir, VST3 to $HOME/.vst3 and LV2 to $HOME/lv2 in local mode. 261To change this, edit vst2_dest_path and so forth to taste. Without --local, files will be installed to system locations (needs `sudo`). 262 263For other options, you can do `./build-linux.sh --help`. 264 265### Build using CMake directly 266 267A build with CMake is also really simple: 268 269``` 270cd surge 271cmake . -Bbuild 272cd build 273make -j 2 Surge-VST3-Packaged 274``` 275 276This will build the VST3 and deposit it in `surge/products` folder. 277 278## Building for ARM platforms 279 280As of August 4, `build-linux.sh` supports ARM builds. If you are building the 1.7.0 or 2811.7.1 release, though, you need to follow these instructions. 282 283With 1.7.0, we have merged changes needed to build with ARM platforms and have done some 284Raspberry Pi testing. Due to a variety of choices an ARM user needs to make and due to 285us not having a RPi in our pipeline (although we do a cross-compile test), we are not 286building a binary of the ARM executable on Linux today, but you can build it easily. 287 288You need to install the pre-requisites (`grep apt-get azure-pipelines.yml`) 289and also install the packages `cairo-dev` and `libxcb-util0-dev`. Then 290the steps to build using your native architecture on RPi are: 291 292``` 293cmake -Bbuild -DARM_NATIVE=native 294cmake --build build --config Release --target Surge-VST3-Packaged 295``` 296 297The `-DARM_NATIVE=native` will include `cmake/arm-native.cmake`, which sets up native 298CPU flags. If you want specific flags, copy that file to `cmake/arm-whatever.cmake`, 299edit the flags, and use `-DARM_NATIVE=whatever`. If you set up an ARM build on a particular 300architecture, we would appreciate a small CMake stub in a pull request from you! 301 302Targets available are `Surge-VST3-Packaged`, `Surge-LV2-Packaged`, `Surge-VST2-Packaged` (if you have 303the VST2 SDK) and `surge-headless`. 304 305These commands will place your final product in `build/surge_products`. Since we have 306not updated the `build-linux.sh` script for ARM yet, you need to do a couple of extra steps: 307 3081. Copy the contents of `resources/data` to `/usr/share/Surge` or `~/.local/share/Surge` 309 3102. Put your plugin in the appropriate location. For instance: 311 312``` 313cd resources/data/ 314tar cf - . | ( cd ~/.local/share/Surge/; tar xf - ) 315cd ../../build/surge_products 316mv Surge.vst3 ~/.vst3 317``` 318 3193. There's a runtime requirement to install the free Lato font family, which is not a build 320 requirement. `sudo apt-get install fonts-lato` 321 322...and you should be good to go! 323 324We welcome pull requests and contributions which would improve the ARM build experience! 325 326## CMake Targets 327 328If you are familiar with CMake, you can use it directly to build on any of our platforms, 329and use it to install the build on Mac and Linux. 330 331As normal, a CMake process begins by generating make assets: 332 333| OS | CMake Generation | 334|-----------|---------------------------------------------| 335| mac | `cmake -Bbuild -GXcode` | 336| win64 | `cmake -Bbuild` | 337| win32 | `cmake -Bbuild -A Win32` | 338| linux | `cmake -Bbuild -DCMAKE_INSTALL_PREFIX=/usr` | 339| linux-arm | `cmake -Bbuild -DARM_NATIVE=native` | 340 341At this point, you will have a `build` directory. You can now build targets using the command: 342 343``` 344cmake --build build --config Release --target (target-name) 345``` 346 347Available build targets are: 348 349| Target | Description | 350|---------------------|-----------------------------------------------------------------------| 351| Surge-VST3-Packaged | Produces the VST3 in `build/surge_products` | 352| Surge-VST2-Packaged | Produces the VST2 in `build/surge_products` (only if VST2 is enabled) | 353| Surge-AU-Packaged | Produces the AU in `build/surge_products` (Mac only) | 354| Surge-LV2-Packaged | Produces the LV2 in `build/surge_products` (Linux only) | 355| surge-headless | Builds the headless test component | 356| all-components | Builds everything available on your OS | 357 358On Mac and Linux, the CMake file also provides installation targets: 359 360| Target | Description | 361|-------------------------------------------|-------------------------------------------------------------------------------------------------------------------| 362| install-everything-local | Install all components and resoures in the appropriate local location for your OS | 363| install-everything-global | Install all components and resources in the appropriate global location (driven by CMAKE_INSTALL_PREFIX on Linux) | 364| install-resources-(global/local) | Install just the resources locally or globally | 365| install-(vst2/vst3/au/lv2)-(global/local) | Install the plugin and associated resources locally or globally | 366 367A reasonable session, then, could be (say, on Linux): 368 369``` 370cmake -Bbuild -DCMAKE_INSTALL_PREFIX=/g/ins 371cmake --build build --config Release --target all-components 372sudo cmake --build build --config Release --target install-everything-global 373``` 374 375which would result in the VST3 in `/g/ins/lib/vst3/Surge.vst3`, and so on. 376 377# Continuous Integration 378 379In addition to the build commands above, we use Azure pipelines for continuous integration. 380This means that each and every pull request will be automatically built in all our environments, 381and a clean build on all platforms is an obvious pre-requisite. If you have questions about 382our CI tools, don't hesitate to ask on our [Discord](https://raw.githubusercontent.com/surge-synthesizer/surge-synthesizer.github.io/master/_includes/discord_invite_link) 383server. We are grateful to Microsoft for providing Azure pipelines for free to the open source community! 384 385# JUCE and SurgeEffectsBank 386 387Since Nov 28, 2020, formerly separate SurgeEffectsBank plugin is a part of the main 388Surge codebase, built with the master CMakeLists.txt file. SurgeEffectsBank bank uses JUCE and we 389have adapted our environment to be able to build both JUCE and hand-crafted VST3SDK builds. 390 391By default, JUCE builds are disabled for developers, but they are enabled in our CI and pipeline environments. 392 393If you want to use the JUCE builds, you should add the `-DBUILD_SURGE_JUCE_PLUGINS=TRUE` command 394to your first `cmake` command. This will download and activate JUCE and add additional targets 395to your project. For instance, on Windows: 396 397``` 398cmake -Bbuild -A x64 -DBUILD_SURGE_JUCE_PLUGINS=TRUE 399``` 400 401will make a Surge solution file in `build` folder, which contains the standard Surge targets (like `Surge-VST3-Packaged`) 402and also the SurgeEffectsBank targets (`Surge-Effects-Bank-Packaged`). You can then build using your platform favorite approach. 403A portable approach is: 404 405``` 406cmake --build build --config Release --target Surge-Effects-Bank-Packaged 407``` 408 409Building this target will create `build/surge_products` directory which contains the platform specific targets. For instance, 410on macOS it contains : 411 412``` 413SurgeEffectsBank.app 414SurgeEffectsBank.component 415SurgeEffectsBank.vst3 416``` 417 418The installer scripts generated by the pipeline will install the assets in the correct place, but we don't have CMake 419install targets for SurgeEffectsBank yet. So for now you would need to move the built component to the appropriate location 420on your system. 421 422Note that JUCE creates VST3 specification adhering results, so on Windows and Linux, VST3 plugin is a directory which contains a DLL 423in 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. 424 425# References 426 427 * Most Surge-related conversation happens on the Surge Synthesizer Discord server. [You can join via this link](https://raw.githubusercontent.com/surge-synthesizer/surge-synthesizer.github.io/master/_includes/discord_invite_link) 428 * IRC channel at #surgesynth at irc.freenode.net. The logs are available at https://freenode.logbot.info/surgesynth/. 429 * Discussion at KvR forum [here](https://www.kvraudio.com/forum/viewtopic.php?f=1&t=511922) 430