-*- text -*-
------------------------------------------------------------------------
supercollider 3 for linux
------------------------------------------------------------------------
$Id: README,v 1.9 2004/04/24 13:35:47 kersten Exp $
------------------------------------------------------------------------

intro
------

this is a port of james mccartney's supercollider synthesis engine
(scsynth) and programming language (sclang) to linux. supercollider's
main homepage is at

   http://www.audiosynth.com

the source code can be obtained via CVS from

   http://supercollider.sourceforge.net

to get further information on supercollider usage or development, you
might consider subscribing to the mailing lists

   http://www.create.ucsb.edu/mailman/listinfo/sc-users
   http://www.create.ucsb.edu/mailman/listinfo/sc-dev

requirements
-------------

 * gcc >= 3.0

   http://www.gnu.org/software/gcc/

   gcc versions < 3.0 are missing some required c++ features

 * ALSA + JACK

   http://www.alsa-project.org
   http://jackit.sourceforge.net

   you need the ALSA soundcard drivers and the JACK audio connection kit
   installed

 * libsndfile >= 1.0

   http://www.mega-nerd.com/libsndfile/

   _the_ soundfile i/o library

 * pkg-config >= 0.14.0

   facilitates checking for installed packages when compiling
   from source

 o autoconf >= 2.52, automake >= 1.4-p4, libtool >= 1.4.2a

   http://www.gnu.org/software/automake/
   http://www.gnu.org/software/autoconf/
   http://www.gnu.org/software/libtool/

   when making changes to the build setup you'll need those too

installation
-------------

if you're familiar with building and installing linux packages, this won't
be new to you:

 0. unpack the distribution tarball and change to the created directory
 1. when building from the CVS sources, execute
    $ ./linux/bootstrap
 2. for an overview of configuration options, execute
    $ ./configure --help
 3. execute
    $ ./configure [options]
    $ make
    $ make install

running scsynth
----------------

run scsynth without options to get an option summary. don't forget to start
jackd before trying to use scsynth. if you want to add 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.

running sclang
---------------

it is recommended to use sclang in combination with the emacs
interface in 'scel'. see the README in this directory for installation
and usage.

before running sclang, you have to create a library configuration file
that tells sclang which classes to compile. there are classes that
don't work on linux, so you'll have to exclude the respective
files/directories from your library configuration. an example
configuration file that works on linux is provided in
`examples/sclang.cfg'; install it as `/etc/sclang.cfg' or
`~/.sclang.cfg'.

you also have to create a custom version of the class Main, because
the default version calls startup code of classes not working on
linux. an example is given in 'examples/extMain.sc'; you can adapt the
file to your needs and put it in your library search path, or live
with the default version, which is installed at the standard library
location (`$prefix/share/SuperCollider/SCClassLibrary').

sclang executes the startup file `~/.sclang.sc' after class library
initialization. this file can contain statements you don't want to put
in a custom Main class, like setting default variables. an example can
be found in `examples/sclang.sc'.

you _have_ to have a `synthdefs' subdirectory in sclang's runtime
directory, because some default synthdefs are written on startup;
otherwise the language will signal a runtime error. 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:

 * SC_JACK_DEFAULT_INPUTS comma separated list of jack ports that
   scsynth's inputs should connect to by default

   $ export SC_JACK_DEFAULT_INPUTS="alsa_pcm:capture_1,alsa_pcm:capture_2"

 * SC_JACK_DEFAULT_OUTPUTS comma separated list of jack ports that
   scsynth's outputs should be connected to by default.

   $ export SC_JACK_DEFAULT_OUTPUTS="alsa_pcm:playback_1,alsa_pcm:playback_2"

two additional environment variables add directories to the default
search path for plugins and synth definitions, respectively. directory
names are separated by ':' as in the unix PATH variable:

 * SC_PLUGIN_PATH, SC_SYNTHDEF_PATH

   $ export SC_SYNTHDEF_PATH="./synthdefs:/home/steve/lib/SuperCollider/synthdefs"

documentation
--------------

apart from the sites listed above, some more documentation links ...

a wiki for supercollider, set up by julian rohrhuber, is at

    http://swiki.hfbk-hamburg.de:8888/MusicTechnology/6

linux specific information can be found at

    http://swiki.hfbk-hamburg.de:8888/MusicTechnology/478

if and when i get around to update the site, you'll find some more at

   http://www.cs.tu-berlin.de/~kerstens/sc.html

reporting bugs
---------------

please report bugs either to the sc-users or sc-dev mailing lists.

contributors
-------------

stefan kersten <steve@k-hornz.de>
andi pieper
maurizio umberto puxeddu
rohan drape

outro
------

thanks to james mccartney, for making this great piece of audio
software publically and freely available.
