BUILDING_ATLAS

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" or maven.

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, it is currently not possible to compile ATLAS for 64bit
under windows, mainly because cygwin is 32bit. There exists the
ming-w64 bit project (http://sourceforge.net/projects/mingw-w64/),
which provides 64bit compiler for the MINGW environment (a subset of
the UNIX- like environment cygwin provides, unfortunately insufficient
to build ATLAS).

What you can do, though,

Pure LAPACK-build on Windows 64 bit
-----------------------------------

Install the x86_64-w64-mingw32 compilers (just about everything except
for ada and objective C) ;)

In order to run fortran files, you might need to put

x86_64-w64-mingw32/sys-root/mingw/bin/

into your PATH.

Then, go into lapack-lite, and edit make.inc such that gfortran is
replaced by x86_64-w64-mingw32-gfortran everywhere. You should also
include the -funroll-all-loops -O3 options.

Compile using "make -k blaslib lapacklib" as usual, and rename the
results to libblas.a and liblapack.a. Then, do a normal lapack build.