This document describes overall requirements and procedure
for installation of XMMS-SID package, please read it carefully!
For more information and tips, please refer to README and FAQ.

Requirements
============
- XMMS version 1.2.0 or later (http://www.xmms.org/)

- Gtk+ and Glib 1.2.5 or later (http://www.gtk.org/)

- ANSI-C and C++-compiler. Preferably GCC along with rest of
  the GNU toolchain. I have no idea whether this compiles with
  any other compiler ... sorry.

- You need AT LEAST one of the following emulation libraries:

   * libSIDPlay1
   * libSIDPlay2

  Only one emulator backend library is required, but all are
  supported with compile & run-time configuration. You may also
  need some supplementary libraries for each emulator library.
  See below for more information.


Emulator library selection hints
================================
Some words on which emulation library you should choose to install
and use - it depends somewhat on your system and personal preferences.

- libSIDPlay v1: This is the old and original emulation library. Its
  emulation is "frame-based" and not very accurate. The waveforms
  produced are harsher and emulation of SID filter is far from
  accurate.

  libSIDPlay v1 requires very little CPU power, it is faster and
  may have fewer bugs due to being more mature software. Many
  OS distributions have pre-built packages of it, not something that
  can be said of libSIDPlay v2. Some people may even like the
  harsher sound produced by libSIDPlay v1.

  Drawbacks are: worse emulation, eventually weakening compability
  as new SID-tunes/files are ripped into "RSID"-format which
  libSIDPlay v1 does NOT support.


- libSIDPlay v2: New, next generation modular SID-emulation framework.
  Along with reSID-library it produces probably most accurate emulated
  representation of SID-chip available. This, however, comes at high
  cost: libSIDPlay2 tends to eat CPU like popcorn, depending on the
  selected emulation options. It is also less spread, not as many
  distributions/operating systems come with pre-packaged libSIDPlay2,
  so you may have to roll your own.

  Also the API-stability of libSIDPlay2 is not yet 100%, there may
  be changes. Bugs are evident, though many of them will be fixed
  eventually.

  
Conclusion thus is as follows: If you are using an old system with not
much spare CPU-power, choose libSIDPlay v1. On a relatively recent
system (more powerful than Pentium III 500MHz) you may wish to choose
libSIDPlay v2, although your mileage may vary.


Where to get XMMS?
==================
Latest version of XMMS should be available from:

http://www.xmms.org/

Please refer to XMMS documentation for information on its usage
and installation, etc. You probably have XMMS already installed,
but if you installed from a pre-built package, make sure that
you have corresponding xmms-devel -package also.


Where to get libSIDPlay1?
=========================
Your OS distribution or some supplementary package repository
may contain libSIDPlay1 packages. Usually those should work
well, but remember to also install the corresponding -dev/-devel
package.

If you can't find packages for your OS, source tarballs for
libSIDPlay1 are available at SIDPlay's homepage:

http://www.geocities.com/SiliconValley/Lakes/5147/sidplay/linux.html

You only need libsidplay, the sidplay-base is not necessary
if you think that you do not need the commandline player.


Where to get libSIDPlay2?
=========================
As of now, some OS distributions already include libSIDPlay2
packages, but some of those may be too old or incompatible
with XMMS-SID. Also note, that ONLY the latest CVS version
(as of 28.5.2006) of libSIDPlay2 compiles correctly with
GCC 4.x - older versions trigger a GCC4 bug, which causes
tunes to play too fast!

The fixed versions are available as source tarballs
(and RPMs for Fedora Core 3) and I highly recommend that
you use these versions. Please refer to:

http://www.tnsp.org/xmms-sid.php#download


However, the original home of libSIDPlay2 is at SourceForge:

http://sidplay2.sourceforge.net/


Building a CVS-version
======================
To build a CVS-version of XMMS-SID, you need to have latest
(STABLE) versions of following tools installed, including:

 - GNU autoconf 2.56 or newer
 - GNU automake 1.9 (older and newer versions MAY be incompatible!)
 - GNU libtool 1.5.20 or newer
 - Glade for Gtk+ 1.2 programs (I use Glade 0.6.4)

If you have all required tools installed, just run the
"bootstrap.sh"-script which generates all necessary build-files.
After successfull bootstrapping, you  should be able to install
the package normally, following steps described in next chapter.


Installing libSIDPlay2
======================
NOTICE! The upstream libSIDPlay2 has several bugs in build
scripts, which botch up building on some non-mainstream
platforms, such as NetBSD and Solaris. I personally provide
fixed versions of libSIDPlay2, reSID and reSID-builder
packages. Therefore I highly recommend that you use the
fixed versions I provide on XMMS-SID's homepage (see above).


NOTICE #2! Under Solaris you may run into a linking problem,
because of a bug in GCC's libtool, please read following
mailing list thread for more information:

http://lists.gnu.org/archive/html/libtool/2005-08/msg00021.html


As the installation procedure of libSIDPlay2 is not completely
transparent or simple, I describe here the steps how to do it
(hopefully) in a succesful manner:

1) Get libSIDPlay2, reSID and reSID-builder packages.

2) Build reSID (you may need to invoke 'gmake' instead of 'make'):

   tar -xzvf resid-0.16.2-ccr.tar.gz
   cd resid-0.16.2-ccr
   ./configure
   make

   There is no need to do "make install", just leave the
   build directory intact, you will need the contents when
   compiling reSID-builder below.

3) Build libSIDPlay2 similarly, but this time do install.
   Untar the package as usual and ...

   ./configure
   make
   make install

   You have to do "make install" as root.

4) Build reSID-builder in similar manner, but with specific
   configure parameters. As usual, untar the package and ...

   ./configure --with-resid=/path/to/resid-0.16.2-ccr
   make
   make install

   NOTE! Obviously you have to change the /path/to/ the
   correct location where you compiled the reSID-package.

5) If all went well and without errors, you now should have
   libSIDPlay2 installed with reSID software SID emulation
   backend.

   
Installing XMMS-SID
===================
When you have the requirements installed and working succesfully,
you may try compiling and installation of XMMS-SID.

Invoke configure script (use parameter --help for help)

$ ./configure

The configure-script will print out lots of information and in
the end it tells you some of the selected build options.

NOTICE! On some systems it may be necessary to force 'configure'
to use gcc instead of g++ with following syntax:

$ CC=gcc CXX=g++ ./configure


If configure passed without errors, try compilation. (Depending
on your system, you may need to invoke 'gmake' instead of 'make'.)

$ make

If that went OK too, then you may try installation. Again, you
may need to invoke 'gmake' instead of 'make'. Install globally
to whole system (as root):

# make install

or install for current user only: (Please notice that some data
files are not installed when intalling for user only)

$ make install-user

Assuming all went correctly, XMMS-SID is now installed. You should
now start or re-start XMMS and configure XMMS-SID's various options.


Post-installation configuration
===============================
To gain full advantage of using XMMS-SID, you need to configure it.
XMMS-SID can be configured just like any other XMMS plugin, in XMMS
do as follows:

 -> Press <ctrl+p>
 -> Select "Audio I/O Plugins"-tab
 -> Choose "XMMS-SID x.y.z [libxmmssid.so]" from the list
 -> Click "Configure"

Please refer to README for more information about configuration.