README_LINUX.md 12.6 KB
Newer Older
1 2
Building SuperCollider on Linux
===============================
3

4 5
Build requirements
------------------
6

7
These are strict requirements for scsynth and supernova:
8

9 10 11 12 13
- [gcc][gcc] >= 4.8
- [cmake][cmake] >= 3.5: Cross-platform build system.
- [libsndfile][libsndfile] >= 1.0: Soundfile I/O.
- [libjack][libjack]: Development headers for the JACK Audio Connection Kit.
- [fftw][fftw] >= 3.0: FFT library.
14

15
These packages are required by default for scsynth and supernova, but the components that require them can be disabled with flags:
16

17 18
- [libxt][libxt]: X toolkit intrinsics, required for UGens such as `MouseX`. To build the servers without X, use the `NO_X11=ON` CMake flag.
- [libavahi-client][libavahi-client]: For zero-configuration networking. To build the servers without Avahi, use the `NO_AVAHI=ON` CMake flag.
19

20 21 22 23 24 25 26
[gcc]: http://www.gnu.org/software/gcc
[libjack]: http://www.jackaudio.org/
[cmake]: http://www.cmake.org
[libsndfile]: http://www.mega-nerd.com/libsndfile
[fftw]: http://www.fftw.org
[libavahi-client]: http://www.avahi.org
[libxt]: http://www.X.org
27

28 29
Recommended packages
--------------------
30

31
For sclang and scide:
32

33 34 35 36 37 38
- [Qt][Qt] >= 5.7 with QtWebEngine: Cross-platform GUI library, required for the IDE and for sclang's Qt GUI kit. It's best to get the latest Qt 5.x version.
- [git][git]: Required for sclang's Quarks system.
- [ALSA][ALSA]: Linux sound library, required for sclang MIDI support.
- [libudev][libudev]: Device manager library, required for HID support.
- [Linux kernel][Linux kernel] >= 2.6: Required for LID support.
- [libreadline][libreadline] >= 5: Required for sclang's CLI interface.
39

40 41 42 43 44 45
[Qt]: http://qt-project.org
[ALSA]: http://www.alsa-project.org
[libudev]: http://www.freedesktop.org/software/systemd/man/libudev.html
[libreadline]: http://savannah.gnu.org/projects/readline
[Linux kernel]: http://www.kernel.org
[git]: https://git-scm.com/
46

47 48
Installing requirements on Debian
---------------------------------
49

50
There are dedicated web pages for building on particular embedded Linux platforms:
51

52 53
- [Raspberry Pi](http://supercollider.github.io/development/building-raspberrypi)
- [BeagleBone Black](https://supercollider.github.io/development/building-beagleboneblack)
54

55
On Debian-like systems, the following command installs the minimal recommended dependencies for compiling scsynth and supernova:
56

57
    sudo apt-get install build-essential cmake libjack-jackd2-dev libsndfile1-dev libfftw3-dev libxt-dev libavahi-client-dev
58

59
If you need to use JACK1 replace libjack-jackd2-dev by libjack-dev.
60

61
The following command installs all the recommended dependencies for sclang except for Qt:
62

63
    sudo apt-get install git libasound2-dev libicu-dev libreadline6-dev libudev-dev pkg-config
64

65 66
Installing Qt
-------------
67

68
**Qt 5.7 or later** is required to be able to run the SuperCollider IDE and sclang's Qt GUI system. This may be a little complicated since some versions of some Linux distributions are stuck with old Qt versions.
69

70
### Installing Qt on recent Debian-like operating systems
71

72
Depending on your Debian flavor and version, your distribution's PPA may be stuck in an old version of Qt. Try this command to query the Qt version available to you:
73

74
    apt-cache policy qt5-default
75

76
If this displays version 5.7 or later, installing Qt is easy:
77

78 79 80 81 82 83 84 85 86 87 88 89 90 91 92
    sudo apt-get install qt5-default qt5-qmake qttools5-dev qttools5-dev-tools qtdeclarative5-dev qtwebengine5-dev libqt5svg5-dev

If you are on Ubuntu 14.04 (Trusty) or 16.04 (Xenial), check the next section. Otherwise, you will have to use the official Qt installer. Sorry.

### Installing Qt on Ubuntu Trusty or Xenial

If you are on Ubuntu 14.04 (Trusty) or 16.04 (Xenial), [Stephan Binner's Launchpad PPAs][Stephan Binner's Launchpad PPAs] allow for simple installation of new Qt versions.

On Xenial:

    sudo apt-add-repository ppa:beineri/opt-qt-5.11.0-xenial
    sudo apt-get update
    sudo apt-get install qt511base qt511location qt511declarative qt511tools qt511webchannel qt511xmlpatterns qt511svg qt511webengine qt511websockets

On Trusty, only Qt 5.10 and below are available:
93

94 95 96
    sudo apt-add-repository ppa:beineri/opt-qt-5.10.1-trusty
    sudo apt-get update
    sudo apt-get install qt510base qt510location qt510declarative qt510tools qt510webchannel qt510xmlpatterns qt510svg qt510webengine qt510websockets
97

98
[Stephan Binner's Launchpad PPAs]: https://launchpad.net/~beineri
99

100
### Installing Qt using the official installer
101

102
Worst case scenario, you can grab Qt off the [Qt official website](https://www.qt.io/). It's best to get the latest version. Click "Download," select the open source license, and download the Qt installer. The Qt installer has a step that prompts for you to log in to a Qt Account, but you don't actually need to authenticate and you can safely click "Skip" at that step.
103

104
At the "Select Components" step, pop open Qt → Qt 5.11 (or whatever the latest version is) and check the "Desktop" option. If you are building the IDE, also select "QWebEngine."
105

106
Unfortunately, the Qt installer does not allow you to deselect the multi-gigabyte QtCreator download.
107 108 109 110

Building
--------

111
### Step 1: Make a build directory
112

113
First, `cd` into the root of the SuperCollider source directory (where this file resides).
114

115
Create a build directory and `cd` into it:
116

117 118
    mkdir build
    cd build
119

120
You can actually name this whatever you want, allowing you to have multiple independent build directories. If your SuperCollider source is also a git repository, the `.gitignore` file is configured to ignore files of the form `build*`.
121

122
### Step 2: Set CMake flags
123

124
Depending on what SuperCollider components you wish to install, you can set CMake flags. You can set CMake flags on the command line using `cmake -DKEY=value ..`. You can also use cmake frontends like ccmake or cmake-gui, or simply edit the `CMakeCache.txt` file. CMake flags are persistent and you only need to run these commands once each.
125

126
We will cover a few important settings. There are others, which you can view with `cmake -LH ..`. We will document more of them in this README file soon.
127

128
#### Nonstandard Qt locations
129

130
If you are installing sclang with GUI features and the IDE, and you installed Qt using the official Qt installer or the Trusty/Xenial PPAs, you will need to tell SuperCollider where Qt is. To do so:
131

132
    cmake -DCMAKE_PREFIX_PATH=/path/to/qt5 ..
133

134
The location of `/path/to/qt5` will depend on how you installed Qt:
135

136 137
- If you downloaded Qt from the Qt website, the path is two directories down from the top-level unpacked Qt directory, in a folder called `gcc`: `Qt/5.11.0/gcc_64/` (64-bit Linux) or `Qt/5.11.0/gcc/` (32-bit). By default, the Qt installer places `Qt/` in your home directory.
- If you used the Trusty/Xenial PPA's described above, the path is `/opt/qt511` or `/opt/qt510` (depending on which version you installed).
138

139
If you want to build without Qt entirely, run
140

141
    cmake -DSC_QT=OFF ..
142

143
#### Compiler optimizations
144

145
If you're building SC for production use and/or don't plan on using a debugger, make sure to build in release mode:
146

147
    cmake -DCMAKE_BUILD_TYPE=Release ..
148

149
This sets the compiler to the best optimization settings. Switch back to the defaults using `cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ..`.
150

151
If you're compiling SC only for use on your own machine (that is, you aren't cross-compiling or packaging SC for distribution), it is recommended to turn on the `NATIVE` flag to enable CPU-specific optimizations:
152

153
    cmake -DNATIVE=ON ..
154

155
#### Install location
156

157
By default, SuperCollider installs in `/usr/local`, a system-wide install. Maybe you can't or don't want to use superuser privileges, or just want to install for a single user. To do so, set `CMAKE_INSTALL_PREFIX` to the desired installation directory. One good place to put it would be `$HOME/usr/local`:
158

159
    cmake -DCMAKE_INSTALL_PREFIX=~/usr/local ..
160

161
Make sure `~/usr/local/bin` is in your `PATH` if you do this. You can do that by adding a line such as `PATH=$PATH:$HOME/usr/local/bin` to `~/.profile`.
162

163
#### Speeding up repeated builds
164

165
If you are developing SC or you're constantly pulling in the latest changes, rebuilding SC repeatedly can be a drag. Installing `ccache` can speed up re-compilation. Here is how to configure cmake to use it:
166

167
    cmake -DCMAKE_CXX_COMPILER=/usr/lib/ccache/g++ -DCMAKE_C_COMPILER=/usr/lib/ccache/gcc ..
168

169
This assumes your ccache executables are installed into `/usr/lib/ccache` - you may need to change the path to reflect your installation.
170

171
#### Library suffix
172

173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202
In some situations, it is preferable to install libraries and plugins
not in the `lib` directory but in a suffixed one, e.g. `lib64`.
In such a case you can set the cmake variable `LIB_SUFFIX`.
For example if you wish to install into `lib64`:

    cmake -DLIB_SUFFIX=64 ..

### Step 3: Build

If CMake ran successfully without errors, you are ready to move on to building. You can freely alternate between building and setting CMake flags.

After setting your CMake flags, just run

    make

The `-j` option allows multiple jobs to be run simultaneously, which can improve compile times on machines with multiple cores. The optimal `-j` setting varies between machines, but a good rule of thumb is the number of cores plus one. For example, on a 4-core system, try `make -j5`.

And to install, run

    make install

You will need to use `sudo make install` if you are doing a system-wide installation, which is the default.

After installing for the first time, please run

    sudo ldconfig

To uninstall:

    make uninstall
203

204
(or `sudo make uninstall`).
205 206 207 208

Building a Debian package
-------------------------

209
The most up-to-date Debian packaging rules are maintained by the
210 211 212 213 214
Debian Multimedia team. Repository (with debian/ folder):

http://anonscm.debian.org/gitweb/?p=pkg-multimedia/supercollider.git;a=summary


215
Running scsynth or supernova (standalone)
216 217
----------------------------

218 219
Run `scsynth --help`  or `supernova --help` to get an option summary. Don't forget to
start jackd before starting the server. If you want to add
220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270
directories to supercollider's search path or assign default jack
ports, set up your environment as described below.

You can specify the number of jack input/output channels created with
the options `-i` and `-o`, respectively.

the `-H` option can be used to specify a jack server to connect to and
to set the jack client identifier. The format is either

`<SERVER-NAME>:<CLIENT-NAME>`

or just

`<CLIENT-NAME>`

when connecting to the default server.


Running sclang
--------------

Supercollider comes with its own powerful IDE. Run it with:

```
$> scide
```

Alternatively you can use sclang in combination with your preferred text
editor out of emacs/vim/gedit. See the `README.md` files in `editors/*` for
installation and usage. Another alternative is to simply run the
`sclang` executable which will provide a readline-based interface.

`sclang` executes the startup file `~/.config/SuperCollider/startup.scd` after class library
initialization. This file can contain statements to set up your
supercollider environment, like setting default variables. An example can
be found in `linux/examples/sclang.sc`.

You _have_ to have a directory `~/.local/share/SuperCollider`. This is where
a synthdefs directory is automatically created. It is also the place
to put Extensions to the class library, in a folder called Extensions.

The runtime directory is either the current working directory or the
path specified with the `-d` option.


Environment
-----------

The jack audio driver interface is configured based on various
environment variables:

271
 * SC_JACK_DEFAULT_INPUTS comma-separated list of jack ports that the server's inputs should connect by default
272 273 274 275 276 277 278 279 280 281 282

   ```
   $> export SC_JACK_DEFAULT_INPUTS="system:capture_1,system:capture_2"
   ```

   in order to connect the first ports of one jack client, it is possible to specify only the client name

   ```
   $> export SC_JACK_DEFAULT_INPUTS="system"
   ```

283
 * SC_JACK_DEFAULT_OUTPUTS comma-separated list of jack ports that the server's outputs should be connected to by default.
284 285 286 287 288 289 290 291 292 293 294 295 296

   ```
   $> export SC_JACK_DEFAULT_OUTPUTS="system:playback_1,system:playback_2"
   ```

   In order to connect the first ports of one jack client, it is possible to specify only the client name

   ```
   $> export SC_JACK_DEFAULT_OUTPUTS="system"
   ```

Two additional environment variables substitute directories for the default
search path for plugins and synth definitions, respectively. Directory
297
names are separated by ':' as in the Unix PATH variable:
298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317

 * SC_PLUGIN_PATH, SC_SYNTHDEF_PATH

   ```
   $> export SC_SYNTHDEF_PATH="./synthdefs:/home/sk/SuperCollider/synthdefs"
   ```


Contributors to this document
-----------------------------

- stefan kersten <sk AT k-hornz DOT de>
- andi pieper
- maurizio umberto puxeddu
- rohan drape
- mario lang
- john yates
- nescivi (marije baalman)
- dan stowell
- tim blechmann