BUILDING_ATLAS
==============

In this file, I summarize the different configuration options for the
platforms.  I keep this information mainly for my own reference, but
of course, you can try it out yourself ;)

I strongly suggest that you build ATLAS with the --with-netlib-lapack
option. This includes higher-level routines not covered in ATLAS from
the lapack libraries.

From my experience, I also found that the Core2 architectural defaults
work pretty well for both Intel and AMD chips. On 64bit, AMD64K10h is
a bit better, but not much. On the other hand, the AMD settings
perform too well on the Intel platform.

TABLE OF CONTENTS:

1. OBTAINING THE SOFTWARE
2. GENERAL REMARKS
3. LINUX
4. MAC OS X
5. WINDOWS

1. OBTAINING THE SOFTWARE
=========================

Getting lapack:

wget http://www.netlib.org/lapack/lapack-lite-3.1.1.tgz

Getting ATLAS:

wget http://sourceforge.net/projects/math-atlas/files/Stable/3.8.3/atlas3.8.3.tar.bz2/download

Getting jblas:

git clone git://github.com/mikiobraun/jblas.git

2. GENERAL REMARKS
==================

The general steps are as follows:

* Compile lapack. Lapack uses blas for its low-level computations. ATLAS also
  implements a subset of Lapack, but not all routines. But you can build ATLAS
  to include the Lapack routines it does not implement, and this is what we're
  going to do.

* Compile ATLAS.

* Compile the native part of jblas with "make".

* Compile the java part of jblas with "ant".

The ATLAS build process is a bit, well, unusual, coming with compiled (not scripted)
configuration scripts. ATLAS has prebuilt configurations which result in much
faster compilation times. If it doesn't find such a profile for your computer,
it will perform a large number of timing experiments to find the best combination
(hence the name "Automatically Tuned...").

Finally, some older processors don't support the SSE3 command set. Some tweaking
is necessary to compile ATLAS for SSE2, namely configuring as for SSE3, and
then going into the file "Make.inc", and replacing SSE2 by SSE3 or removing -DATL_SSE3
from the compiler directives.

For reference, here is a list of the main ATLAS options.

ATLAS OPTIONS
-------------

This chart may come in handy when you want ATLAS to build with some
predefined configurations.

ATLAS Architecture Options: (-A)

    0 = 'UNKNOWN'
    1 = 'POWER3'
    2 = 'POWER4'
    3 = 'POWER5'
    4 = 'PPCG4'
    5 = 'PPCG5'
    6 = 'P5'
    7 = 'P5MMX'
    8 = 'PPRO'
    9 = 'PII'
   10 = 'PIII'
   11 = 'PM'
   12 = 'CoreSolo'
   13 = 'CoreDuo'
   14 = 'Core2Solo'
   15 = 'Core2' <- used for 32 bit builds
   16 = 'Corei7'
   17 = 'P4'
   18 = 'P4E'
   19 = 'Efficeon'
   20 = 'K7'
   21 = 'HAMMER'
   22 = 'AMD64K10h' <- used for 64 bit builds
   23 = 'UNKNOWNx86'
   24 = 'IA64Itan'
   25 = 'IA64Itan2'
   26 = 'USI'
   27 = 'USII'
   28 = 'USIII'
   29 = 'USIV'
   30 = 'UnknownUS'
   31 = 'MIPSR1xK'
   32 = 'MIPSICE9'

ATLAS Operating System Options: (-O)

    0 = 'UNKNOWN'
    1 = 'Linux'
    2 = 'SunOS'
    3 = 'SunOS4'
    4 = 'OSF1'
    5 = 'IRIX'
    6 = 'AIX'
    7 = 'Win9x'
    8 = 'WinNT'
    9 = 'HPUX'
   10 = 'FreeBSD'
   11 = 'OSX'

3. Linux
========

LAPACK
------

Copy make.inc.LINUX from INSTALL directory, update options in the file like this:

FORTRAN  = gfortran 
OPTS     = -O2 -fPIC
DRVOPTS  = $(OPTS)
NOOPT    = -fPIC
LOADER   = gfortran
LOADOPTS = -fPIC

compile with "make -k blaslib lapacklib". "-k" (continue on error) is
needed because some files won't build otherwise.


ATLAS
-----

For 32 bit:

mkdir build
cd build
> ../configure -C if gfortran \
  --with-netlib-lapack=$HOME/build/lapack-lite-3.1.1/liblapack_fortran.a \
  -A 15 -Si cputhrchk 0 -b 32 
make
make time

This sets the fortran compiler to gfortran, architecture Core2, 32
bit, and don't test for CPU throttling (not needed because we use
predefined configuration)

For 64 bit:

as above, but configure with

> ../configure \
  --with-netlib-lapack=$HOME/build/lapack-lite-3.1.1/lapack_LINUX.a \
  -A 21 -b 64 -Si cputhrchk 0 -Fa alg -fPIC  


jblas
-----

> ./configure --static-libs --libpath=$HOME/build/ATLAS/build/lib/


4. Mac OS X
===========

If you install the gfortran with mac ports, you get gcc-mp-4.3 and
gfortran-mp-4.3. This means you have to redefine all the
compilers. Apart from that, it was pretty "smooth sailing ;)"

LAPACK
------

cp INSTALL/make.inc.LINUX make.inc

Update options to

FORTRAN  = gfortran-mp-4.3 
OPTS     = -funroll-all-loops -O3 -fPIC
DRVOPTS  = $(OPTS)
NOOPT    = -fPIC
LOADER   = gfortran-mp-4.3
LOADOPTS =

Run with "make -k"


ATLAS
-----

mkdir build_macosx
cd build_macosx

Execute the following script buil.sh:

CC=gcc-mp-4.3
F77=gfortran-mp-4.3
LAPACK=$HOME/Documents/lapack-lite-3.1.1
../configure -b 32 -C xc $CC -C gc $CC -C if $F77 -C ic $CC -C dm $CC -C sm $CC -C dk $CC -C sk $CC -Fa alg -fPIC --with-netlib-lapack=$LAPACK/liblapack_fortran.a

It's important to set the 32bit flag. Otherwise, it seems to construct
64 bit code.


5. Windows XP (32bit)
=====================

I'm describing here using cygwin. For some reason, the gcc4 version in cygwin
does not support compiling to mingw, but using the cygwin version leads
to some address spaces clashes with Java (at least, the last time I checked),
leading to a crash as soon as the cygwin compiled code is loaded.

What all of this means is that you should use the old gcc3 "legacy" compilers.

Also watch out for directory names with spaces in them, ATLAS does not like
them.

LAPACK
------

Compiling LAPACK just works as in Linux, but replace "gfortran" by "g77".

ATLAS
-----

Back in ATLAS 3.6, one needed to set architectures explicitly. With
3.8.3, there is no need to do so, but you have to set the fortran
compiler explicitly to "g77" (and the bit numbers to 32):

../configure --with-netlib-lapack=$HOME//build/lapack-lite-3.1.1/liblapack_fortran.a -A 15 -C if g77 -b 32

64-bit
------

Unfortunately, there is no support for 64bit under Windows right now,
mainly because there is no 64bit mingw compiler in cygwin. There
exists the mingw-w64 bit project
(http://sourceforge.net/projects/mingw-w64/), but I didn't managed to
compile ATLAS using those.
