source: JEM-EUSO/esaf_lal/tags/v1_r0/esafdoc/UserGuide/Introduction.tex @ 117

% ESAF User Guide
% $Id: Introduction.tex 2441 2006-02-01 08:29:07Z thea $
% M.Pallavicini, A. Thea - created

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% introduction
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Introduction}%
%\addcontentsline{toc}{section}{Introduction}
\label{sec:intro}
\esaf{} stands for Euso Simulation and Analysis Framework.  It is a software
framework developed for the Extreme Universe Space Observatory, EUSO.

It is an integrated software designed to handle the event simulation chain
(shower development simulation, light production due to fluorescence and
Cerenkov, atmospheric effects, light transport to the Euso detector and the
response of the Euso detector itself) and the reconstruction and analysis of
both simulated events and of the real events.

This note is a simple User Guide, therefore very little space is devoted to the
description of the internal structure of ESAF and of the code. The reader
should look at the ESAF document in the bibliography. 

The topic addressed in this document are basically the following:

\begin{itemize}
\item Requirements
\item Getting the source code
\item Compiling, linking and updating
\item Running \Simu{}
\item Output Root file structure
\item The reconstruction code
\end{itemize}

The \esaf{} code is written in C++ and Fortran and is based on the \ROOT{}
package~\cite{bib:root}. Although the code is written in a highly portable way,
because of lack of man power we support the Linux platform only. 

The compiler is the standard gcc version 3.2 or higher~\cite{bib:gcc}.  Several
Linux distributions have been used in the recent years without major problems.

Even if we do NOT give any support, we encourage the user to try to port the
code to different UNIX platforms if needed, because it should not create major
problems. 


\subsection{Requirements}%
%\addcontentsline{toc}{subsection}{Requirements}

\begin{description}

\item[gcc] version 3.2 or higher must be installed on your system.  Type
\code{gcc -v} to get the version. If you get an error here, you don't have \code{gcc}
at all! 

\item[\ROOT] must be installed and configured; the \code{ROOTSYS} environment
variable must be properly set and must point to a recent version of \ROOT{}
(3.10.2 or higher). Development is carried on using the last \textbf{pro}
version available (differences among \textbf{new}, \textbf{pro} and
\textbf{old} are explained on \ROOT{} website) therefore we strongly suggest
keep the \ROOT{} version up to date. If you do not know how to set the
\code{ROOTSYS} variable, ask your local system manager.

\item[g77] The Fortran compiler sometimes is not included in the Linux
distribution. Make sure that it is installed on your machine and eventually
contact your computer administrator to get it.

\item[zlib] We use compressed ASCII files and we need the zlib library
\cite{bib:zlib}.  This is a very standard library available for any UNIX
platform.  Be sure that you have it.
\end{description}


\subsection{Getting the code}%
%\addcontentsline{toc}{subsection}{Getting the code}

The \esaf{} code is available through \textbf{CVS} (Concurrent Version System) 
\cite{bib:cvs} from the CVS server at the Lyon in2p3 Computing Center.
The code is available in "read-only" mode for normal users and in 
read/write mode for developers.

In the normal read-only mode, the user should configure his ssh directory first.
Inside your directory \code{.ssh}, create an ASCII file named \code{config} with
the following lines:

\begin{displaycode}
Host cvs.in2p3.fr
     Port 2222
     User euso
     PasswordAuthentication yes
     RSAAuthentication no
     PubkeyAuthentication no
     ForwardX11 no
     ForwardAgent no
\end{displaycode}

Then the user should set the following UNIX environment variables (see CVS
manual for details):

\begin{displaycode}
[user]# export CVSROOT=euso@cvs.in2p3.fr:/cvs/euso/
[user]# export CVS_RSH=ssh 
\end{displaycode}

After these settings are done you are ready to get the code with the standard
CVS command:

\begin{displaycode}
[user]# cvs co esaf
\end{displaycode}

The developer that needs write acces to the CVS repository must get in contact
with the \esaf{} group and get an account at the Lyon CC. The complete
documentation about Lyon CVS accounts are available on the Lyon CC webpage
\cite{bib:cvslyon}.

\subsection{Compiling and Linking}%
%\addcontentsline{toc}{subsection}{Compiling and Linking}

Once you have the \esaf{} source code, compiling is a very simple task. 
Just enter into the \esaf{} directory that CVS has created in the place 
where you typed \code{cvs co esaf} and then type \code{make}.

The compilation and linking may take several minutes, depending on the 
machine you are using. If everything went fine, at the end you should have 
2 executable files in the \code{bin/i686} directory, named \code{\Simu{}} and 
\code{\Reco{}}. 

Compilation and or Linking may fail for several reasons; if so, and you didn't
modified the code, make sure that all requirements are satisfied.

\subsection{Updating the code}
%\addcontentsline{toc}{subsection}{Updating the code}

\esaf{} is continuously updated (developing and debugging); in most cases
changes are small and don't affect \esaf{}'s behaviour deeply. On the contrary
sometimes are so significant to require a total rebuild of the code and may and
affect also the output files so that they are not compatible between different
versions of the program. Therefore we advise to keep the code up-to-date.
\code{}
To do this just go in \code{esaf} directory and type at the system prompt

\begin{displaycode}
[user]# cvs up -d
\end{displaycode}

This updates files that are changed, deleted or created; the optiona flag
\code{-d} is needed when new directory has been added to the repository. This
doesn't occur often, so basically you can just type \code{cvs up}.

It is also possible to update each directory or file indipendently running
\code{cvs up} from the directory itself (as long as in that directory there
is a subdirectory \code{CVS}).

There is an \esaf{} CVS mailing list that keeps the users informed whenever new
code is committed to the repository and that sends the list of the modified
files. If you are interested to receive these mails, you are invited to contact
the authors.

\subsection{Building options}
%\addcontentsline{toc}{subsection}{Building options}

In the main \esaf{} directory the \code{Rules} file contains the compilation
options.

The most important option for the user is \code{ESAFTMP}; this variable points
to the directory where \code{make} saves the temporary object files for creation
of libraries and binaries. Default directory is:

\begin{displaycode}
ESAFTMP = /tmp
\end{displaycode}

In some cases is advisable to change the default directory (editing the file
\code{Rules}) because the directory \code{/tmp}, present in all systems, is
generally emptied when you reboot the machine.

In \code{ESAFTMP} directory contains \code{ESAFTMP.username/architeture/} in
which are other subdirectories, one for each library of \esaf{}.

\subsection{Cleaning and rebuilding}
%\addcontentsline{toc}{subsection}{Cleaning and rebuilding}

Sometimes, after a major change or when an obsolete file is removed from
repository \code{make} could fail to rebuild \esaf{}. This is due to old
temporary files in \code{ESAFSYS} that conflicts with the new code. To get rid
of them two ways exist.

In most cases \code{make} is able to clean \code{ESAFSYS} by itself. Just go in
\code{esaf/} directory and type

\begin{displaycode} 
[user]# make clean
[user]# make
\end{displaycode}

If also \code{make clean} fails or the compilation is still broken,
\code{ESAFSYS} must be deleted by hand.

\begin{displaycode}
[user]# cd [ESAFTMP]
[user]# rm -rf
[user]# cd [ESAFSYS]
[user]# make
\end{displaycode}

As last chance, if you still have problems, you can delete the entire \code{esaf/}
and the \code{ESAFTMP} directories and reinstall \esaf{}.

The other options in the file \code{Rules} is \code{DEBUG}, for compiling with
(\code{DEBUG = 1}) or without (\code{DEBUG = 0}) debugger support.
%and \code{VERBOSE\_COMPILING} in order to visualize or not each single step of
%compilation.