/*
 * Copyright (c) 2012-2015:  G-CSC, Goethe University Frankfurt
 * Author: Ingo Heppner
 * 
 * This file is part of UG4.
 * 
 * UG4 is free software: you can redistribute it and/or modify it under the
 * terms of the GNU Lesser General Public License version 3 (as published by the
 * Free Software Foundation) with the following additional attribution
 * requirements (according to LGPL/GPL v3 §7):
 * 
 * (1) The following notice must be displayed in the Appropriate Legal Notices
 * of covered and combined works: "Based on UG4 (www.ug4.org/license)".
 * 
 * (2) The following notice must be displayed at a prominent place in the
 * terminal output of covered works: "Based on UG4 (www.ug4.org/license)".
 * 
 * (3) The following bibliography is recommended for citation and must be
 * preserved in all covered files:
 * "Reiter, S., Vogel, A., Heppner, I., Rupp, M., and Wittum, G. A massively
 *   parallel geometric multigrid solver on hierarchically distributed grids.
 *   Computing and visualization in science 16, 4 (2013), 151-164"
 * "Vogel, A., Reiter, S., Rupp, M., Nägel, A., and Wittum, G. UG4 -- a novel
 *   flexible software system for simulating pde based models on high performance
 *   computers. Computing and visualization in science 16, 4 (2013), 165-179"
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
 */

/** \page pageAdditionalSoftware Prerequisites and Recommendend Tools

[TOC]

\note This page is outdated. Please use \ref pageUginstall .


On this page you'll find short installation instructions for additional software
that might be useful &mdash; or is even necessary &mdash; for working with \ug4 
(especially on clusters).

So, in case a software needed for a certain task is not available on the system
(or has the wrong version number) one has to install it locally (unless you have
administrator privileges - congratulations ...)

We propose the following procedures for which we assume that all additional
software is installed in a directory \c local directly in your home directory 
(version numbers are those of the most recent (stable) versions at the time this 
documentation was written).

A basic understanding of the used Unix tools (\c wget, \c tar, ...) is useful 
but not necessary (instructions should work "out of the box" &mdash; except for 
the version numbers &mdash; check for a version that is appropriate for you and 
adapt the respective file name).

Instead of using \c wget, you can also use \c curl (as is installed on \em Mac), 
like
\verbatim
curl -O http://www.cmake.org/files/v2.8/cmake-2.8.6.tar.gz 
\endverbatim

<hr>
\section secInstallCMake Installation of CMake (required)

CMake can be installed with
\verbatim
uginstall cmake
\endverbatim
see \ref pageUginstall.

If that fails:
You may install CMake through a pre-built installer, which can be obtained here:
http://www.cmake.org/cmake/resources/software.html (min Release 2.6).
Be sure to install the command line tools, when prompted during installation.

You can alternatively compile and install a local version of the
<a href="http://www.cmake.org">CMake build tool</a> by doing the following 
steps:
<ol>
  <li>Download tar ball:
    \verbatim
cd ~/local
wget http://www.cmake.org/files/v2.8/cmake-2.8.6.tar.gz
    \endverbatim
  </li>
  <li>Unpack:
    \verbatim
tar xvzf cmake-2.8.6.tar.gz
    \endverbatim
  </li>
  <li>Configure and build:
    \verbatim
cd cmake-2.8.6/
./bootstrap --prefix=$HOME/local
make
make install
    \endverbatim
  </li>
  <li>Shortcut for executing \em CMake from command-line (i.e., add a line like 
    the following in your <tt>.bashrc</tt> (for Bash):
    \verbatim
alias cmake='$HOME/local/bin/cmake'
    \endverbatim
    or (for Tcsh):
    \verbatim
alias cmake '$HOME/local/bin/cmake'
    \endverbatim
  </li>
</ol>


<hr>
\section secInstallBoost Installation of Boost (optional)

A version of the <a href="http://www.boost.org">Boost library</a> is 
automatically checked out and available in the <tt>externals/</tt> sub 
directory of your trunk (since Jan 2012), so a local installation is usually no 
longer necessary for building \ug4.
But if you need a special (e.g. newer) version, you can get one this way:
<ol>
  <li>Download tar ball:
    \verbatim
cd ~/local
wget http://sourceforge.net/projects/boost/files/boost/1.48.0/boost_1_48_0.tar.gz
    \endverbatim
  </li>

  <li>Unpack (no build necessary!) into a directory which has to be contained 
    in your search path (see next step):
    \verbatim
tar xzf boost_1_48_0.tar.gz
    \endverbatim
  </li>

  <li>and add \em Boost root directory to search path (i.e., add a line like the
    following in your <tt>.profile</tt> (for Bash):
    \verbatim
export PATH=$PATH:$HOME/local/boost_1_48_0
    \endverbatim
    or (for Tcsh):
    \verbatim
set PATH = ($PATH $HOME/local/boost_1_48_0)
    \endverbatim
  </li>

  <li>Instruct \em CMake to use your own copy of \em Boost when configuring \ug4
    \verbatim
cmake -DINTERNAL_BOOST=OFF <further cmake parameters> ..
    \endverbatim
  </li>
</ol>


<hr>
\section secInstallLUA Installation of LUA (optional)

You can install a local version of the <a href="http://www.lua.org">Lua 
interpreter</a> by performing the following steps, so that you are able to 
execute Lua scripts "stand alone" (i.e. without utilising \ug4's Lua 
capabilities):
<ol>
  <li>Download tar ball:
    \verbatim
cd ~/local
wget http://www.lua.org/ftp/lua-5.1.4.tar.gz
    \endverbatim
  </li>
  <li>Unpack:
    \verbatim
tar xvzf lua-5.1.4.tar.gz
    \endverbatim
  </li>
  <li>Build and install (cf. <tt>INSTALL</tt>):
    \verbatim
cd lua-5.1.4/
make linux
make local
    \endverbatim
  </li>
  <li>Shortcut for executing Lua from command-line (i.e., add a line like the
    following in your <tt>.bashrc</tt> (for Bash)):
    \verbatim
alias lua='$HOME/local/lua-5.1.4/bin/lua'
    \endverbatim
    or (for Tcsh):
    \verbatim
alias lua '$HOME/local/lua-5.1.4/bin/lua'
    \endverbatim
  </li>
  <li>Usage example, executing (a local copy of) the "analyser script" 
    described in \ref secScalabilityTestsSpecific :
    \verbatim
lua my_scaling_analyzer.lua
    \endverbatim
  </li>
</ol>


<hr>
\section secInstallParaView Installation of ParaView (optional)

You can install a local version of <a href="http://paraview.org/">ParaView</a>
by performing the following steps (only described for installation of a 
"precompiled binary", which usually will be the preferred way):
<ol>
  <li>Download tar ball:<br>
    Go to http://www.paraview.org/paraview/resources/software.php and choose 
    the version, type (e.g. <em>"ParaView Binary Installer"</em>) and OS, and 
    download the tar ball and move it in the directory where you want to 
    install \em ParaView:
    \verbatim
mv ParaView-3.14.0-Linux-64bit.tar.gz ~/local
    \endverbatim
  </li>
  <li>Unpack:
    \verbatim
cd ~/local
tar xvzf ParaView-3.14.0-Linux-64bit.tar.gz 
    \endverbatim
  </li>
  <li>After unpacking a binary installer the executables reside in e.g.
    \verbatim
ParaView-3.14.0-Linux-64bit/
    \endverbatim
    See the documentation (e.g. http://paraview.org/Wiki/The_ParaView_Tutorial)
    for how to build \em ParaView from sources (\em CMake and a compiler (of 
    course) necessary &mdash; and a bit time).
  </li>
  <li>Shortcuts for executing the \em ParaView client and server from 
    command-line (i.e., add lines like the following in your <tt>.bashrc</tt> 
    (for Bash)):
    \verbatim
alias paraview='$HOME/local/ParaView-3.14.0-Linux-64bit/bin/paraview'
alias pvserver='$HOME/local/ParaView-3.14.0-Linux-64bit/bin/pvserver'
    \endverbatim
    or (for Tcsh):
    \verbatim
alias paraview '$HOME/local/ParaView-3.14.0-Linux-64bit/bin/paraview'
alias pvserver '$HOME/local/ParaView-3.14.0-Linux-64bit/bin/pvserver'
    \endverbatim
  </li>
  <li>Basic usage (using the shortcut mentioned above):
    <ul>
      <li>Start an instance of \em ParaView and load a datafile:
        \verbatim
paraview --data=<VTK-File>
        \endverbatim
      </li>
      <li>Start an instance of \em ParaView and load a (previously saved) state 
        file (with ending <tt>.pvsm</tt>):
        \verbatim
paraview --state=<state file>
        \endverbatim
      </li>
    </ul>
  </li>
</ol>

For parallel rendering see e.g. \ref pageParallelRendering.

<hr>
\section secInstallLAPACK Installation BLAS/LAPACK (optional)

<ul>
  <li> Note: On most systems, LAPACK and BLAS are preinstalled and are found by cmake.
  <li> On some clusters, LAPACK/BLAS are kind of "built into" the compiler,
  so you don't have to specify anything. In this case, use<br>
  <tt>cmake -DBUILTIN_BLAS=ON -DBUILTIN_LAPACK=ON</tt> <br>
  Ask the administrator for help.  
  <li> On some systems, you'd have to install LAPACK/BLAS manually. 
  You can do this on most systems via their package managers. 
  <li> If you can't find/get/install the packages: 
  Download <a href="http://www.tacc.utexas.edu/tacc-projects/gotoblas2">GotoBLAS2</a>.
  <li> extract the source to <tt>~/software/GotoBLAS2/</tt>
  <li> Choose one of the <tt>quickbuild.*</tt> files there and execute it.
  <li> Now add the path <tt>~/software/GotoBLAS2</tt> to the environment variable
  <tt>LD_LIBRARY_PATH</tt> by adding the line
  \verbatim
  LD_LIBRARY_PATH=$LD_LIBRARY_PATH:~/software/GotoBLAS2/
  \endverbatim
  add the end of your <tt>~/.bashrc</tt>.
  <li> remember to <tt> source ~/.bashrc</tt>
  <li> Now cmake should accept GotoBLAS2 as LAPACK/BLAS library.
</ul>

 */
