moved INSTALL.txt to README.txt and (mostly) rewrote it

svn path=/trunk/externals/iem/iemmatrix/; revision=17446

1 files changed, 161 insertions, 0 deletions

diff --git a/README.txt b/README.txt
new file mode 100644
index 0000000..56a066e
--- /dev/null
+++ b/README.txt
@@ -0,0 +1,161 @@
+Installation/Compilation instructions for "iemmatrix"
+=====================================================
+
+iemmatrix uses the *autoconf* build system.
+For generic build instructions, please see INSTALL.txt
+
+Dependencies
+============
+
+in order to compile iemmatrix, you will need some libraries/applications installed.
+Some of these dependencies are optional.
+If they are present during compilation, iemmatrix will have certain functionality
+enabled, which might be missing otherwise.
+
+ - puredata
+     http://puredata.info/downloads
+     make sure you also have the development files (headers)
+
+ - GNU scientific library (aka gsl) [optional]
+     http://www.gnu.org/software/gsl
+     needed for higher maths, including eigenvalues and singular-value decomposition
+ - FFTW (Fast Fourier Transform) [optional]
+     http://www.fftw.org
+     fast, high-precision FFTs; if not present, iemmatrix will use Pd's internal FFT
+ - sndfile (reading/writing audio files) [optional]
+     http://www.mega-nerd.com/libsndfile/
+     for reading soundfiles into matrices (many soundfiles are supported)
+
+
+ - autotools, libtool, gettext
+     thats the basic build-system
+
+ - a compiler, linker,...
+     tested with
+      - GCC (the GNU compiler collection)
+      - Clang
+
+Building
+========
+
+Make sure that each step succeeds, before proceeding to the next one!
+
+ $ ./autogen.sh
+ $ ./configure
+ $ make
+
+
+./configure will need to find the Pd-headers (and on some platforms the Pd-library).
+If these files are in a non-standard location (e.g. on W32 and OSX),
+you have to manually tell it where to look for them, using the `--with-pd` flag
+and pointing it to the directory that contains the 'bin/' and 'src/' (or 'include/')
+folders of your Pd-distribution.
+
+E.g.
+
+ $ ./configure --with-pd=/Applications/Pd-0.45-4.app/Contents/Resources
+
+Once `make` has succeeded, you will have a `iemmatrix` binary in the (hidden)
+`.libs` folder.
+
+
+Installing
+==========
+
+The ordinary way to install, is by running the following with the proper priviliges
+(e.g. as root):
+
+ # make install
+
+This will install the entire iemmatrix into /usr/local/lib/pd/extra/iemmatrix.
+
+On systems that have no standard filesystem layout for Pd-externals (e.g. W32 and OSX),
+this is not exactly what you want.
+Instead, you can use the following to collect all installation data into a single directory:
+
+ $ make install DESTDIR=$(pwd)/ pkglibdir=iemmatrix
+
+This will create a new directory `iemmatrix` (in your current directory),
+containing all binaries and abstractions needed.
+
+You can then take this directory, and put it into a place, where Pd will look for it:
+
+E.g.
+
+ - linux: `~/pd-externals` (e.g. `/home/frodo/pd-externals`)
+ - OSX  : `~/Library/Pd`   (e.g. `/Users/frodo/Pd`)
+ - W32  : `%AppData%\Pd`   (e.g. `C:\Documents and Settings\frodo\Application Data\Pd`)
+
+A full list of default search paths for externals, can be found at
+  https://puredata.info/docs/faq/how-do-i-install-externals-and-help-files/
+
+
+System-specific instructions
+============================
+
+linux (Debian-based)
+--------------------
+
+`iemmatrix` is available as Debian package
+
+  # aptitude install pd-iemmatrix
+
+To install all dependencies for compiling iemmatrix yourself, use:
+
+ # apt-get build-dep pd-iemmatrix
+
+or
+
+ # aptitude install automake1.11 autoconf puredata libfftw3-dev libsndfile1-dev libgsl0-dev
+
+
+mac OS-X
+--------
+
+Most dependencies are available via `brew`
+
+   http://brew.sh
+
+Install them using
+
+   $ brew install gsl --universal
+   $ brew install fftw --universal
+   $ brew install libsndfile --universal
+
+When running iemmatrix' configure, make sure to specify the path to Pd.
+If you want to build universal binaries (e.g. both 32bit (i386) and 64bit (x86_64)),
+you can specify the `--enable-fat-binary` flag.
+E.g.
+
+ $ ./configure  --with-pd=/Applications/Pd-0.45-4.app/Contents/Resources --enable-fat-binary=i386,x86_64
+
+Note: when building fat binaries, all dependencies must be fat too.
+
+Microsoft W32
+-------------
+
+The only sane way to build iemmatrix for W32 using autotools,
+is currently by using `MinGW-w64` as a cross-compilation environment on linux.
+
+Debian (and derivates) provides packages for this:
+
+ # aptitude install mingw-w64 mingw-w64-i686-dev mingw-w64-tools binutils-mingw-w64
+
+Run "./configure" and specify the path to your W32 installation of Pd
+(where you unzipped the W32 package of Pd) using the `--with-pd` flag.
+Make sure that the Pd-sources are in PDPATH/src and the compiled pd-binaries in PDPATH/bin.
+If they are scattered across you filesystem you can alternatively give explicitely the paths
+to your "m_pd.h" (with `--includedir`) and to your "pd.lib" (with `--libdir`).
+Don't forget to override the default extension ("pd_linux" on linux-systems)
+with the more appropriate "dll".
+On bash this looks like:
+
+ $ ./configure --with-extension=dll --host=i686-w64-mingw32 --with-pd=/home/frodo/W32/pd-0.46-6
+
+Now run "make" and enjoy.
+	
+
+W32 using VisualStudio
+----------------------
+There are outdated VisualStudio project files in src/
+Use them at your own risk.