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  * libavahi-client
  80    http://www.avahi.org/
  81    a more powerful zeroconf service discovery implementation
  82
  83  * libcwiid
  84    http://abstrakraft.org/cwiid/
  85    library for wiimote support
  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 or libjack-jackd2-dev
 112    libsndfile1-dev
 113    libasound2-dev
 114    libavahi-client-dev
 115    libicu-dev
 116    libreadline6-dev
 117    libfftw3-dev
 118    libxt-dev
 119    libcwiid-dev (for wiimote support)
 120    pkg-config
 121    cmake
 122    subversion (required by the Quarks class at run-time)
 123
 124 ------------------------------------------------------------------------
 125 building
 126 ------------------------------------------------------------------------
 127
 128 to build supercollider with cmake, it is suggested to do out-of-tree
 129 builds in a specific build directory:
 130
 131 mkdir build
 132 cd build
 133 cmake ..
 134
 135 to run the build process run:
 136 make
 137
 138 the build process can be configured using the cmake program, cmake
 139 frontends like ccmake or cmake-gui, or by simply editing the
 140 build/CMakeCache.txt file.
 141
 142 for example to enable a release build run the following in your build
 143 directory:
 144 cmake -DCMAKE_BUILD_TYPE=Release ..
 145
 146 to install the whole program, run:
 147 make install
 148
 149 for the above step you will probably need super-user privileges,
 150 e.g. using "sudo".
 151
 152 also, please run "sudo ldconfig" after installing for the first time.
 153
 154 to uninstall:
 155 make uninstall
 156
 157 Qt GUI:
 158 -------
 159
 160 By default the experimental Qt GUI support will be built into sclang.
 161 If you want to build without it configure cmake like this:
 162
 163         cmake -DSC_QT=OFF ..
 164
 165 ------------------------------------------------------------------------
 166 Building a Debian package
 167 ------------------------------------------------------------------------
 168
 169 The most up-to-date debian packaging rules are maintained by the
 170 Debian Multimedia team. Repository (with debian/ folder):
 171
 172   http://anonscm.debian.org/gitweb/?p=pkg-multimedia/supercollider.git;a=summary
 173
 174 At time of writing they support 3.4.x, but we expect updates once 3.5
 175 is available.
 176
 177 ------------------------------------------------------------------------
 178 running scsynth (standalone)
 179 ------------------------------------------------------------------------
 180
 181 run scsynth without options to get an option summary. don't forget to
 182 start jackd before trying to use scsynth. if you want to add
 183 directories to supercollider's search path or assign default jack
 184 ports, set up your environment as described below.
 185
 186 you can specify the number of jack input/output channels created with
 187 the options -i and -o, respectively.
 188
 189 the -H option can be used to specify a jack server to connect to and
 190 to set the jack client identifier. the format is either
 191
 192     <SERVER-NAME>:<CLIENT-NAME>
 193
 194 or just
 195
 196     <CLIENT-NAME>
 197
 198 when connecting to the default server.
 199
 200 ------------------------------------------------------------------------
 201 running sclang
 202 ------------------------------------------------------------------------
 203
 204 it is recommended to use sclang in combination with your preferred text
 205 editor out of emacs/vim/gedit. see the README files in `linux/*' for
 206 installation and usage. as an alternative you can simply run the
 207 `sclang' executable which will provide a readline-based interface.
 208
 209 sclang executes the startup file `~/.config/SuperCollider/startup.scd' after class library
 210 initialization. this file can contain statements to set up your
 211 supercollider environment, like setting default variables. an example can
 212 be found in `linux/examples/sclang.sc'.
 213
 214 you _have_ to have a directory `~/.local/share/SuperCollider/'. This is where
 215 automatically a synthdefs directory is created. It is also the place
 216 to put Extensions to the class library, in a folder called Extensions.
 217
 218 the runtime directory is either the current working directory or the
 219 path specified with the `-d' option.
 220
 221 for advanced setups, sclang's compilation search path can be
 222 customized with a library configuration file. an example is provided
 223 in `linux/examples/sclang.cfg'; install it as `/etc/sclang.cfg' or
 224 `~/.config/SuperCollider/sclang.cfg'. This config file is only needed when you want to
 225 _exclude_ directories from the class library. Otherwise (so in most cases)
 226 it is not needed.
 227
 228 ------------------------------------------------------------------------
 229 environment
 230 ------------------------------------------------------------------------
 231
 232 the jack audio driver interface is configured based on various
 233 environment variables:
 234
 235  * SC_JACK_DEFAULT_INPUTS comma separated list of jack ports that
 236    scsynth's inputs should connect to by default
 237
 238    $ export SC_JACK_DEFAULT_INPUTS="system:capture_1,system:capture_2"
 239
 240    in order to connect the first ports of one jack client, it is possible
 241    to specify only the client name
 242
 243    $ export SC_JACK_DEFAULT_INPUTS="system"
 244
 245  * SC_JACK_DEFAULT_OUTPUTS comma separated list of jack ports that
 246    scsynth's outputs should be connected to by default.
 247
 248    $ export SC_JACK_DEFAULT_OUTPUTS="system:playback_1,system:playback_2"
 249
 250    in order to connect the first ports of one jack client, it is possible
 251    to specify only the client name
 252
 253    $ export SC_JACK_DEFAULT_OUTPUTS="system"
 254
 255 two additional environment variables substitute directories for the default
 256 search path for plugins and synth definitions, respectively. directory
 257 names are separated by ':' as in the unix PATH variable:
 258
 259  * SC_PLUGIN_PATH, SC_SYNTHDEF_PATH
 260
 261    $ export SC_SYNTHDEF_PATH="./synthdefs:/home/sk/SuperCollider/synthdefs"
 262
 263 ------------------------------------------------------------------------
 264 documentation
 265 ------------------------------------------------------------------------
 266
 267 apart from the sites listed above, some more documentation links ...
 268
 269 a wiki for supercollider, set up by julian rohrhuber, is at
 270
 271     http://swiki.hfbk-hamburg.de/MusicTechnology/6
 272
 273 linux specific information can be found at
 274
 275     http://swiki.hfbk-hamburg.de/MusicTechnology/478
 276
 277 ------------------------------------------------------------------------
 278 reporting bugs
 279 ------------------------------------------------------------------------
 280
 281 please report bugs either to the sc-users or sc-dev mailing lists.
 282
 283 ------------------------------------------------------------------------
 284 contributors to this document
 285 ------------------------------------------------------------------------
 286
 287 stefan kersten <sk AT k-hornz DOT de>
 288 andi pieper
 289 maurizio umberto puxeddu
 290 rohan drape
 291 mario lang
 292 john yates
 293 nescivi (marije baalman)
 294 dan stowell
 295 tim blechmann
 296
 297 ------------------------------------------------------------------------
 298 outro
 299 ------------------------------------------------------------------------
 300
 301 thanks to james mccartney, for making this great piece of audio
 302 software publically and freely available.
 303
 304 ------------------------------------------------------------------------
 305 eof
 306 ------------------------------------------------------------------------
 307