SPHInX

h1. Building

Quick guide for users on 100% compatible systems

We assume that you have successfully [[downloaded]] and unpacked the package, possibly including [[3rd-party packages]] in sphinx/sxaccelerate/3rd-party/packages/ .

Please make sure that CPU throttling is deactivated when compiling (specifically: ATLAS!).

<pre>

   cd sphinx

   ./setup

   ./configure --disable-debug

   make all

   make install

</pre>

If this does not work, please read the rest of this page.

You may want to run the [[testbed]] after compilation. 

h2. Prerequisites

    * C++ compiler

    * automake

    * libtool

    * flex, bison

    * Additional libraries (see also [[3rd-party packages]])

    ** BLAS+LAPACK library

    *** ATLAS+LAPACK or

    *** mkl or

    *** acml or

    *** libGOTO or

    *** ESSL 

    ** FFT library

    *** FFTW (recommended)

    *** ACML (we encountered many bugs...) 

    ** netCDF 

| CentOS 5.6 | yum install gcc44-c++ gcc44-gfortran automake libtool flex bison |

| Fedora 15 | yum install gcc-c++, gcc-gfortran, automake, libtool, flex, bison |

| Debian 6 | apt-get install g++ gfortran automake libtool flex bison |

| MacOS X 10.6 | X-Code (install from Apple installation DVD) |

| Windows | port in progress..|

Known issues with specific systems

[[See here]]

Please make sure that CPU throttling is deactivated when compiling the third-party libraries (specifically: ATLAS!). 

Building

Depending on the scope of your work with S/PHI/nX please choose the best fitting building approach:

| | Users | Testers | Developers |

| build S/PHI/nX release |once | once | frequently |

| build S/PHI/nX debug | | once | frequently|

| build SxAccelerate | | | once - frequently |

| build numlibs | | | once - rarely |

   * On machines with N CPUs: you may use parallel make via make -j 2N 

h2. configure options (selection)

| --disable-atlas  --disable-lapack  --enable-mkl  --with-mklpath=... | use MKL for BLAS/LAPACK (support for selected versions) | 	

| --disable-atlas  --disable-lapack  --enable-acml | use ACML for BLAS/LAPACK |

| --enable-mpi | compile MPI version (experimental) |

| --enable-openmp | compile using openmp, try to use openmp numerical libraries (experimental) |

| --with-numlibs=... | all external numerical libraries can be found in these paths (/path/1/:/path/2/:/path/3/) |

| --without-numlibs | external numerical libraries can be found in standard paths or via specified LDFLAGS and CPPFLAGS |

| CXX=... | set C++ compiler |

| CXXFLAGS=... | set additional C++ compiler flags |

| LDFLAGS=... | set additional linker flags (see compiler/linker docu) |

|CPPFLAGS=... | set additional preparser flags (see compiler docu) |

|CPPFLAGS='-I...' | set additional search path for external includes  |

h2. S/PHI/nX users

(Build S/PHI/nX only once to create an optimized executable.)

    # cd sphinx

    # ./setup

    # ./configure --disable-debug --prefix=/instpath/to/sphinx

    # make all install 

If --prefix=/instpath/to/sphinx is omitted, SPHInX will be installed into the current directory.

h2. S/PHI/nX test users

(Build S/PHI/nX in debug and release only once to create an optimized executable as well as a version that can generate a memory core file.)

    # cd sphinx

    # ./setup

    # ./configure --prefix=/instpath/to/sphinx --with-debug --with-release

    # make all install 

Read more about [[being a S/PHI/nX alpha tester]].

h2. S/PHI/nX developers

(Suitable for developers)

h2. Easy build instructions

    * As a simple alternative, you may use the build instruction for test users.

    * Properly configured build directories for debug and release mode will be found as subdirectories in sphinx/sxaccelerate/ and sphinx/, respectively.

    * While developing, there is no need to install (make all install -> make all).

    * You can compile all build directories by a top-level make, ...

    * ... but also each build directory separately (but beware: when changes are made in sxaccelerate, you typically need to rebuild sxaccelerate first, and then sphinx!).

    * For developers, we recommend to build the external libraries separately, as described in the following. Precompiled numlibs avoid repeated installation of the numlibs when top-level make is invoked, and can be reused for concurrent SPHInX versions.

    * use parallel make (make -j ...)

    *use top-level sxmake wrapper instead of make 

h2. Advanced build instructions

p(. 1. cd sphinx

    2. ./setup

    3. Possibly switch to a separate build directory (on a local file system)

<pre>

    mkdir -p /build/path/sphinx

    mkdir -p /build/path/sphinx/sxaccelerate/3rd-party

    cd /build/path/sphinx

</pre>

p(. If a build path is used, replace ./configure by the corresponding absolute filenames to the configure scripts in the source tree.

p(. 4. Building 3rd-party numeric libraries

     # cd sxaccelerate/3rd-party

     # ./configure --prefix=/instpath/to/numlibs

          where /instpath/to/numlibs refers to the folder where the compiled libraries will be installed in.

     # make all install

     # cd ../..

     # optionally clean up:

          rm -rf sxaccelerate/3rd-party 

p(. If --prefix=/instpath/to/numlibs is omitted, numlibs will be installed in sxaccelerate/3rd-party (NO CLEANUP!)

p(. 5. Compile S/PHI/nX

        # ./setup

        # ./configure --prefix=/instpath/to/sphinx --with-debug --with-release --with-numlibs=/instpath/to/numlibs

        # where /instpath/to/sxaccelerate is where the libraries and headers will be installed to.

        # make 

h2. S/PHI/nX core developers

(Suitable only for freaks)

h2. More configure options

| --enable-debug | compile in debug mode (default) |

| --disable-debug | compile in release mode |

| --enable-shared/--disable-shared | enable/disable shared objects/linkage (default: enable) |

| --enable-static/--disable-static | enable/disable static objects/linkage (default: disable) |

| --enable-numlibschecks | check the numlibs install |

h2. Advanced build instructions

p(. 1. Call ./setup in /src/path/to/sphinx

    2. Build 3rd-party numeric libraries (see instructions for developers)

    3. Building sxaccelerate

<pre>

   mkdir -p /build/path/sxaccelerate

   cd /build/path/sxaccelerate

   /src/path/to/sphinx/sxaccelerate/src/configure [options] --with-numlibs=/instpath/to/numlibs

</pre>

p(. For available configure options, see configure --help. You may build debug and release versions side by side using the sxaccelerate/configure --with-debug --with-release - note the omission of the src before the configure in this case! 

p(. 4. Building sphinx on top of an existing sxaccelerate build (or install)

<pre>

    mkdir -p /build/path/sphinx

    cd /build/path/sphinx

    /src/path/to/sphinx/src/configure --with-sxaccelerate=/build/path/sxaccelerate

</pre>

Note that ==*you cannot override any configure options set in the sxaccelerate*== that affect compiler/linker flags or numlibs selection.