README_LINUX.txt

   1 -*-text-*---------------------------------------------------------------
   2 supercollider 3 for linux
   3 ------------------------------------------------------------------------
   4
   5 ------------------------------------------------------------------------
   6 intro
   7 ------------------------------------------------------------------------
   8
   9 SuperCollider is a synthesis engine (scsynth) and programming language
  10 (sclang), originally Mac-based but now very widely used on Linux
  11 (since Stefan Kersten ported the code in 2003). SuperCollider is free
  12 software under the GPL - its main homepage is at
  13
  14    http://supercollider.sourceforge.net
  15
  16 to get further information on supercollider usage or development, you
  17 might consider subscribing to the mailing lists
  18
  19   http://www.beast.bham.ac.uk/research/sc_mailing_lists.shtml
  20
  21 ------------------------------------------------------------------------
  22 build requirements
  23 (most of these will be available in your linux distribution as packages )
  24 ------------------------------------------------------------------------
  25
  26  * gcc >= 3.0
  27    http://www.gnu.org/software/gcc/
  28    gcc versions < 3.0 are missing some required c++ features
  29
  30  * jack and libjack
  31    http://jackit.sourceforge.net/
  32    jack audio connection kit
  33
  34  * libsndfile >= 1.0
  35    http://www.mega-nerd.com/libsndfile/
  36    _the_ soundfile i/o library
  37
  38  * pkg-config >= 0.14.0
  39    http://www.freedesktop.org/software/pkgconfig/
  40    facilitates checking for installed packages when compiling from
  41    source
  42
  43  * cmake >= 2.8
  44    http://www.cmake.org/
  45    cross-platform build system
  46
  47  * fftw >= 3.0
  48    http://www.fftw.org/
  49    fast FFT transform library (for frequency-domain analysis,
  50                                         phase-vocoder effects)
  51
  52  * libxt
  53    http://www.X.org/
  54    X toolkit intrinsics
  55
  56  * libicu
  57    http://www.icu-project.org/
  58    unicode libraries
  59
  60 ------------------------------------------------------------------------
  61 build requirements (optional features)
  62 (most of these will be available in your linux distribution as packages )
  63 ------------------------------------------------------------------------
  64
  65  * qt >= 4.5 (+ qtwebkit)
  66    http://qt.nokia.com/
  67    cross-platform graphical user interface library, for sclang's GUI
  68    classes
  69
  70  * alsa
  71    http://www.alsa-project.org/
  72    advanced linux sound architecture drivers and library, for sclang's
  73    MIDI interface
  74
  75  * libreadline >= 5
  76    http://savannah.gnu.org/projects/readline
  77    provides convenient CLI interface for sclang
  78
  79  * libhowl (obsolete)
  80    http://www.porchdogsoft.com/products/howl/
  81    zeroconf service dicovery implementation
  82
  83  * libavahi-client
  84    http://www.avahi.org/
  85    a more powerful zeroconf service discovery implementation
  86
  87  * linux kernel >= 2.6
  88    http://www.kernel.org/
  89    for sclang's linux input device (LID) interface
  90
  91  * for scel: the Emacs interface see the README in the directory
  92    `editors/scel'
  93
  94  * for sced: the gedit interface see the README in the directory
  95    `editors/sced'
  96
  97  * for scvim: the vim interface see the README in the directory
  98    `editors/scvim'
  99
 100
 101 ------------------------------------------------------------------------
 102 build requirements (debian users)
 103 ------------------------------------------------------------------------
 104
 105 on debian (unstable) you can install the following packages and be set
 106 for building supercollider:
 107
 108    build-essential
 109    libqt4-dev
 110    libqtwebkit-dev
 111    libjack-dev
 112    libsndfile1-dev
 113    libasound2-dev
 114    libavahi-client-dev
 115    libicu-dev
 116    libreadline6-dev
 117    libfftw3-dev
 118    libxt-dev
 119    pkg-config
 120    cmake
 121    cmake-modules
 122
 123 ------------------------------------------------------------------------
 124 building
 125 ------------------------------------------------------------------------
 126
 127 to build supercollider with cmake, it is suggested to do out-of-tree
 128 builds in a specific build directory:
 129
 130 mkdir build
 131 cd build
 132 cmake ..
 133
 134 to run the build process run:
 135 make
 136
 137 the build process can be configured using the cmake program, cmake
 138 frontends like ccmake or cmake-gui, or by simply editing the
 139 build/CMakeCache.txt file.
 140
 141 for example to enable a release build run the following in your build
 142 directory:
 143 cmake -DCMAKE_BUILD_TYPE=Release ..
 144
 145 to install the whole program, run:
 146 make install
 147
 148 to uninstall:
 149 make uninstall
 150
 151 Qt GUI:
 152 -------
 153
 154 By default the experimental Qt GUI support will be built into sclang.
 155 If you want to build without it configure cmake like this:
 156
 157         cmake -DSC_QT=OFF ..
 158
 159 ------------------------------------------------------------------------
 160 Building a Debian package
 161 ------------------------------------------------------------------------
 162
 163 In our SVN we have debian packaging rules. These were designed on Ubuntu
 164 but we believe they should work on most common debian systems - please
 165 let us know if you have any issues with this way of building:
 166
 167   cd SuperCollider3    # (or wherever your SC source is)
 168   svn co https://supercollider.svn.sourceforge.net/svnroot/supercollider/packages/ubuntu/ debian
 169   debuild
 170
 171 Eventually, some .deb packages will be put in the parent folder, and can
 172 then be installed just like any other Debian package. For example:
 173
 174   dpkg -i ../supercollider*.deb
 175
 176 (Note: the packages supercollider-scel*.deb, supercollider-scvim*.deb,
 177 supercollider-sced*.deb, represent the different editor integrations:
 178 emacs, vim, gedit. You might not want to install all of those, but
 179 choose your preferred editor.)
 180
 181
 182 ------------------------------------------------------------------------
 183 running scsynth (standalone)
 184 ------------------------------------------------------------------------
 185
 186 run scsynth without options to get an option summary. don't forget to
 187 start jackd before trying to use scsynth. if you want to add
 188 directories to supercollider's search path or assign default jack
 189 ports, set up your environment as described below.
 190
 191 you can specify the number of jack input/output channels created with
 192 the options -i and -o, respectively.
 193
 194 the -H option can be used to specify a jack server to connect to and
 195 to set the jack client identifier. the format is either
 196
 197     <SERVER-NAME>:<CLIENT-NAME>
 198
 199 or just
 200
 201     <CLIENT-NAME>
 202
 203 when connecting to the default server.
 204
 205 ------------------------------------------------------------------------
 206 running sclang
 207 ------------------------------------------------------------------------
 208
 209 it is recommended to use sclang in combination with your preferred text
 210 editor out of emacs/vim/gedit. see the README files in `linux/*' for
 211 installation and usage. as an alternative you can simply run the
 212 `sclang' executable which will provide a readline-based interface.
 213
 214 sclang executes the startup file `~/.config/SuperCollider/startup.scd' after class library
 215 initialization. this file can contain statements to set up your
 216 supercollider environment, like setting default variables. an example can
 217 be found in `linux/examples/sclang.sc'.
 218
 219 you _have_ to have a directory `~/.local/share/SuperCollider/'. This is where
 220 automatically a synthdefs directory is created. It is also the place
 221 to put Extensions to the class library, in a folder called Extensions.
 222
 223 the runtime directory is either the current working directory or the
 224 path specified with the `-d' option.
 225
 226 for advanced setups, sclang's compilation search path can be
 227 customized with a library configuration file. an example is provided
 228 in `linux/examples/sclang.cfg'; install it as `/etc/sclang.cfg' or
 229 `~/.config/SuperCollider/sclang.cfg'. This config file is only needed when you want to
 230 _exclude_ directories from the class library. Otherwise (so in most cases)
 231 it is not needed.
 232
 233 ------------------------------------------------------------------------
 234 environment
 235 ------------------------------------------------------------------------
 236
 237 the jack audio driver interface is configured based on various
 238 environment variables:
 239
 240  * SC_JACK_DEFAULT_INPUTS comma separated list of jack ports that
 241    scsynth's inputs should connect to by default
 242
 243    $ export SC_JACK_DEFAULT_INPUTS="system:capture_1,system:capture_2"
 244
 245    in order to connect the first ports of one jack client, it is possible
 246    to specify only the client name
 247
 248    $ export SC_JACK_DEFAULT_INPUTS="system"
 249
 250  * SC_JACK_DEFAULT_OUTPUTS comma separated list of jack ports that
 251    scsynth's outputs should be connected to by default.
 252
 253    $ export SC_JACK_DEFAULT_OUTPUTS="system:playback_1,system:playback_2"
 254
 255    in order to connect the first ports of one jack client, it is possible
 256    to specify only the client name
 257
 258    $ export SC_JACK_DEFAULT_OUTPUTS="system"
 259
 260 two additional environment variables substitute directories for the default
 261 search path for plugins and synth definitions, respectively. directory
 262 names are separated by ':' as in the unix PATH variable:
 263
 264  * SC_PLUGIN_PATH, SC_SYNTHDEF_PATH
 265
 266    $ export SC_SYNTHDEF_PATH="./synthdefs:/home/sk/SuperCollider/synthdefs"
 267
 268 ------------------------------------------------------------------------
 269 documentation
 270 ------------------------------------------------------------------------
 271
 272 apart from the sites listed above, some more documentation links ...
 273
 274 a wiki for supercollider, set up by julian rohrhuber, is at
 275
 276     http://swiki.hfbk-hamburg.de/MusicTechnology/6
 277
 278 linux specific information can be found at
 279
 280     http://swiki.hfbk-hamburg.de/MusicTechnology/478
 281
 282 ------------------------------------------------------------------------
 283 reporting bugs
 284 ------------------------------------------------------------------------
 285
 286 please report bugs either to the sc-users or sc-dev mailing lists.
 287
 288 ------------------------------------------------------------------------
 289 contributors to this document
 290 ------------------------------------------------------------------------
 291
 292 stefan kersten <sk AT k-hornz DOT de>
 293 andi pieper
 294 maurizio umberto puxeddu
 295 rohan drape
 296 mario lang
 297 john yates
 298 nescivi (marije baalman)
 299 dan stowell
 300 tim blechmann
 301
 302 ------------------------------------------------------------------------
 303 outro
 304 ------------------------------------------------------------------------
 305
 306 thanks to james mccartney, for making this great piece of audio
 307 software publically and freely available.
 308
 309 ------------------------------------------------------------------------
 310 eof
 311 ------------------------------------------------------------------------
 312