\chapter{Download and installation}
\label{chap:installation}
This chapter is intended to be a general introduction 
on how to download, install and use \Atlas. In particular, 
in \sect{s:requirements} we will present the general 
requirements of the library. In \sect{s:installation} we 
will first describe how to install the third-party packages 
required by \Atlas (if supported by ECMWF) and successively 
we will outline how to install \Atlas. Finally, in \sect{s:using}
we show how to use \Atlas by creating a simple example 
that initializes and finalizes the library.


\section{General requirements}
\label{s:requirements}

\Atlas is distributed as Git repository and is available at the ECMWF Stash 
git hosting service: \url{https://software.ecmwf.int/stash/projects}.
This can only be accessed by ECMWF staff within the internal intranet.
Occasionally, access can be granted to external partners working 
on specific projects.

\Atlas is currently available under Stash as \Atlas project 
itself or under the European project ESCAPE. These two repositories 
are separated - specifically the \Atlas project under ESCAPE is 
a so-called Git fork of the main \Atlas project.
Given this structure of the \Atlas project, one can find the 
library either in the main repository:\\
\url{https://software.ecmwf.int/wiki/display/ATLAS/Atlas}\\
or in the ESCAPE repository:\\
\url{https://software.ecmwf.int/stash/projects/ESCAPE/repos/atlas/browse}.\\
If you encounter any problem accessing these pages, please contact 
Willem Deconinck (\url{willem.deconinck@ecmwf.int}).

Note that the main \Atlas project is intended for ECMWF internal 
developments, while the \Atlas project under ESCAPE is intended 
for experimental developments within the ESCAPE project.
Note also that \Atlas requires third-party libraries as described 
in the \sect{s:installation} below.

Finally, \Atlas has been tested and works correctly with the 
following compilers: GCC 4.8.1, Intel 13.0.1, 14.0.1 and CCE 
8.2.7, 8.3.1.


\section{Installation}
\label{s:installation}
\Atlas requires a number of third-party libraries. 
Some of them are external third-party libraries not maintained 
by ECMWF - these external libraries are briefly described 
in \sect{s:external-libs}, where we also provide some 
useful links on how to download and install them. 

Some other third-party libraries are developed and maintained 
by ECMWF. For this set of libraries we provide a download and 
installation instructions in \sect{s:ecmwf-libs}.

\subsection{External third-party dependencies}
\label{s:external-libs}
\Atlas requires the following external third-party libraries 
(some of the links provided may have changed, so we suggest 
the reader to lookup on the web for these packages):
%
\begin{itemize}
\item \textbf{Git}: Required for project management and to download 
the repository. For use and installation see \url{https://git-scm.com/}
\item \textbf{CMake}: Required for configuration and cross-compilation 
purposes. For use and installation see \url{http://www.cmake.org/}
\item \textbf{MPI}: Required for distributed memory parallelisation.
For use and installation see for instance \url{https://www.open-mpi.org/}
\item \textbf{Python}: Required for certain components of the build system.
For use and installation see \url{https://www.python.org/}.
\item \textbf{OpenMP} (optional): Required for shared memory 
parallelisation. For use and installation see \url{http://openmp.org/wp/}
\item \textbf{boost\_unit\_test} (optional): Required for unit testing 
for C++. For use and installation see \url{http://www.boost.org/}
\end{itemize}
%
Note that if you are an ECMWF staff member, you have some of the above 
libraries already available through the module system. In particular 
you can load the following packages as follows:
%
\begin{lstlisting}[style=BashStyle]
module load  git  cmake  python
\end{lstlisting}
%
If you are not an ECMWF staff member you need to either install them 
manually following the links above or ask your system administrator 
to verify whether these packages are already available within your 
working environment.


\subsection{ECMWF third-party dependencies}
\label{s:ecmwf-libs}
\Atlas additionally requires the following projects developed 
at ECMWF:
%
\begin{itemize}
\item \textbf{ecbuild}: It implements some CMake macros that 
are useful for configuring and cross-compiling \Atlas and the 
other ECMWF third-party libraries required by \Atlas. 
For further information, please visit: 
\url{https://software.ecmwf.int/wiki/display/ECBUILD/ecBuild}.
\item \textbf{eckit}: It implements some useful C++
functionalities widely used in ECMWF C++ projects. 
For further information, please 
visit: \url{https://software.ecmwf.int/wiki/display/ECKIT/ecKit}
\item \textbf{fckit} (optional): It implements some useful 
Fortran functionalities. For further information, please 
visit: \url{https://software.ecmwf.int/stash/projects/ECSDK/repos/fckit/browse}
\item \textbf{transi} (optional): It implements the spectral 
transform. For further information, please visit:
\url{https://software.ecmwf.int/stash/projects/ATLAS/repos/transi/browse}
\end{itemize}
%
In the following we will outline how to install each of the 
projects above. 

The first step is to create a folder where to download, build 
and install all the third-party projects required as well as 
where to build and install \Atlas. Let us call this folder 
\inlsh{myproject}, create it and enter into the folder:
%
\begin{lstlisting}[style=BashStyle]
mkdir -p $(pwd)/myproject
cd myproject
\end{lstlisting}
%
We then need to create the following folder tree:
%
\begin{lstlisting}[style=BashStyle]
SRC=$(pwd)/sources
BUILDS=$(pwd)/builds
INSTALL=$(pwd)/install
mkdir -p $SRC 
mkdir -p $BUILDS 
mkdir -p $INSTALL
\end{lstlisting}
%
where the sources directory will contain the source files
of each project, the builds directory will contain the 
built projects and the install directory will contain 
the installation of each project.\\
%
It is guaranteed at any point in time that all ECMWF projects have
a git branches called ``master'' and ``develop''. These branches
respectively in each project are guaranteed to be compatible. The
``master'' branch contains the latest fixed release version of each
project, whereas the ``develop'' branch contains the latest daily
contributions to each project in preparation for future release
versions. It is not guaranteed that the ``develop'' branch of e.g.
\Atlas would be compatible with the ``master'' branch of one if its
dependencies (e.g. eckit).\\
When updating the ``develop'' branch of \Atlas, it might therefore
be advisable to also update the ``develop'' branches of all of its
dependencies.
With the following, we can specify which branch in every project
will be built.
\begin{lstlisting}[style=BashStyle]
BRANCH=master
\end{lstlisting}
%
All ECMWF projects can be built with different optimisation options.
There are the following 
three recommended options:\\
\begin{itemize}
\setlength\itemsep{0.1em}
\item \inlsh{DEBUG}: No optimisation - used for debugging or development
                     purposes only. This option may enable additional
                     boundschecking.
\item \inlsh{BIT}: Maximum optimisation while remaining bit-reproducible.
\item \inlsh{RELEASE}: Maximum optimisation.
\end{itemize}
With the following, we can specify which optimisation to use for the
installation of all projects.
\begin{lstlisting}[style=BashStyle]
BUILD_TYPE=RELEASE
\end{lstlisting}
%
We can now proceed to the download and install
each of the ECMWF projects required by \Atlas.
%
\subsubsection{ecbuild}
To download the project and switch to the correct branch,
we can type on the terminal the commands reported below:
%
\begin{lstlisting}[style=BashStyle]
git clone ssh://git@software.ecmwf.int:7999/ecsdk/ecbuild.git $SRC/ecbuild
cd $SRC/ecbuild
git checkout $BRANCH
\end{lstlisting}
%
This project is constituted by just a few CMake macros 
and it does not need to be compiled nor installed.
We do not need to to any additional step for ecbuild!\\
%
In the ecbuild project resides an executable script called \inlsh{ecbuild}
to aid installation of all following projects. To make this script
easily accessible, prepend it to the \inlsh{PATH}.
\begin{lstlisting}[style=BashStyle]
export PATH=$SRC/ecbuild/bin:$PATH
\end{lstlisting}
%
This executable script \inlsh{ecbuild} acts as a wrapper around the
\inlsh{cmake} executable. More information on this script can be 
obtained:
\begin{lstlisting}[style=BashStyle]
ecbuild --help
\end{lstlisting}
Particular options of the \inlsh{ecbuild} script noteworthy are
\inlsh{\ddash{build}} and \inlsh{\ddash{prefix}}.
\begin{itemize}
\setlength\itemsep{0.1em}
\item \inlsh{\ddash{build}=\$BUILD\_TYPE} sets the build type to specified optimisation
\item \inlsh{\ddash{install}=\$INSTALL} sets the install prefix to the specified path
\end{itemize}

\subsubsection{eckit}
To download the project and switch to the correct branch,
we can type on the terminal the commands reported below:
%
\begin{lstlisting}[style=BashStyle]
git clone ssh://git@software.ecmwf.int:7999/ecsdk/eckit.git $SRC/eckit
cd $SRC/eckit
git checkout $BRANCH
\end{lstlisting}
%
Now that we have downloaded the project and switched 
to the correct branch, we can proceed to build the 
project and install it. We first need to create the 
following folder where the files will be built:
%
\begin{lstlisting}[style=BashStyle]
mkdir $BUILDS/eckit
cd $BUILDS/eckit
\end{lstlisting}
%
Then, we need to run ecbuild in order to configure the 
library - i.e. to find the various dependencies required, 
etc. - and finally we need to run \inlsh{make install} 
to compile and install the library. These two steps are 
reported below:
%
\begin{lstlisting}[style=BashStyle]
ecbuild --build=$BUILD_TYPE --prefix=$INSTALL/eckit -- $SRC/eckit
make -j4 install
\end{lstlisting}
%
Note that if the folder \inlsh{\$INSTALL/eckit} 
is not already present it will be automatically created.

\subsubsection{fckit (optional)}
To download the library and switch to the correct branch called 
\inlsh{develop}, we can type on the terminal the commands reported 
below:
%
\begin{lstlisting}[style=BashStyle]
git clone ssh://git@software.ecmwf.int:7999/ecsdk/fckit.git $SRC/fckit
cd $SRC/fckit
git checkout $BRANCH
\end{lstlisting}
%
Now that we have downloaded the library and switched 
to the develop branch, we can proceed to build the 
library and install it. We first need to create the 
following folder where the files will be built:
%
\begin{lstlisting}[style=BashStyle]
mkdir $BUILDS/fckit
cd $BUILDS/fckit
\end{lstlisting}
%
Then, we need to run ecbuild in order to configure the 
library - i.e. to find the various dependencies required, 
etc. - and finally we need to run \inlsh{make install} 
to compile and install the library. These two steps are 
reported below:
%
\begin{lstlisting}[style=BashStyle]
ecbuild --build=$BUILD_TYPE --prefix=$INSTALL/fckit -- $SRC/fckit
make -j4 install
\end{lstlisting}
%
Note that if the folder \inlsh{\$INSTALL/fckit} 
is not already present it will be automatically created.



\subsubsection{transi (optional)}
To download the library and switch to the correct branch called 
\inlsh{develop}, we can type on the terminal the commands reported 
below:
%
\begin{lstlisting}[style=BashStyle]
git clone ssh://git@software.ecmwf.int:7999/atlas/transi.git $SRC/transi
cd $SRC/transi
git checkout $BRANCH
\end{lstlisting}
%
Now that we have downloaded the library and switched 
to the develop branch, we can proceed to build the 
library and install it. We first need to create the 
following folder where the files will be built:
%
\begin{lstlisting}[style=BashStyle]
mkdir $BUILDS/transi
cd $BUILDS/transi
\end{lstlisting}
%
Then, we need to run ecbuild in order to configure the 
library - i.e. to find the various dependencies required, 
etc. - and finally we need to run \inlsh{make install} 
to compile and install the library. These two steps are 
reported below:
%
\begin{lstlisting}[style=BashStyle]
ecbuild --build=$BUILD_TYPE --prefix=$INSTALL/transi -- $SRC/transi
make -j4 install
\end{lstlisting}
%
Note that if the folder \inlsh{\$INSTALL/transi} is not already 
present it will be automatically created.



\subsection{\Atlas installation}
Once we have downloaded, compiled and installed the third-party 
dependencies described above, we can now download and install 
\Atlas. In particular, to download the library and switch 
to the correct branch called \inlsh{develop}, we can type 
on the terminal the commands reported below:
%
\begin{lstlisting}[style=BashStyle]
git clone ssh://git@software.ecmwf.int:7999/atlas/atlas.git $SRC/atlas
cd $SRC/atlas
git checkout $BRANCH
\end{lstlisting}
%
Now that we have downloaded the library and switched 
to the develop branch, we can proceed to build the 
library and install it. We first need to create the 
following folder where the files will be built:
%
\begin{lstlisting}[style=BashStyle]
mkdir $BUILDS/atlas
cd $BUILDS/atlas
\end{lstlisting}
%
Then, we need to run \inlsh{ecbuild} in order to configure 
the library - i.e. to find the various dependencies required, 
etc. - and finally we need to run \inlsh{make install} 
to compile and install the library. These two steps are 
reported below:
%
\begin{lstlisting}[style=BashStyle]
$SRC/ecbuild/bin/ecbuild --build=$BUILD_TYPE --prefix=$INSTALL/atlas -- \
  -DECKIT_PATH=$INSTALL/eckit \
  -DFCKIT_PATH=$INSTALL/fckit \
  -DTRANSI_PATH=$INSTALL/transi \
  $SRC/atlas
make -j4 install
\end{lstlisting}
%
Note that if the folder \inlsh{\$INSTALL/atlas} is not already 
present it will be automatically created.

The following extra flags may be added to the \inlsh{ecbuild} 
step to fine-tune configuration:
\begin{itemize}
\setlength\itemsep{0.1em}
\item \inlsh{-DENABLE\_OMP=OFF} --- Disable OpenMP
\item \inlsh{-DENABLE\_MPI=OFF} --- Disable MPI
\item \inlsh{-DENABLE\_FORTRAN=OFF} --- Disable Compilation of Fortran bindings
\item \inlsh{-DENABLE\_TRANS=OFF} --- Disable compilation of the spectral transforms
       functionality. This is automatically disabled if the optional \emph{transi}
       dependency is not compiled or found. In this case it is also unnecessary to
       provide \inlsh{-DTRANSI\_PATH=\$INSTALL/transi}.
\end{itemize}
%
%
\begin{notebox}
By default compilation is done using shared libraries. Some systems have 
linking problems with static libraries that have not been compiled with 
the flag \inlsh{-fPIC}. In this case, also compile atlas using static 
linking, by adding to the ecbuild step the flag: \inlsh{\ddash{static}}
\end{notebox}
%
The building and installation of \Atlas should now be complete 
and you can start using it. With this purpose, in the next 
section we show a simple example on how to create a simple 
program to initialize and finalize the library.


\section{Inspecting your \Atlas installation} \label{s:inspect}
Once installation of atlas is complete, an executable called "atlas"
can be found in \inlsh{\$INSTALL/bin/atlas}. Executing 
\begin{lstlisting}[style=BashStyle]
>>> $INSTALL/bin/atlas --version
0.7.0

>>> $INSTALL/bin/atlas --git
2d683ab4aa0c

>>> $INSTALL/bin/atlas --info
atlas version (0.7.0), git-sha1 2d683ab

  Build:
    build type      : Release
    timestamp       : 20160215122606
    op. system      : Darwin-14.5.0 (macosx.64)
    processor       : x86_64
    c compiler      : Clang 7.0.2.7000181
      flags         :  -O3 -DNDEBUG
    c++ compiler    : Clang 7.0.2.7000181
      flags         :  -O3 -DNDEBUG
    fortran compiler: GNU 5.2.0
      flags         :  -fno-openmp -O3 -funroll-all-loops -finline-functions

  Features:
    Fortran        : ON
    MPI            : ON
    OpenMP         : OFF
    BoundsChecking : OFF
    Trans          : ON
    Tesselation    : ON
    gidx_t         : 64 bit integer

  Dependencies: 
    eckit version  (0.12.3), git-sha1 7b76818
    transi version (0.3.2), git-sha1 bf33f60
\end{lstlisting}
%
gives you information respectively on the macro version,
a more detailed git-version-controlled identifier, and finally 
a more complete view on all the features that Atlas has been compiled with,
as well as compiler and compile flag information.
Also printed is the versions of used dependencies such as eckit and transi.

\section{Using \Atlas in your project}
\label{s:using}
In this section, we provide a simple example on how to use \Atlas.
The objective here is not to get familiar with the main 
functionalities of \Atlas, but rather to show how to get started!
Specifically, we will show a simple ``Hello world'' program that
initialises and finalises the library, and uses the internal \Atlas
logging facilities to print ``Hello world!''.
The steps necessary to compile and run the program will be detailed
in this section.

Note that the \Atlas supports both C++ and Fortran, therefore, 
in the following, we will show both an example using C++ and 
an example using Fortran. Before starting, we create a folder 
called \inlsh{project1} in the \inlsh{sources} directory:
%
\begin{lstlisting}[style=BashStyle]
mkdir -p $SRC/project1
\end{lstlisting}
%
Here, we will add both the C++ and Fortran files of this 
simple example. Note that there are (at least) two ways 
to compile the code we are going to write. The first involves 
just using a C compiler for the C++ version and a Fortran 
compiler for the Fortran version, without using any cmake 
files. The second involves using cmake files. In the following, 
we will detail both possibilities.

\subsection{C++ version}
\label{s:atlas-hello-world-C}

\subsubsection*{Program description}
The C++ version of the \Atlas initialization and finalization
calls is depicted in \lista{code1-C}.
%
\lstinputlisting[caption=Initialization and finalization 
of \Atlas using C++, style=CStyle, label=code1-C]{hello-world.cc}
%
We can create a new file in the folder \inlsh{project1} just generated:
%
\begin{lstlisting}[style=BashStyle]
touch $SRC/project1/hello-world.cc
\end{lstlisting}
%
and copy the content of the code in \lista{code1-C} into it.
We can now have a closer look at the code.
On line 1, we include the \Atlas header file, we successively 
specify a simple main function, in which we call the initialization 
of the \Atlas library on line 6.
Note that we passed the two arguments of the main function 
\inltc{argc} and \inltc{argv} to the \inltc{atlas\_init} 
function.
We finally call the \Atlas \inltc{atlas\_finalize()} function 
at line 8 without passing any argument to it.

The function \inltc{atlas\_init()} is responsible for 
setting up the logging facility and for the initialization
of MPI (Message Passage Interface), 
while the function \inltc{atlas\_finalize()} 
is responsible for finalizing MPI and closing the program.
On line 7, we log ``Hello world!'' to the \inltc{info} log
channel.\\
%
\Atlas provides 4 different log channels which can be configured
separately: \inltc{debug}, \inltc{info}, \inltc{warning}, and
\inltc{error}. By default, the \inltc{debug} channel does not
get printed; the \inltc{info} and \inltc{warning} channel get 
printed to the std::cout stream, and the \inltc{error} channel
gets printed to std::cerr. For more information on the logging
facility, the reader is referred to section~\ref{s:utilities-logging}.

\subsubsection*{Code compilation}
We now need to compile the code. We first create a new directory
into the \inlsh{\$BUILDS} folder, where we will compile the code
%
\begin{lstlisting}[style=BashStyle]
mkdir -p $BUILDS/project1
\end{lstlisting}
%
As mentioned above, there are (at least) two ways for compiling 
the source code above. These are detailed below.
%
\begin{description}
%
\item \underline{Directly with C++ compiler}\\[0.5em]
%
The first possibility is to 
avoid using cmake and ecbuild and directly run a C++ compiler, 
such as g++. For doing so, especially when \Atlas is linked statically,
we need to know all \Atlas dependent libraries. This step can be easily
achieved by inspecting the file 
%
\begin{lstlisting}[style=BashStyle]
vi $INSTALL/atlas/lib/pkgconfig/atlas.pc
\end{lstlisting}
%
Here, all the flags necessary for the correct compilation 
of the C++ code in \lista{code1-C} are reported. For 
compiling the code, we first go into the builds directory 
just created and we generate a new folder where the executables 
will be stored: 
%
\begin{lstlisting}[style=BashStyle]
cd $BUILDS/project1
mkdir -p bin
\end{lstlisting}
%
Note that, when using the cmake compilation route, it is not 
necessary to generate the bin directory since it will automatically 
created during compilation.
After having generated the bin folder, we can run the following 
command:
%
\begin{lstlisting}[style=BashStyle]
g++ $SRC/project1/hello-world.cc -o bin/atlas_c-hello-world \ 
  $(pkg-config $INSTALL/atlas/lib/pkgconfig/atlas.pc --libs --cflags)
\end{lstlisting}
%
This will compile our hello-world.cc file and it will automatically 
link all the static and dynamic libraries required by the program. 
The executable, as mentioned, is generated into the folder bin.
%
\item \underline{CMake/ecbuild}\\[0.5em]
%
The second possibility is to create an ecbuild project, which is 
especially beneficial for projects with multiple files, libraries,
and executables.
 In particular, we need to create the following 
cmake file
%
\begin{lstlisting}[style=CMakeStyle]
# File: CMakeLists.txt
cmake_minimum_required(VERSION 2.8.4 FATAL_ERROR)
project(usage_example)

include(ecbuild_system NO_POLICY_SCOPE)
ecbuild_requires_macro_version(1.9)
ecbuild_declare_project()
ecbuild_find_package(NAME atlas REQUIRED)
ecbuild_add_executable(TARGET   atlas_c-usage_example
                       SOURCES  hello-world.cc 
                       INCLUDES ${ATLAS_INCLUDE_DIRS}
                       LIBS     atlas)
ecbuild_print_summary()
\end{lstlisting}
in the sources folder of our project \inlsh{\$SRC/project1}.
We can create the \inlsh{CMakeLists.txt} file in the correct 
directory following the two steps below:
%
\begin{lstlisting}[style=BashStyle]
cd $SRC/project1
touch CMakeLists.txt
\end{lstlisting}
%
and copy the CMake code above into it.
In the second line of the CMake file above, we declare the minimum 
cmake version required to compile the code, while in the second 
line we declare the name of our ecbuild project. 
From line 5 to line 7 we include some required ecbuild macros 
necessary for using ecbuild. On line 8 we specify that the 
\Atlas library is required for this project. Finally, on line 
9 we add the instruction to compile the executable.
Line 13 prints just a compilation summary.
We can build this simple ecbuild project by going into our builds 
directory 
%
\begin{lstlisting}[style=BashStyle]
cd $BUILDS/project1
\end{lstlisting}
%  
and by typing the following command:
%
\begin{lstlisting}[style=BashStyle]
ecbuild -DATLAS_PATH=$INSTALL/atlas $SRC/project1/
make 
\end{lstlisting}
%  
Note that in the above command we needed to provide the path 
to the \Atlas library installation. Alternatively,
\inlsh{ATLAS\_PATH} may be defined as an environment variable.
This completes the compilation of our first example that
uses \Atlas and generates an executable into the bin folder
(automatically generated by cmake) inside our builds directory
for project1.
\end{description}
%

\subsubsection*{Run the code}
After the compilation of the source code is completed, 
we have an executable file into the folder \inlsh{\$BUILDS/project1/bin/}.
If we simply run the executable file as follows:
%
\begin{lstlisting}[style=BashStyle]
./atlas_c-hello-world
\end{lstlisting}
% 
we obtain the output
\begin{lstlisting}[style=BashStyle]
[0] (2016-03-09 T 15:07:15) (I) -- Hello world!
\end{lstlisting}
%
However, by adding \inlsh{\ddash{debug}} to the command line,
also debug information is printed.
In particular, if we type:
%
\begin{lstlisting}[style=BashStyle]
./atlas_c-hello-world --debug
\end{lstlisting}
%
we should obtain something similar to the following output:
%
\begin{lstlisting}[style=BashStyle]
[0] (2016-03-09 T 15:09:42) (D) -- Atlas program [atlas_c-hello-world]
[0] (2016-03-09 T 15:09:42) (D) --   atlas version [0.6.0]
[0] (2016-03-09 T 15:09:42) (D) --   atlas git     
  [dabb76e9b696c57fbe7e595b16f292f45547d628]
[0] (2016-03-09 T 15:09:42) (D) --   eckit version [0.11.0]
[0] (2016-03-09 T 15:09:42) (D) --   eckit git     
  [ac7f6a0b3cb4f60d9dc01c8d33ed8a44a4c6de27]
[0] (2016-03-09 T 15:09:42) (D) --   Configuration read from scripts:
[0] (2016-03-09 T 15:09:42) (D) --   rundir  : 
  /home/na/nagm/myproject/builds/project1
[0] (2016-03-09 T 15:09:42) (I) -- Hello world!
[0] (2016-03-09 T 15:09:42) (D) -- Atlas finalized
\end{lstlisting}
%
which gives us some information such as the version of \Atlas we are 
running, the identifier of the commit and the path of the executable. 



\subsection{Fortran version}
\label{s:atlas-hello-world-F}

\subsubsection*{Program description}
The Fortran version of the \Atlas initialization and finalization 
calls is depicted in \lista{code1-F}.
%
\lstinputlisting[caption=Initialization and finalization of 
\Atlas using Fortran, style=FStyle, label=code1-F]{hello-world.F90}
%
We can create a new file in the folder \inlsh{project1} just generated:
%
\begin{lstlisting}[style=BashStyle]
touch $SRC/project1/hello-world.F90
\end{lstlisting}
%
and copy the content of the code in \lista{code1-F} into it.
We can now have a closer look at the code.
On line 1, we define the program, called \inltf{usage\_example}.
On line 3, we include the required \Atlas libraries
(note that we include only the three functions required 
for this example - i.e. \inltf{atlas\_init}, \inltf{atlas\_finalize}),
and \inltf{atlas\_log}.
The function \inltf{atlas\_init()} on line 8 is responsible for setting up the
logging and for the initialization of MPI (Message Passage Interface), 
while the function \inltf{atlas\_finalize()} on line 10 is responsible for
finalizing MPI and closing the program.
On line 9, we log ``Hello world!'' to the \inltf{info} log channel.\\
%
\Atlas provides 4 different log channels which can be configured
separately: \inltc{debug}, \inltc{info}, \inltc{warning}, and
\inltc{error}. By default, the \inltc{debug} channel does not
get printed; the \inltc{info} and \inltc{warning} channel get 
printed to the std::cout stream, and the \inltc{error} channel
gets printed to std::cerr. For more information on the logging
facility, the reader is referred to section~\ref{s:utilities-logging}.


\subsubsection*{Code compilation}
We now need to compile the code. We first create a new directory
into the \inlsh{\$BUILDS} folder, where we will compile the code
%
\begin{lstlisting}[style=BashStyle]
mkdir -p $BUILDS/project1
\end{lstlisting}
%
As mentioned above, there are (at least) two ways for compiling 
the source code above. These are detailed below.
%
\begin{description}
%
\item \underline{Directly with Fortran compiler}\\[0.5em]
%
The first possibility is to avoid using cmake and ecbuild and 
directly run a Fortran compiler, such as gfortran.
For doing so, especially when \Atlas is linked statically,
we need to know all \Atlas dependent libraries. This step can be easily
achieved by inspecting the file. This step can be easily achieved by inspecting 
the file 
%
\begin{lstlisting}[style=BashStyle]
vi $INSTALL/atlas/lib/pkgconfig/atlas.pc
\end{lstlisting}
%
Here, all the flags necessary for the correct compilation 
of the Fortran code in \lista{code1-F} are reported. For 
compiling the code, we first go into the builds directory 
just created and we generate a new folder where the executables 
will be stored: 
%
\begin{lstlisting}[style=BashStyle]
cd $BUILDS/project1
mkdir -p bin
\end{lstlisting}
%
Note that, when using the cmake compilation route, it is not 
necessary to generate the bin directory since it will automatically 
created during compilation.
After having generated the bin folder, we can run the following 
command:
%
\begin{lstlisting}[style=BashStyle]
gfortran $SRC/project1/hello-world.F90 -o bin/atlas_f-hello-world \ 
$(pkg-config $INSTALL/atlas/lib/pkgconfig/atlas.pc --libs --cflags)
\end{lstlisting}
%
This will compile our hello-world.F90 file and it will automatically 
link all the static and dynamic libraries required by the program. 
The executable, as mentioned, is generated into the folder bin.
%
\item \underline{CMake/ecbuild}\\[0.5em]
%
The second possibility is to use a cmake file that uses some 
ecbuild macros. In particular, we need to create the following 
cmake file:
%
\begin{lstlisting}[style=CMakeStyle]
# File: CMakeLists.txt
cmake_minimum_required(VERSION 2.8.4 FATAL_ERROR)
project(usage_example)

include(ecbuild_system NO_POLICY_SCOPE)
ecbuild_requires_macro_version(1.9)
ecbuild_declare_project()
ecbuild_enable_fortran(MODULE_DIRECTORY ${CMAKE_BINARY_DIR}/module
                       REQUIRED)
ecbuild_find_package(NAME atlas REQUIRED)
ecbuild_add_executable(TARGET  atlas_f-usage_example
                       SOURCES hello-world.F90 
                       INCLUDES ${ATLAS_INCLUDE_DIRS}
                                ${CMAKE_CURRENT_BINARY_DIR}
                       LIBS  atlas_f)
ecbuild_print_summary()
\end{lstlisting}
%
in the sources folder of our project \inlsh{\$SRC/project1}.
We can create the \inlsh{CMakeLists.txt} file in the correct 
directory following the two steps below:
%
\begin{lstlisting}[style=BashStyle]
cd $SRC/project1
touch CMakeLists.txt
\end{lstlisting}
%
and copy the cmake code above into it.
In the second line of the cmake file, we declare the minimum cmake 
version required to compile the code, while in the second line 
we declare the name of our cmake project. 
From line 5 to line 7 we include some required ecbuild macros 
necessary for using ecbuild. On line 8 we enable Fortran compilation, 
while on line 10 we specify that the \Atlas library is required for 
this project. Finally, on line 11 we add the instruction to 
compile the executable.
Line 15 prints just a compilation summary. We can now run this simple 
cmake file by going into our builds directory 
%
\begin{lstlisting}[style=BashStyle]
cd $BUILDS/project1
\end{lstlisting}
%  
and by typing the following command:
%
\begin{lstlisting}[style=BashStyle]
$SRC/ecbuild/bin/ecbuild -DATLAS_PATH=$INSTALL/atlas $SRC/project1/
make 
\end{lstlisting}
%  
Note that in the above command we needed to provide the path 
to the \Atlas library installation.  Alternatively,
\inlsh{ATLAS\_PATH} may be defined as an environment variable.
This completes the compilation of our first example that uses
\Atlas and generates an executable file into the bin folder 
(automatically generated by CMake) inside our builds directory
for project1.
\end{description}
%

\subsubsection*{Run the code}
After the compilation of the source code is completed, 
we have an executable file into the folder \inlsh{\$BUILDS/project1/bin/}.
If we simply run the executable file as follows:
%
\begin{lstlisting}[style=BashStyle]
./atlas_c-hello-world
\end{lstlisting}
% 
we obtain the output
\begin{lstlisting}[style=BashStyle]
[0] (2016-03-09 T 15:27:00) (I) -- Hello world!
\end{lstlisting}
%
However, by setting the environment variable \inlsh{DEBUG=1},
also debug information is printed.
In particular, if we type:
%
\begin{lstlisting}[style=BashStyle]
export DEBUG=1
./atlas_c-hello-world
\end{lstlisting}
%
we should obtain something similar to the following output:
%
\begin{lstlisting}[style=BashStyle]
[0] (2016-03-09 T 15:27:04) (D) -- Atlas program [atlas_f-hello-world]
[0] (2016-03-09 T 15:27:04) (D) --   atlas version [0.6.0]
[0] (2016-03-09 T 15:27:04) (D) --   atlas git     
  [dabb76e9b696c57fbe7e595b16f292f45547d628]
[0] (2016-03-09 T 15:27:04) (D) --   eckit version [0.11.0]
[0] (2016-03-09 T 15:27:04) (D) --   eckit git    
   [ac7f6a0b3cb4f60d9dc01c8d33ed8a44a4c6de27]
[0] (2016-03-09 T 15:27:04) (D) --   Configuration read from scripts:
[0] (2016-03-09 T 15:27:04) (D) --   rundir  :
  /home/na/nagm/myproject/builds/project1
[0] (2016-03-09 T 15:27:04) (I) -- Hello world!
[0] (2016-03-09 T 15:27:04) (D) -- Atlas finalized

\end{lstlisting}
%
which gives us some information such as the version of \Atlas we are 
running, the identifier of the commit and the path of the executable. 
\begin{tipbox}
The outputs obtained for the Fortran and C++ versions should be identical
since they call exactly the same routines. 
\end{tipbox}

This completes your first project that uses the \Atlas library.






