This file explains how to compile and install the CLAM libraries and 
applications from the source tarballs or a subversion checkous. 

Please note that CLAM plugins are compiled and installed independently. 
You can find some plugins in the CLAM/plugins dir of the source code.

Alternatively, CLAM website provides already compiled packages for several 
platforms: http://clam-project.org/download.html

Checkout the subversion repository

	$ svn co http://clam-project.org/clam/trunk clam

 1. Install CLAM dependencies

 This step is different for each architecture (Linux, Windows, MacOSX).
 Such platform dependant steps at detailed at the end of this file.
   
 2. Compile CLAM libraries from the source

 Change the directory to CLAM/ and execute:

        $ scons configure
        $ scons
        $ sudo scons install
 
 This will compile all the libraries with default options, and install
 them to the default dirs ( /usr/local/lib/ and /usr/local/include/ )

 Troubleshooting: in some scenarios, the first scons command ends with error
 and is necessary to re-run scons a second time.
 
 Tip: use "scons -j3" to take advantadge of multi-threading if you machine is a dual-core.

 To install clam in a non system-wide place (usefull when developing) use 
 scons configure with these options: (you must create the destination dir before)

	$ scons configure prefix=~/local
 
 Then export LD_LIBRARY_PATH=~/local/lib before running the apps with these libs.
 (Probably you also want to add this export line into your .bashrc)
 
 To see all available build options run:

        $ scons --help

 Note that scons saves the last used options in the options.cache file. 
 These options will be used by default in further "scons" commands.

 If you plan to use your CLAM build for performance-sensitive applications consult the
 tips below (4. Tips for increasing performance).
 
 MacOSX specific: the equivalent to LD_LIBRARY_PATH in mac is DYLD_LIBRARY_PATH.
   
 ** Warning about compiler Errors: ** 
 Because scons copies all sources in CLAM/scons/libs/ you must be aware that the 
 paths given by the g++ error log are NOT the original sources. For example, if scons 
 returns: "scons/libs/core/src/Processing.cxx:56: error: ..." you should not edit this 
 file but the one in src/ (searchable by  $ find  src/ -name "Processing.cxx")

 3. Compile CLAM applications and extensions plugins.

 Applications and plugins can be download from the CLAM website in separate tarballs.
 If you are using svn, applications are folders at the clam trunk.
 Plugins are inside CLAM/plugins/.
 Go to the root of the application or plugin source tree (e.g. NetworkEditor or
 CLAM/plugin/osc) and issue: (maybe changing the prefix)

        $ scons prefix=/usr/local clam_prefix=/usr/local

		$ scons install   # with 'sudo' if the prefix requires it

 For further building options do :

        $ scons --help

 Some of the projects do not follow this general rule so refer to their
 INSTALL file for extra dependencies and the concrete procedure.


++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++



2.1 Install CLAM dependencies on Linux

 Debian/Ubuntu
 (do "sudo apt-get install <packages>")

 * Packages to compile clam libs:
   build-essential scons ladspa-sdk lv2core libfftw3-dev libjack-dev libmad0-dev libogg-dev libsndfile1-dev libvorbis-dev libid3-3.8.3-dev libasound2-dev portaudio19-dev libxerces-c-dev python-dev

 ** to compile and pass the tests: libcppunit-dev 

 * Qt4 packages required to compile most CLAM applications (NetworkEditor, Annotator, Chordata, Voice2Midi...):
   qt4-dev-tools libqt4-dev libqt4-opengl-dev libqtwebkit-dev

 * Qt3 packages to compile SMSTools:
   libqt3-headers libqt3-mt-dev 

 
 Redhat / Fedora Core packages list (tested with FC5)
   gcc-c++ scons fftw2-devel fltk-devel libvorbis-devel libogg-devel qt-devel
   qt-designer libxml++-devel alsa-lib-devel libsndfile-devel ladspa-devel 
   id3lib-devel libXi-devel 
   Unofficial Pakages:
   libmad-devel (lvn5) jack-audio-connection-kit-devel (rhfc5.ccrma)
   qt4-devel, qt4 


 Gentoo packages list:
 * for libclam: scons fftw jack-audio-connection-kit ladspa-sdk xerces-c libvorbis libmad libogg libsndfile id3lib alsa-lib portaudio 


2.2 Install CLAM dependencies on Mac OSX

Build instructions for CLAM in Mac OSX are currently in this wiki:

http://clam-project.org/wiki/Devel/Mac_OSX_build



2.3 Install CLAM dependencies on Windows

See instructions on the wiki for native compilation with MinGW 
or cross compilation from Linux

 http://www.clam-project.org/wiki/Devel/Windows_MinGW_cross_compile (recommended)
 http://www.clam-project.org/wiki/Devel/Windows_MinGW_build


++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 
 
 3. Tips for increasing performance

 If you plan to use CLAM in performance-sensitive applications it's a good idea to
 compile with the release flag set, as this tells the compiler to use optimizations:
 	
	$ scons configure release=1

 Also if you use the fourier transform a lot in CLAM, try using the fast fftw3 
 implementation:

 	$ scons configure with-fftw3=1

 Of course you can do both:

 	$ scons configure release=1 with-fftw3=1
 
 If you decide to use the fftw3 library you can further improve the fft performance
 by precomputing wisdom. The fftw3 tries to optimize the algorithms it uses for your
 system, this takes a long time at first but allows the transforms to be later 
 computed much faster. To calculate the wisdom for the transforms most often used in
 CLAM issue these commands (you need the fftw3 package):

 	$ fftw-wisdom -v -x -o wisdom rof32768 cif32768

 And then move the resulting wisdom file to the default system wisdom location (you
 need root access for this):

 	$ sudo mv wisdom /etc/fftw/

 Don't worry if the file /etc/fftw/wisdom already exists - you do not lose any
 information previously stored in it, because fftw-wisdom reads this file first and
 includes it in the new wisdom file it generates.

 Generating fftw wisdom has been tested under linux, for using wisdom on other 
 operating systems consult your fftw3 user documentation.





