.. _installation:

Installation
============

The following instructions build AMPX as distributed before SCALE 6.1.  
For SCALE 6.2 and beyond, AMPX is included in the full SCALE installation.  
Refer to :numref:`sec-scale.install` for instructions to install SCALE.

The AMPX build is based on CMake from KitWare, which supports a consistent
experience on LINUX, Mac, and Windows.

AMPX requires:

- | Intel Fortran/C++ 13.1 or higher
  | or
  | GNU GCC/G++/GFORTAN 4.6.1 or higher

- CMake --- Platform independent build configuration

- QT 4.7 or higher

Optionally, AMPX requires LAPACK and  BLAS libraries.

There are four main steps to create an AMPX installation:

1. CMake configuration creates a native build tree

2. Compilation compiles all executables and libraries

3. Optionally run test cases

4. Installation --- This deploys all executables into a configuration ready for running

:file:`CMakeLists.txt` files are found throughout AMPX. From the AMPX root directory,
these CMakeLists.txt files create a tree of included directories called the
SOURCE TREE.

To configure a build, ``cmake`` is called on the root CMakeLists.txt file, namely
:file:`ampx_dir/CMakeLists.txt`. CMake takes the SOURCE TREE and creates a BUILD TREE.
The BUILD TREE contains or will contain the build configuration, Make files, and
all compilation output (i.e., object files, archive libraries and binary
executables). Then ``make install`` in the build directory will install the
packages, and an optional ``ctest`` command will run several tests to ensure that
AMPX was built correctly.

AMPX requires QT and optionally LAPACK and BLAS routines. If these libraries
reside in a known location (i.e., installed by yum or macports [see below]), the
installation procedure will automatically find the libraries. Otherwise the
location can be given at configuration time.

.. recommended-install:

Recommended Installation Procedure
----------------------------------

1. Navigate to the root scale directory, where :file:`CMakeLists.txt`,
   PackagesList.cmake and CTestConfig.cmake are shown. This is the root of the
   source tree that at which CMake will be pointed.

2. Make a build directory:
    ::

      mkdir build
      cd build

    and create a cmake script in this directory called configure with content similar to:

    ::

      #!/bin/bash
      INSTALL_PATH=${PWD}/install
      OPTIONS=${PWD}/../script/options_ampx_packages.cmake
      cmake \
              -D SCALE_ENABLE_TESTS:BOOL="ON" \
              -D SCALE_CONFIGURE_OPTIONS_FILE:FILEPATH=${OPTIONS} \
                     -D DART_TESTING_TIMEOUT:STRING=6500 \
              -D CMAKE_INSTALL_PREFIX:FILEPATH=${INSTALL_PATH} \
              -D CMAKE_BUILD_TYPE:STRING=RELEASE \
              -D CMAKE_Fortran_COMPILER:STRING=gfortran \
              -D CMAKE_CXX_COMPILER:STRING=g++ \
              -D CMAKE_C_COMPILER:STRING=gcc \
              $*

    and make it executable:

    ::

      chmod u+x configure

    An example script file is provided in the script directory:
    *configure_ampx_gcc* for gnu compilers and *configure_ampx_intel* for intel
    compilers.

3. Create the build tree by running

   ::

     ./configure ../

4. Install the packages by running

   ::

      make install

   and optionally run the test suite:

   ::

     ctest

5. If third party libraries are not found, the user may need to specify the path
   to them. For QT, add

   ::

      -D CMAKE_PREFIX_PATH=/Path_to_QT_directory/bin \

   to the configure script. For LAPACK and BLAS, add:

   ::

     -D TPL_LAPACK_LIBRARIES:STRING=/Path_to_lapack_libs/lib/liblapack.so\
     -D TPL_BLAS_LIBRARIES:STRING=/Path_to_lapack_libs//lib/libblas.so\

   to the configure script.

Every library and executable is a TARGET. Calling 'make' on Linux and Mac will
build ALL targets. For example, typing *make x10* will  build only the x10
executable.

CMAKE_Fortran_COMPILER,  CMAKE_Fortran_FLAGS,  CMAKE_C_COMPILER, CMAKE_C_FLAGS,
CMAKE_CXX_COMPILER, and CMAKE_CXX_FLAGS may be modified in the cmake command
invocation line to update the compilers or compiler flags to the desired
settings.

.. _mac-osx:

Mac OS X
--------

XCode is needed to compile AMPX on a Mac OS X computer. It is available free
from the App Store. In addition, the command line options from XCode must be
installed. This can be accomplished by navigating to
XCode->Preferences->Downloads->Components->Command Line Tools, and clicking
"Install."

The latest version of macports, downloadable from http://www.macports.org, is
also required.

If the rsync is blocked by a firewall, macports can be synchronized over http by
changing the file :file:`/opt/local/etc/macports/sources.conf`, changing the line:

::

  rsync://rsync.macports.org/release/tarballs/ports.tar [default]

to

::

  http://www.macports.org/files/ports.tar.gz [default]

The following commands will install all necessary components from macports:

If rsync port is blocked use:

::

   sudo port -d sync

If rsync port is open:

::

  sudo port selfupdate

Regardless of rsync status, the following commands should be executed:

::

  sudo port install gcc48
  sudo port install qt4-mac
  sudo port install cmake

These commands upgrade the default compilers from gcc-4.2.2 to gcc-4.8.2, and
they install qt4.8.4 and cmake. Newer versions may be used if available from
macports. Once the new version is installed, the default gcc version must be
selected. First the available versions are listed:

::

   port select --list gcc

And then one of the available ports should be selected via:

::

  sudo port select --set gcc mp-gcc48

Installation will then proceed in the same manner as on Linux.