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 In our SVN we have debian packaging rules. These were designed on Ubuntu
 170 but we believe they should work on most common debian systems - please
 171 let us know if you have any issues with this way of building:
 172
 173   cd SuperCollider3    # (or wherever your SC source is)
 174   svn co https://supercollider.svn.sourceforge.net/svnroot/supercollider/packages/ubuntu/ debian
 175   debuild
 176
 177 Eventually, some .deb packages will be put in the parent folder, and can
 178 then be installed just like any other Debian package. For example:
 179
 180   dpkg -i ../supercollider*.deb
 181
 182 (Note: the packages supercollider-scel*.deb, supercollider-scvim*.deb,
 183 supercollider-sced*.deb, represent the different editor integrations:
 184 emacs, vim, gedit. You might not want to install all of those, but
 185 choose your preferred editor.)
 186
 187
 188 ------------------------------------------------------------------------
 189 running scsynth (standalone)
 190 ------------------------------------------------------------------------
 191
 192 run scsynth without options to get an option summary. don't forget to
 193 start jackd before trying to use scsynth. if you want to add
 194 directories to supercollider's search path or assign default jack
 195 ports, set up your environment as described below.
 196
 197 you can specify the number of jack input/output channels created with
 198 the options -i and -o, respectively.
 199
 200 the -H option can be used to specify a jack server to connect to and
 201 to set the jack client identifier. the format is either
 202
 203     <SERVER-NAME>:<CLIENT-NAME>
 204
 205 or just
 206
 207     <CLIENT-NAME>
 208
 209 when connecting to the default server.
 210
 211 ------------------------------------------------------------------------
 212 running sclang
 213 ------------------------------------------------------------------------
 214
 215 it is recommended to use sclang in combination with your preferred text
 216 editor out of emacs/vim/gedit. see the README files in `linux/*' for
 217 installation and usage. as an alternative you can simply run the
 218 `sclang' executable which will provide a readline-based interface.
 219
 220 sclang executes the startup file `~/.config/SuperCollider/startup.scd' after class library
 221 initialization. this file can contain statements to set up your
 222 supercollider environment, like setting default variables. an example can
 223 be found in `linux/examples/sclang.sc'.
 224
 225 you _have_ to have a directory `~/.local/share/SuperCollider/'. This is where
 226 automatically a synthdefs directory is created. It is also the place
 227 to put Extensions to the class library, in a folder called Extensions.
 228
 229 the runtime directory is either the current working directory or the
 230 path specified with the `-d' option.
 231
 232 for advanced setups, sclang's compilation search path can be
 233 customized with a library configuration file. an example is provided
 234 in `linux/examples/sclang.cfg'; install it as `/etc/sclang.cfg' or
 235 `~/.config/SuperCollider/sclang.cfg'. This config file is only needed when you want to
 236 _exclude_ directories from the class library. Otherwise (so in most cases)
 237 it is not needed.
 238
 239 ------------------------------------------------------------------------
 240 environment
 241 ------------------------------------------------------------------------
 242
 243 the jack audio driver interface is configured based on various
 244 environment variables:
 245
 246  * SC_JACK_DEFAULT_INPUTS comma separated list of jack ports that
 247    scsynth's inputs should connect to by default
 248
 249    $ export SC_JACK_DEFAULT_INPUTS="system:capture_1,system:capture_2"
 250
 251    in order to connect the first ports of one jack client, it is possible
 252    to specify only the client name
 253
 254    $ export SC_JACK_DEFAULT_INPUTS="system"
 255
 256  * SC_JACK_DEFAULT_OUTPUTS comma separated list of jack ports that
 257    scsynth's outputs should be connected to by default.
 258
 259    $ export SC_JACK_DEFAULT_OUTPUTS="system:playback_1,system:playback_2"
 260
 261    in order to connect the first ports of one jack client, it is possible
 262    to specify only the client name
 263
 264    $ export SC_JACK_DEFAULT_OUTPUTS="system"
 265
 266 two additional environment variables substitute directories for the default
 267 search path for plugins and synth definitions, respectively. directory
 268 names are separated by ':' as in the unix PATH variable:
 269
 270  * SC_PLUGIN_PATH, SC_SYNTHDEF_PATH
 271
 272    $ export SC_SYNTHDEF_PATH="./synthdefs:/home/sk/SuperCollider/synthdefs"
 273
 274 ------------------------------------------------------------------------
 275 documentation
 276 ------------------------------------------------------------------------
 277
 278 apart from the sites listed above, some more documentation links ...
 279
 280 a wiki for supercollider, set up by julian rohrhuber, is at
 281
 282     http://swiki.hfbk-hamburg.de/MusicTechnology/6
 283
 284 linux specific information can be found at
 285
 286     http://swiki.hfbk-hamburg.de/MusicTechnology/478
 287
 288 ------------------------------------------------------------------------
 289 reporting bugs
 290 ------------------------------------------------------------------------
 291
 292 please report bugs either to the sc-users or sc-dev mailing lists.
 293
 294 ------------------------------------------------------------------------
 295 contributors to this document
 296 ------------------------------------------------------------------------
 297
 298 stefan kersten <sk AT k-hornz DOT de>
 299 andi pieper
 300 maurizio umberto puxeddu
 301 rohan drape
 302 mario lang
 303 john yates
 304 nescivi (marije baalman)
 305 dan stowell
 306 tim blechmann
 307
 308 ------------------------------------------------------------------------
 309 outro
 310 ------------------------------------------------------------------------
 311
 312 thanks to james mccartney, for making this great piece of audio
 313 software publically and freely available.
 314
 315 ------------------------------------------------------------------------
 316 eof
 317 ------------------------------------------------------------------------
 318