INSTALL Guide 

Version 1.2.0, January 7, 2011
Version 1.0, December 22, 2009
Version 0.3, September 17, 2009
Version 0.2, May 8, 2009
Version 0.1, March 28, 2009

If you just want to get started, I recommend that you download the
multiplatform" jar file which already includes the required native
BLAS and LAPACK code based on lapack-lite
(http://www.netlib.org/lapack/lapack-lite-3.1.1.tgz) and ATLAS
(http://math-atlas.sourceforge.net/) for a number of operating
systems. Currently supported are:

- Windows
- Linux
- Mac OS X

both in 32 bit and 64 bit versions.

If you are only adding code on the Java side, then you can work with
the supplied build.xml ant script. Simply type "ant jar" to compile
the new jar file.

Starting with version 1.2.0, you can also use maven to compile the project.
Both alternatives exist in parallel.

If you want to access further functions from LAPACK, you need to
recompile the native part. This procedure is a bit more involved, see
below.


COMPILING JBLAS (JAVA PART)
===========================

Prerequisites: 
  - java JDK
  - ant
  - maven
  - ruby

ANT BUILD
---------

Running "ant clean jar" should do the job ;)

"ant jar" collects all static JNI libraries. Other build targets are:

- ant dynamic-lean-jar
  
  Build a jar file with the JNI libraries, but without the ATLAS libraries
  built in for only the current platform.

- ant static-lean-jar

  Build a jar file with the JNI and ATLAS libraries only for the current
  platform.

- ant minimal-jar

  Build a jar file without the JNI and ATLAS libraries. Both must be
  installed in the usual library locations.

MAVEN BUILD
-----------

Just the usual "mvn clean install" builds everything and installs the jar
file in your local repository.

INSTALLING JBLAS
----------------

1. Add "jblas-1.2.0.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-1.2.0.jar
   and copy it somewhere where it can be found.

   For Linux, use LD_LIBRARY_PATH, for Windows, PATH
   

COMPILING THE NATIVE PART
=========================

I assume that you already have a built of lapack-lite or ATLAS based
on the lapack-lite libraries. That build process is quite
involved. You can find some information about it in
BUILDING_ATLAS. You can also use the atlas libraries which come with
your distribution.

The build goes like this:

- run ./configure with options (see below)
- run "make" to build the JNI library
- run "ant jar" to package the library into the jar file


BUILD OPTIONS
-------------

Dynamic vs. Static

Basically, you can build with "dynamic" binding or "static" binding,
which means that either the JNI library is dynamically loading the
lapack libraries, or they are already linked into it. The latter case
("static") is better for standalone cases, but the resulting jar file
is bigger.

The default is dynamic binding, otherwise pass the option
"--static-libs" to the configure script.

This option also affects what libraries "ant jar" packs into the jar file.


LAPACK build vs. ATLAS build

You can either build against LAPACK only, or against the ATLAS
libraries. LAPACK is somewhat slower, but probably easier to
compile. To compile against LAPACK, pass the "--lapack-build"
option. I also recommend to use the "--libpath" option to specify
exactly where the libraries are.


CONFIGURE FLAGS SUMMARY

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.

--ptatlas
   Uses multithreaded versions of the ATLAS libraries. AFAIK, these should
   be compiled on the target computer to have the right number of threads.
   This means you have to recompile ATLAS, but it is certainly worth
   the effort, performance improvements are really huge!

--help
   print help




