%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Copyright (c) 2003-2018 by The University of Queensland
% http://www.uq.edu.au
%
% Primary Business: Queensland, Australia
% Licensed under the Apache License, version 2.0
% http://www.apache.org/licenses/LICENSE-2.0
%
% Development until 2012 by Earth Systems Science Computational Center (ESSCC)
% Development 2012-2013 by School of Earth Sciences
% Development from 2014 by Centre for Geoscience Computing (GeoComp)
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Installing from source for \linux}
\label{sec:srclinux}

\subsection{Dependencies}

The following instructions assume you are running the \file{bash} shell.
Comments are indicated with \# characters.
Make sure you have the following installed:
\begin{itemize}
 \item \file{g++} and associated tools.
 \item \file{make}
 % I suspect that these are only needed by VTK and if we aren't using it anymore they could be removed
%  \item \file{libXext.so}\footnote{In Debian this is in the libXext-dev package.}
%  \item \file{libxt.so}\footnote{In Debian this is in the libxt-dev package.}
\end{itemize}

\noindent To compile matplotlib you will also need the following\footnote{For
Debian and Ubuntu users, installing \file{libfreetype6-dev} and
\file{libpng-dev} will be sufficient.} (if your distribution separates
development files, make sure to get the development packages):
\begin{itemize}
 \item \file{freetype2}
 \item \file{zlib}
 \item \file{libpng}
\end{itemize}

\noindent In order to fully test the installation using the unit tests you also
need\footnote{On Debian and Ubuntu this is packaged as \file{libcppunit-dev}}:
\begin{itemize}
 \item \file{cppunit}
\end{itemize}
However, a large number of tests will work without it.

\subsection{Preliminaries}
\label{sec:prelim}
You will also need a copy of the \esfinley source code.
If you retrieved the source using subversion, don't forget that one can use the export command instead of checkout to get a smaller copy.
For additional visualization functionality see Section~\ref{sec:addfunc}.

These instructions will produce the following directory structure:
\begin{itemize}
 \item[] \file{stand} \begin{itemize}
  \item[] \file{escript.d}
  \item[] \file{pkg}
  \item[] \file{pkg_src}
  \item[] \file{build}
  \item[] \file{doc}
 \end{itemize}
\end{itemize}

Before you start copy the \esfinley source into the \file{escript.d} directory.
The following instructions refer to software versions in the \file{escript-support-3-src} bundle.
If you download your own versions of those packages substitute their version numbers and names as appropriate.
There are a number of uses of the \file{make} command in the following instructions.
If your computer has multiple cores/processors you can speed up the compilation process by adding -j 2 after the make command.
For example to use all processors on a computer with 4 cores:
\begin{shellCode}
make
\end{shellCode}
becomes
\begin{shellCode}
make -j 4
\end{shellCode}

\begin{shellCode}
mkdir stand
cd stand
mkdir build doc pkg pkg_src
export PKG_ROOT=$(pwd)/pkg
\end{shellCode}

\subsection{Building the dependencies}

Copy the compressed sources for the packages into \file{stand/pkg_src}.
If you are using the support bundles, decompress them in the stand directory:
\begin{shellCode}
tar -xjf escript-support-3-src.tar.bz2
\end{shellCode}

Copy documentation files into \file{doc} then unpack the archives:

\begin{shellCode}
cd build
tar -jxf ../pkg_src/Python-2.6.2.tar.bz2
tar -jxf ../pkg_src/boost_1_39_0.tar.bz2
tar -zxf ../pkg_src/scons-1.2.0.tar.gz
tar -zxf ../pkg_src/numpy-1.3.0.tar.gz
tar -zxf ../pkg_src/netcdf-4.0.tar.gz
tar -zxf ../pkg_src/matplotlib-0.98.5.3.tar.gz
\end{shellCode}

\begin{itemize}

\item Build Python:
\begin{shellCode}
cd Python*
./configure --prefix=$PKG_ROOT/python-2.6.2 --enable-shared 2>&1 \
  | tee tt.configure.out
make 
make install 2>&1 | tee tt.make.out

cd ..

export PATH=$PKG_ROOT/python/bin:$PATH
export PYTHONHOME=$PKG_ROOT/python
export LD_LIBRARY_PATH=$PKG_ROOT/python/lib:$LD_LIBRARY_PATH

pushd ../pkg
ln -s python-2.6.2/ python
popd
\end{shellCode}

Run the new python executable to make sure it works.

\item Now build NumPy:
\begin{shellCode}
cd numpy-1.3.0
python setup.py build
python setup.py install --prefix $PKG_ROOT/numpy-1.3.0
cd ..
pushd ../pkg
ln -s numpy-1.3.0 numpy
popd
export PYTHONPATH=$PKG_ROOT/numpy/lib/python2.6/site-packages:$PYTHONPATH
\end{shellCode}

% \begin{shellCode}
% cd numarray-1.5.2
% 
% python setup.py install \
%  --gencode --install-lib=$PKG_ROOT/numarray-1.5.2/lib \
%  --install-headers=$PKG_ROOT=$PKG_ROOT/numarray-1.5.2/include/numarray \ 
%    2>&1 | tee tt.install.out
% 
% 
% export PYTHONPATH=$PKG_ROOT/numarray/lib:$PYTHONPATH
% cd ..
% pushd ../pkg
% ln -s numarray-1.5.2 numarray
% popd
% \end{shellCode}

\item Next build scons:
\begin{shellCode}
cd scons-1.2.0
python setup.py install --prefix=$PKG_ROOT/scons-1.2.0

export PATH=$PKG_ROOT/scons/bin:$PATH
cd ..
pushd ../pkg
ln -s scons-1.2.0 scons
popd
\end{shellCode}

\item The Boost libraries...:
\begin{shellCode}
pushd ../pkg
mkdir boost_1_39_0
ln -s boost_1_39_0 boost
popd
cd boost_1_39_0
./bootstrap.sh --with-libraries=python --prefix=$PKG_ROOT/boost
./bjam
./bjam install --prefix=$PKG_ROOT/boost --libdir=$PKG_ROOT/boost/lib
export LD_LIBRARY_PATH=$PKG_ROOT/boost/lib:$LD_LIBRARY_PATH
cd ..
pushd ../pkg/boost/lib/
ln *.so.* libboost_python.so
popd
\end{shellCode}

\item ...and netCDF:
\begin{shellCode}
cd netcdf-4.0
CFLAGS="-O2 -fPIC -Df2cFortran" CXXFLAGS="-O2 -fPIC -Df2cFortran" \
FFLAGS="-O2 -fPIC -Df2cFortran" FCFLAGS="-O2 -fPIC -Df2cFortran" \
./configure --prefix=$PKG_ROOT/netcdf-4.0

make 
make install

export LD_LIBRARY_PATH=$PKG_ROOT/netcdf/lib:$LD_LIBRARY_PATH
cd ..
pushd ../pkg
ln -s netcdf-4.0 netcdf
popd
\end{shellCode}

\item Finally matplotlib:
\begin{shellCode}
cd matplotlib-0.98.5.3
python setup.py build
python setup.py install --prefix=$PKG_ROOT/matplotlib-0.98.5.3
cd ..
pushd ../pkg
ln -s matplotlib-0.98.5.3 matplotlib
popd
cd ..
\end{shellCode}

\end{itemize}

\subsection{Compiling escript}\label{sec:compileescriptlinux}

Change to the directory containing your escript source (\file{stand/escript.d}), then:

\begin{shellCode}
cd escript.d/scons
cp TEMPLATE_linux.py YourMachineName_options.py

echo $PKG_ROOT
\end{shellCode}
Where \texttt{YourMachineName} is the name of your computer as returned by the hostname command.
If the name contains non-alphanumeric characters, then you will need to replace them with underscores.
For example the options file for \texttt{bob-desktop} would be named \file{bob_desktop_options.py}.
If you wish to build with OpenMP, MPI or configure other aspects of the system take a quick look at Section~\ref{sec:compilesrc}.


You will need to edit your options file and specify where to find boost and netcdf.
(replace \file{x/stand} with the path to \file{stand})

\begin{python}
#boost_prefix = '/usr/local'
\end{python}

should be
\begin{python}
boost_prefix = ['x/stand/pkg/boost/include/boost-1_39/', 'x/stand/pkg/boost/lib/']
\end{python}

\begin{python}
#netcdf = True
\end{python}

should be
\begin{python}
netcdf = True
\end{python}

\begin{python}
#netcdf_prefix = '/usr/local'
\end{python}

should be \begin{python}
netcdf_prefix = ['x/stand/pkg/netcdf/include/', 
			'x/stand/pkg/netcdf/lib/']
\end{python}

% 
% Edit the options file and put the value of PKG_ROOT between the quotes in the PKG_ROOT= line.
% For example:
% \begin{shellCode}
% PKG_ROOT="/home/bob/stand/pkg"
% \end{shellCode}

\begin{shellCode}
cd ../bin
\end{shellCode}

Modify the STANDALONE line of \file{run-escript} to read:
 
STANDALONE=1

Start a new terminal and go to the \file{stand} directory.

\begin{shellCode}
export PATH=$(pwd)/pkg/scons/bin:$PATH
cd escript.d
eval $(bin/run-escript -e)
scons
\end{shellCode}

If you wish to test your build, then you can do the following. 
Note this may take a while if you have a slow processor and/or less than 1GB of RAM.
\begin{shellCode}
scons py_tests
\end{shellCode}
(If you have cppunit installed you can run additional tests using \texttt{scons all_tests}.

\subsection{Cleaning up}
Once you are satisfied, the \file{escript.d/build} and \file{stand/build} directories can be removed.

If you \emph{really} want to save space and do not wish to be able to edit or recompile \esfinley, you can remove the following:
\begin{itemize}
 \item From the \file{escript.d} directory:\begin{itemize}
\item Everything except: \file{bin}, \file{include}, \file{lib}, \file{esys},
\file{README_LICENSE}.
\item Hidden files, which can be removed using
\begin{shellCode}
find . -name '.?*' | xargs rm -rf
\end{shellCode}
in the \file{escript.d} directory.
\end{itemize}
\item from the \file{pkg} directory:
\begin{itemize}
\item  \file{scons}, \file{scons-1.2.0}
\end{itemize}
\item \file{package\_src}\footnote{Do not remove this if you intend to redistribute.}.
\end{itemize}

Please note that removing all these files may make it more difficult for us to diagnose problems.