# HG changeset patch
# User Matti Hamalainen <ccr@tnsp.org>
# Date 1148964604 0
# Node ID 3cc7455360adc22460a335432ee3f96b21072dca
# Parent  fcf4f13d73a0a4d125b49048d7823ac327c5ec86
Improve documentation: Talk more about libSIDPlay1, document problems of
libSIDPlay2 and approximate installation procedure.


diff -r fcf4f13d73a0 -r 3cc7455360ad INSTALL
--- a/INSTALL	Tue May 30 04:24:02 2006 +0000
+++ b/INSTALL	Tue May 30 04:50:04 2006 +0000
@@ -77,23 +77,40 @@
 
 Where to get libSIDPlay1?
 =========================
-libSIDPlay1 is available at SIDPlay's homepage:
+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 are sure that you don't need the commandline player.
+if you think that you do not need the commandline player.
 
 
 Where to get libSIDPlay2?
 =========================
-libSIDPlay2 is available at SourceForge:
+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/
 
-You need the "sidplay-libs-2.1.1" package! Earlier versions WILL NOT
-WORK! Later versions MAY work, but I can't really guarantee that.
-
 
 Building a CVS-version
 ======================
@@ -101,8 +118,8 @@
 (STABLE) versions of following tools installed, including:
 
  - GNU autoconf 2.56 or newer
- - GNU automake 1.7 (older and newer versions MAY be incompatible!)
- - GNU libtool 1.5.6 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
@@ -113,16 +130,62 @@
 
 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, which
-are now available from XMMS-SID's homepage too.
+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 ...
 
-2) In following order,
+   ./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,