%
%     This file is part of the Code_Saturne Preprocessor, element of the
%     Code_Saturne CFD tool.
%
%     Copyright (C) 1998-2007 EDF S.A., France
%
%     contact: saturne-support@edf.fr
%
%     The Code_Saturne Preprocessor is free software; you can redistribute it
%     and/or modify it under the terms of the GNU General Public License
%     as published by the Free Software Foundation; either version 2 of
%     the License, or (at your option) any later version.
%
%     The Code_Saturne Preprocessor 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 General Public License for more details.
%
%     You should have received a copy of the GNU General Public License
%     along with the Code_Saturne Preprocessor; if not, write to the
%     Free Software Foundation, Inc.,
%     51 Franklin St, Fifth Floor,
%     Boston, MA  02110-1301  USA
%


\section[Compilation et aide au débogage]{Compilation et\\ aide au débogage
  \label{cha:compilation}}


\subsection{Compilation\label{sec:compilation}}


\subsubsection{Configuration pour la compilation\label{sec:compil.config}}

Le \pcs utilise maintenant le système de configuration et de compilation
GNU (Autoconf / Automake / Libtool), qui possède sa propre documentation.

Pour obtenir la liste des options de configuration disponible,
dans le répertoire racine du \pcs, il suffit de taper la commande~:
{\tt ./configure~--help}.

La plupart des systèmes actuels disposent d'une commande {\tt make}
capable de gérer la compilation depuis un répertoire différent
de celui des sources (support {\tt VPATH}). Si c'est le cas sur le
système utilisé, il est conseillé de configurer le \pcs depuis
un répertoire différent de son arborescence, afin de laisser celle-ci
inchangée par rapport à la référence. Sinon, on peut toujours
installer {\tt gmake}, le {\tt make} du système GNU (le standard
sous Linux) pour disposer de cette fonctionnalité.

Par exemple, si l'arborescence du \pcs se situe sous \\
{\tt/home/saturne/Enveloppe/ecs-2.0.0.src}\\
les commandes suivantes
permettront sa configuration en mode \og debug \fg et son installation sous\\
{\tt/home/saturne/Enveloppe/ecs-2.0.0/arch/Linux}~:

\begin{verbatim}
> cd /home/saturne/Enveloppe
> mkdir ecs_build
> cd ecs_build
> ../ecs-2.0.0.src/configure \
 --prefix=/home/saturne/Enveloppe/ecs-2.0.0/arch/Linux \
 --enable-debug
> make
> make install
> make clean
\end{verbatim}

Les options de {\tt ./configure} les plus utiles pour le \pcs sont les
suivantes~:

\noindent
\begin{tabular}{|l|%
                >{\PreserveBackslash\raggedright\hspace{0pt}}p{9.0cm}|}
\hline
Option                                  & Fonction \\
\hline
\hline
\verb:--enable-debug:                   & compilation en mode \og debug \fg
                                          plutôt qu'en mode optimisé  \\
\hline
\verb:--with-bft-prefix=:$<$chemin$>$   & chemin d'installation de la librairie
                                          BFT (en général nécessaire si
                                          différent d'un chemin système) \\
\hline
\verb:--with-hdf5-prefix=:$<$chemin$>$  & chemin d'installation des librairies HDF5 et MED \\
\verb:--with-med-prefix=:$<$chemin$>$   & \\
\verb:--disable-med:                    & pas de support MED même si les
                                          librairies sont détectées \\
\hline
\verb:--with-cgns-prefix=:$<$chemin$>$  & chemin d'installation de la librairie
                                          CGNS \\
\verb:--with-cgns-exec-prefix=:$<$chemin$>$ & chemin d'installation de la partie
                                          dépendante du système de la librairie
                                          CGNS (si différent du précédent) \\
\verb:--disable-cgns:                   & pas de support CGNS même si la
                                          librairie est détectée \\
\hline
\verb:--with-metis-libdir=:$<$chemin$>$ & chemin auquel se trouve la librairie
                                          METIS (\verb:libmetis.a:) \\
\verb:--disable-metis:                  & pas de support METIS même si la
                                          librairie est détectée \\
\hline
\end{tabular}

Si la version de {\tt make} utilisée ne supporte pas la logique {\tt VPATH},
alors on sera limité à la compilation depuis l'arborescence source
(dans quel cas on pourra utiliser {\tt make distclean} plutôt que
{\tt make clean} pour ramener le répertoire à l'état le plus proche
possible de son état initial~:

\newpage

\begin{verbatim}
> cd /home/saturne/Enveloppe/ecs-2.0.0.src
> ./configure --prefix=/home/saturne/Enveloppe/ecs-2.0.0/arch/Linux \
 --enable-debug
> make
> make install
> make distclean
\end{verbatim}

Les plates-formes sur lesquelles le \pcs est régulièrement compilé
sont mentionnées dans le tableau ci-dessous.

\begin{center}
\begin{tabular}{|l|l|l|}
\hline
\multicolumn{1}{|c}{Plate-forme} & \multicolumn{1}{|c|}{\fc{`uname -s`}} \\
\hline
IBM Power 5 (Frontal Blue Gene/L)                 & \verb:Linux:  \\
Station Linux (Debian Sarge et Etch)              & \verb:Linux:  \\
Cluster AMD Opteron (Red Hat EL 4, Chatou, CCRT)  & \verb:Linux:  \\
Cluster Itanium II (Bull Novascale, CCRT)         & \verb:Linux:  \\
SUN Sparc (Solaris 8)                             & \verb:SunOS:  \\
\hline
\end{tabular}
\end{center}

Le \pcs a été utilisé régulièrement mais n'est plus maintenu sur les plateformes
suivantes, qui ne sont plus utilisées ou disponibles~:

\begin{center}
\begin{tabular}{|l|l|l|}
\hline
\multicolumn{1}{|c}{Plate-forme} & \multicolumn{1}{|c|}{\fc{`uname -s`}} \\
\hline
Alpha EV68 sous Tru64 Unix (HP Alphaserver, CCRT) & \verb:OSF1:   \\
SGI (Irix 6.5)                                    & \verb:IRIX64: \\
HP 9000 (HP-UX 10.2, HP-UX 11)                    & \verb:HP-UX:  \\
PC Linux (Red Hat 7.2, Debian 2.2)                & \verb:Linux: \\
Cluster PC Linux MFEE (Red Hat 8.0)               & \verb:Linux:  \\
Cluster PC Linux MFEE (Red Hat 7.2 avec)          & \verb:Linux: \\
Fujitsu VPP5000                                   & \verb:UNIX_System_V: \\
\hline
\end{tabular}
\end{center}

Finalement le \CS a été compilé et testé à l'occasion sur de nombreuses
architectures, dont~:

\begin{liste}
\item de nombreuses variantes de Linux sous PC (Red Hat 8.0, Fedora Core 4,
      SuSE 7.1 à 9.1, SUSE 9.2 à 10.2 Mandrake 9 et 10, etc.) avec diverses
      versions du compilateur GCC (2.95, 2.96, 3.1 à 3.4, 4.0.2 à 4.3.1)~;
\item sur un machine SGI Altix (Linux avec patchs SGI, processeur
      Intel Itanium II, compilateur Intel).
\end{liste}

\subsubsection{Options de compilation\label{sec:compil.opt}}

Il est possible de choisir le compilateur C et l'éditeur de
liens au moyen de la variable d'environnement \fc{CC}, comme suit~:

\noindent
\verb:> ./configure --prefix=:$<$chemin$>$\verb: CC=:$<$compilateur$>$

De même, il est possible d'utiliser d'autres options de compilation et
d'édition de liens que celles fournies par défaut, en renseignant les
variables d'environnement \fc{CPPFLAGS} (préprocesseur C), \fc{CFLAGS}
(compilation), et \fc{LDFLAGS} (édition de liens) lors de l'appel
à \fc{configure}.

On peut aussi, au lieu de remplacer les options par défaut, les compléter,
avec les variables d'environnement \fc{CPP\_ADD}, \fc{CC\_ADD}, \fc{LD\_ADD},
et \fc{LIBS\_ADD}.


\subsubsection{Variables d'environnement dépendantes du système d'exploitation
  \label{sec:compil.var}}

Il existe des variables qui dépendent du système et qui sont positionnées
automatiquement dans le fichier \fc{ecs\_config.h} généré par le script
\fc{configure} et inclus dans les sources.

On donne ci-dessous, le rôle joué par chacune de ces variables, lorsqu'elles
sont définies~:

\begin{center}
\begin{tabular}{|l|l|}
\hline
\multicolumn{1}{|c}{Variable} & \multicolumn{1}{|c|}{Rôle} \\
\hline
\verb:_POSIX_SOURCE: & (Variable déclarée par la norme POSIX) \\
                     & Utilisation de fonctions POSIX\\
\verb:_XOPEN_SOURCE: & (Variable déclarée par la norme X-OPEN)\\
                     & Utilisation de fonctions X-OPEN\\
\verb:_XOPEN_SOURCE_EXTENDED: & (Variable déclarée par la norme X-OPEN2)\\
                     & Utilisation de fonctions X-OPEN2\\
\verb:HAVE_CGNS:     & permet l'utilisation de la librairie \CGNS\\
\verb:HAVE_MED:      & permet l'utilisation de la librairie \med\\
\verb:HAVE_METIS:    & permet l'utilisation de la librairie \Metis\\
\hline
\end{tabular}
\end{center}


\subsection{Mémoire\label{sec:mem}}

Une fonctionnalité du \pcs donne la possibilité de retranscrire l'état
de la mémoire à chaque allocation ou libération d'un bloc mémoire.
Ceci est utile surtout si l'on ne dispose pas d'un outil comme
{\em Purify} ou {\em Valgrind}.

Cette fonctionnalité est prise en compte dans le \pcs chaque fois que la
variable d'environnement {\tt CS\_PREPROCESS\_MEM\_LOG} a été positionnée
à l'exécution.\\

Cette fonctionnalité réalise automatiquement~:
\begin{liste}
\item pour chaque allocation~:
  \begin{liste}
  \item l'impression sur fichier de la taille mémoire allouée~;
  \item l'impression sur fichier du cumul de la mémoire allouée~;
  \end{liste}
\item pour chaque libération~:
  \begin{liste}
    \item l'impression sur fichier de la taille mémoire libérée~;
    \item la vérification que le bloc libéré a bien été alloué~;
  \end{liste}
\end{liste}


\subsection{Impression de la structure Maillage\label{sec:impression}}

Le \pcs offre la possibilité de retranscrire sur fichier
le contenu d'une structure\\
\maillaget ainsi que de toutes ses structures
composantes.

La retranscription est faite par défaut dans le fichier
\begin{quote}
\begin{alltt}
ecs_impression.ascii
\end{alltt}
\end{quote}
chaque fois que la fonction
\begin{quote}
\begin{alltt}
ecs_maillage__imprime()
\end{alltt}
\end{quote}
est appelée (soit avant et après les principales étapes du traitement),
à condition d'ajouter l'option documentée uniquement
ici {\tt -dump [n]} à la ligne de commande du \pcs, où {\emph n} indique
que l'on imprime les {\emph n} premiers et derniers éléments de chaque
tableau (0 par défaut).

Cette fonction prend pour argument~:
\begin{liste}
\item la structure \maillaget à imprimer~;
\item le nom du fichier où est faite l'impression~;
\item un titre dont le rôle est de séparer différentes impressions
de la structure \maillaget pour différents appels.
\end{liste}

\begin{quote}
\begin{alltt}
void ecs_maillage__imprime
(
 const ecs_maillage_t *this_maillage,
 const char           *nom_fichier_dump,
 const char           *titre
)
\end{alltt}
\end{quote}


%\passepage

