INSTALL Guide v0.1 - March 30, 2009

jblas depends on a BLAS and LAPACK library for most of its
computational intensive parts. I recommend getting a high-quality
implementation like ATLAS http://math-atlas.sourceforge.net/, but
taking the default implementation should also suffice. 

Since the LAPACK libraries which come with ATLAS are incomplete (for
example, no eigenvalue computations), you also need the Fortran LAPACK
and BLAS libraries. These will be linked in a way such that the
optimized ATLAS versions are used when available.


STANDARD PROCEDURE
==================

COMPILING JBLAS

Assuming that you already have LAPACK and ATLAS libraries
somewhere. This has been tested on Linux (debian lenny) and Windows
XP/Cygwin.

Prerequisites: 
  - java JDK
  - ant
  - ruby
  - Windows XP: cygwin with gcc, nm, ruby, make, etc.

1. Run "./configure".

2. Running "ant clean all" should do the job ;)


INSTALLING JBLAS

1. Add "jblas.jar" to your CLASSPATH

2. By default, the dynamic libraries are extracted from the jar file
   to the default temporary directory and loaded from there. If you
   don't want to do this, extract the dynamic library from jblas.jar
   and copy it somewhere where it can be found.

   For Linux, use LD_LIBRARY_PATH, for Windows, PATH
   

CONFIGURE FLAGS

The configure script understands the following options:

--lapack=DIR
   Location where the LAPACK and BLAS sources can be found. Location of
   the extracted lapack-lite files. Otherwise it is assumed that they
   can be found in the jblas directory

--lapack-build
   Build only against LAPACK and BLAS, not ATLAS. Note that depending on
   your configuration, you might still get an ATLAS version (for example, when
   you compile under debian and ATLAS is installed). Use --static-libs then.

--download-lapack
   Download and unpack lapack-lite here if not found.

--static-libs
   Searches for static libraries only. Resulting jblas will not depend on
   shared LAPACK/BLAS/ATLAS libraries. Default for Windows XP.

--help
   print this help


FURTHER BUILD OPTIONS
=====================

ADDING OTHER FUNCTIONS FROM LAPACK

Currently, I've only added stubs for LAPACK routines I have needed so
far.  If you want to add further stubs, you need the LAPACK
sources. Currently, the build is set up to work with the directory
structure of lapack-lite
http://www.netlib.org/lapack/lapack-lite-3.1.1.tgz If you want to play
around with other LAPACK routines, it is best to download the archive
and unpack it in the jblas directory. You can also type in
"./configure --download-lapack" to let the configure script handle
this (requires "wget" and "tar" to be installed)

Then, you have to do a "ant realclean jar" to delete the cached
information about the Fortran routines and reparse the definitions.


ANT TARGETS

javadoc
  generate javadoc pages

compile-test
  compiles tests (need junit3)

test
  run some tests (not that good coverage so far)

compile
  recompile classes


COMPILING LAPACK/BLAS AND ATLAS
===============================

Here are some hints when you want to compile LAPACK/BLAS and LAPACK
from scratch. Note that the installation processes for both these
packages are quite non-standard... .


COMPILING LAPACK/BLAS

1. Copy a matching make.inc.* from the INSTALL directory to the base
   directory, where * stands for your operating system (for example, *
   = LINUX for Linux and Windows/Cygwin, * = gfortran if you have the
   (newer) gfortran instead of g77)

2. In make.inc, add the option "-fPIC" to OPTS and NOOPTS

2. Run "make blaslib lapacklib"

4. Rename "blas_*.a" to "libblas_fortran.a" and 
   "lapack_*.a" to "liblapack_fortran.a"

If you want to make a LAPACK build, make sure to specify --static-libs
when configuring jblas as well.


COMPILING ATLAS 

A version more recent than 3.8.0 should work

1. Create a build directory with "mkdir build" and cd into it with "cd
   build".

2. For Linux, run "../configure -Fa alg -fPIC". (Note: for 3.8.3 on my
   system, I had to add the "-b 32" flag to set the pointer
   width. Also make sure to turn of any CPU throttling with
   'cpufreq-set'.)

   For Windows/Cygwin, run "../configure -O 1", maybe also add "-b 32"
   for 32bit systems. This basically configures ATLAS as if you
   compiled on a Linux system, because the Windows/Cygwin option
   seems to be broken (at least when you're using Cygwin).

3. Run "make" (takes a lot of time, your machine should also not be
   under load) 

4. Only for Linux: Change directory to "build/lib" and run "make shared"
