%-------------------------------------------------------------------------------

% This file is part of Code_Saturne, a general-purpose CFD tool.
%
% Copyright (C) 1998-2013 EDF S.A.
%
% This program 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.
%
% 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 General Public License for more
% details.
%
% You should have received a copy of the GNU General Public License along with
% this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
% Street, Fifth Floor, Boston, MA 02110-1301, USA.

%-------------------------------------------------------------------------------

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Short doc CS class corresponding to article
\documentclass[a4paper,10pt,twoside]{csshortdoc}
% Additional macros
\usepackage{csmacros}
\usepackage[usenames, dvipsnames]{color}
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Packages and commands for PDF documents and hyperlinks
\hypersetup{%
  pdftitle = {CodeSaturne installation guide},
  pdfauthor = {MFEE},
  pdfpagemode = UseOutlines
}
\pdfinfo{/CreationDate (D:20100802000000-01 00 )}
%
% To have thumbnails upon opening the document under ACROREAD
% pdfpagemode = UseThumbs
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Info for title pages
\titreCS{\CS version~\verscs installation guide}

\docassociesCS{}
\resumeCS{This document presents all the necessary elements to install
with \CS version \verscs.

\begin{center}
\large{WORK IN PROGRESS}
\end{center}
}
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Document start
\begin{document}

\def\contentsname{\textbf{\normalsize TABLE OF CONTENTS}\pdfbookmark[1]{Table of
contents}{contents}}

\renewcommand{\logocs}{cs_logo_wire_black}

\pdfbookmark[1]{Flyleaf}{pdg}
\large
\makepdgCS
\normalsize

\passepage

\begin{center}\begin{singlespace}
\tableofcontents
\end{singlespace}\end{center}

\section{\CS Automated or manual installation\label{sec:inst_types}}

\CS may be installed either directly through its GNU Autotools based
scripts (the traditional \texttt{configure}, \texttt{make}, \texttt{make install})
sequence), or using an automated installer (\texttt{install\_saturne.py}),
which generates an initial \texttt{setup} file when run a first time,
and builds and installs \CS and some optional libraries based on the
edited \texttt{setup} when run a second time. The use of this automated script
is briefly explained in the top-level \texttt{README} file of the \CS
sources, as well as in the comments of \texttt{setup} file. It is not detailed
further in this documentation, which details the manuel installation, allowing
a finer control over installation options.

Note that when the automatic installer is run, it generates a build directory,
in which the build may be modified (re-running \texttt{configure}, possibly
adapting the command logged at the beginning of the \texttt{config.status}
file) and resumed.

\section{Installation basics\label{sec:install_basics}}

The installation scripts of \CS are based on the GNU Autotools,
(Autoconf, Automake, and Libtool), so it should be familiar for many
administrators. A few remarks are given here:

\begin{itemize}
\item As with most software with modern build systems, it is recommended
      to build the code in a separate directory from the sources. This
      allows multiple builds (for example production and debug), and is
      considered good practice. Building directly in the source tree is
      not regularly tested, and is not guaranteed to work, in addition
      to ``polluting'' the source directory with build files.
\item By default, optional libraries which may be used by \CS are
      enabled automatically if detected in default search paths
      (i.e. \texttt{/usr/} and \texttt{/usr/local}. To find libraries
      associated with a package installed in an alternate path,
      a \texttt{--with-<package>=...} option to the \texttt{configure} script
      must given. To disable the use of a library which would be
      detected automatically, a matching \texttt{--without-<package>} option
      must be passed to \texttt{configure} instead.
\item Most third-party libraries usable by \CS are considered optional,
      and are simply not used if not detected, but the libraries needed by
      the GUI are considered mandatory, unless the \texttt{--disable-gui}
      or \texttt{--disable-frontend} option is explicitly used.
\end{itemize}

When the prerequisites are available, and a build directory
created, building and installing \CS may be as simple as running:

\fbox{\begin{minipage}{\textwidth}\texttt{\\
\$ ../../code\_saturne-\verscs/configure\\
\$ make\\
\$ make install\\
}\end{minipage}}

The following chapters give more details on \CS's recommended
third-party libraries, configuration recommendations, troubleshooting,
and post-installation options.

\section{Third-Party libraries\label{sec:ext_lib}}

For a minimal build of \CS, a Posix system with a C and a Fortran compiler,
a Python interpreter and a {\tt make} tool should be sufficient.
For parallel runs, an MPI library is also necessary.
To build an use the GUI, Libxml2 and PyQt4 (which in turn requires
Qt4 and SIP) are required.
Other libraries may be used for additional mesh format options,
as well as to improve performance. A list of those libraries
and their role is given in \S\ref{sec:list_ext_lib}.

\subsection{Installing third-party libraries for \CS\label%
{sec:obtain_ext_lib}}

Third-Party libraries usable with \CS may be installed in several
ways:

\begin{itemize}
\item On many Linux systems, most of libraries listed in
      \S\ref{sec:list_ext_lib} are available through the distribution's
      package manager.\footnote{On Mac OS X systems, package managers such as
      Fink or MacPorts also provide package management, even though the
      base system does not.} This requires administrator privileges,
      but is by far the easiest way to install third-party libraries
      for \CS.

      Note that distributions usually split libraries or tools into runtime
      and development packages, and that although some packages are
      installed by default on many systems, this is generally not the
      case for the associated development headers. Development
      packages usually have the same name as the matching runtime package,
      with a \texttt{-dev} postfix added. For example, on a Debian or
      Ubuntu system ,\texttt{libxml2} is usually installed by default,
      but \texttt{libxml2-dev} must also be installed for the \CS
      build to be able to use the former.

\item On many large compute clusters, Environment Modules allow
      the administrators to provide multiple versions of many
      scientific libraries, as well us compilers or MPI libraries,
      using the \texttt{module} command. More details on
      Environment Modules may be found at \url{http://modules.sourceforge.net}.
      When being configured and installed \CS checks for modules loaded
      with the \texttt{module} command, and records the list of loaded
      modules. Whenever running that build of \CS, the modules detected
      at installation time will be used, rather than those defined by
      default in the user's environment. This allows using versions of
      \CS built with different modules safely and easily, even if the
      user may be experimenting with other modules for various purposes.

\item If not otherwise available, third-party software may be compiled
      an installed by an administrator or a user. An administrator
      will choose where software may be installed, but for a user
      without administrator privileges or write access to
      \texttt{usr/local}, installation to a user account is often
      the only option. None of the third-party libraries usable
      by \CS require administrator privileges, so they may all be
      installed normally in a user account, provided the user
      has sufficient expertise to install them. This is usually not
      complicated (provided one reads the installation instructions,
      and is prepared to read error messages if something goes wrong),
      but even for an experienced user or administrator, compiling
      and installing 5 or 6 libraries as a prerequisite significantly
      increases the effort required to install \CS.

      Even though it is more time-consuming, compiling and installing
      third-party software may be necessary when no matching packages
      or Environment Modules are available, or when a more recent version
      or a build with different options is desired.
\end{itemize}

\subsection{List of third-party libraries usable by \CS\label%
{sec:list_ext_lib}}

The list of third-party software usable with \CS is provided here:

\begin{itemize}

\item BLAS (Basic Linear Algebra Subroutines) may be used by the
      \texttt{cs\_blas\_test} unit test to compare the cost of operations
      such as vector sums and dot products with those provided
      by the code and compiler.
      If no third-party BLAS is provided, \CS reverts to its own
      implementation of BLAS routines, so no functionality is lost here.
      Optimized BLAS libraries such as Atlas, MKL, ESSL, or ACML may be very
      fast for BLAS3 (dense matrix/matrix operations), but the advantage is
      usually much less significant for BLAS 1 (vector/vector) operations, which
      are almost the only ones \CS has the opportunity of using.
      \CS uses its own dot product implementation (using a superblock algorithm,
      for better precision), and $y \leftarrow ax+y$ operations, so external
      BLAS1 are not used for computation, but only for unit testing (so as
      to be able to compare performance of built-in BLAS with external BLAS).
      The Intel MKL BLAS may also be used for matrix-vector products, so it
      is linked with the solver when available, but this is also currently only
      used in unit benchmark mode.
      Note that in some cases, threaded BLAS routines might oversubscribe
      processor cores in some MPI calculations, depending on the way both
      \CS and the BLAS were configured and interact, and this can actually
      lead to lower performance.
      Use of BLAS libraries is thus useful as a unit benchmarking feature,
      but has no influence on full calculations.

\item PyQt4 is required by the \CS GUI. PyQt4 in turn requires Qt4,
      Python,and SIP. Without this library, the GUI may not be built,
      although XML files generated with another install of \CS
      may be used if Libxml2 is available.

\item Libxml2 is required to read XML files edited with the GUI.
      If this library is not available, only user subroutines may
      be used to setup data.

\item HDF5 is necessary for MED, and may also be used by CGNS.

\item CGNSlib is necessary to read or write mesh and visualization files
      using the CGNS format, available as an export format with many
      third-party meshing tools,

\item MED is necessary to read or write mesh and visualization files
      using the MED format, mainly used by the SALOME platform.

\item libCCMIO is necessary to read or write mesh and visualization files
      generated or readable by \starccmp using its native format.

\item \scotch or \ptscotch may be used to optimize mesh partitioning.
      Depending on the mesh, parallel computations with meshes partitioned
      with these libraries may be from 10\% to 50\% faster than using the
      built-in space-filling curve based partitioning.

      As \scotch and \ptscotch use symbols with the same names, only
      one of the 2 may be used. If both are detected, \ptscotch is used.

\item \metis or \parmetis are alternative mesh partitioning libraries.
      These libraries have a separate source tree, but some of their
      functions have identical names, so only one of the 2 may be used.
      If both are available, \parmetis will be used. Partitioning
      quality is usually slightly lower than that obtained with \scotch or
      \ptscotch, but these libraries are faster.

      Though broadly available, the \parmetis license is quite restrictive,
      so \ptscotch may be preferred (\CS may be built with both
      \metis and \scotch libraries). Also, the \metis licence was changed
      in March 2013 to the Apache 2 licence, so it would not be surprising
      for future \parmetis versions to follow.

\item \texttt{eos-1.2} may be used for thermodynamical properties of fluids.

\end{itemize}

For developers, the GNU Autotools (Autoconf, Automake, Libtool) as
well as gettext will be necessary. To build the documentation,
pdf\LaTeX{} and \texttt{fig2dev} (part of TransFig) will be necessary.

\subsection{Notes on some third-party tools and libraries}

\subsubsection{Python and PyQt4\label{sec:ext:python}}

\CS requires a Python interpreter, with Python version 2.4 or above.
The base scripts should work both with Python 2 or Python 3 versions,
but have not been tested recently with the latter. The GUI is Python 2
only, so using Python 3 is not currently recommended.

While \CS makes heavy use of Python, this is for scripts and for the GUI only;
The solver only uses compiled code, so we may for example use
a 32-bit version of Python with 64-bit \CS libraries and executables.

The GUI is written in PyQt4 (Python bindings for Qt4), so but Qt4 and
the matching Python bindings must be available. On most modern
Linux distributions, this is available through the package manager,
which is by far the preferred solution. When running on a system which does
not provide these libraries, there are several alternatives:

\begin{itemize}

\item build \CS without the GUI. If built with Libxml2, XML files
      produced with the GUI are still usable, so if an install of \CS
      with the GUI is available on an other machine, the XML files
      may be copied on the current machine. This is certainly not an optimal
      solution, but in the case where users have a mix of desktop or virtual
      machines with modern Linux distributions and PyQt4 installed, and
      a compute cluster with an older system, this may avoid requiring
      a build of Qt4 and PyQt4 on the cluster if users find this too daunting.

\item Install a local Python interpreter, and add Qt4 bindings to this
      interpreter.

      Python (\url{http://www.python.org}) and Qt4
      (\url{http://qt.nokia.com/products}) must be downloaded  and
      installed first, in any order. The installation instructions of
      both of these tools are quite clear, and though the installation of these
      large packages (especially Qt4) may be a lengthy process in terms of
      compilation time, but is well automated and usually devoid of nasty
      surprises.\footnote{The only case in which the \CS developers
      have has issues with Qt4 was when trying to force an install into
      64-bit mode with the GNU compilers (version 4.1.2) on a PowerPC 64
      architecture running SLES 10 Linux, on which compilers default
      to building 32 bit code, although 64 bit is available. Using default
      options on the same machine led to a perfectly functional 32-bit Qt
      installation}.

      Once Python is installed, the SIP bindings generator
      (\url{http://riverbankcomputing.co.uk/software/sip/intro})
      must also be installed. This is a small package, and configuring it
      simply requires running \texttt{python configure.py} in its source
      tree, using the Python interpreter just installed.

      Finally, the PyQt4 bindings
      (\url{http://riverbankcomputing.co.uk/software/pyqt/intro}) may be
      installed, in a manner similar to SIP.

      When this is finished, the local Python interpreter contains
      the PyQt4 bindings, and may be used by \CS's \texttt{configure}
      script by passing \texttt{PYTHON=<path\_to\_python\_executable}.

\item add Python Qt4 bindings as a Python extension module for an existing
      Python installation. This is a more elegant solution than the previous
      one, and avoids requiring rebuilding Python, but if the user does not
      have administrator privileges, the extensions will be placed in a
      directory that is not on the default Python extension search path, and
      that must be added to the \texttt{PYTHONPATH} environment variable.
      This works fine, but for all users using this build of \CS, the
      \texttt{PYTHONPATH} environment variable will need to be
      set.\footnote{In the future, the \CS installation scripts could check
      the \texttt{PYTHONPATH} variable and save its state in the build so as
      to ensure all the requisite directories are searched for.}

      The process is similar to the previous one, but SIP and PyQt4
      installation requires a few additional configuration options
      in this case. See the SIP and PyQt4 reference guides for
      detailed instructions, especially the \emph{Building a Private
      Copy of the SIP Module} section of the SIP guide.

\end{itemize}

\subsubsection{\scotch and \ptscotch\label{sec:ext:scotch}}

Note that both \scotch and \ptscotch may be built from the same source
tree, and installed together with no name conflicts.

For better performance, \ptscotch may be built to use threads with concurrent
MPI calls. This requires initializing MPI with \texttt{MPI\_Init\_thread}
with \texttt{MPI\_THREAD\_MULTIPLE} (instead of the more restrictive
\texttt{MPI\_THREAD\_SERIALIZED}, \texttt{MPI\_THREAD\_FUNNELED}, or
\texttt{MPI\_THREAD\_SINGLE}, or simply using \texttt{MPI\_Init}).
As \CS does not support thread models in which different threads may call
MPI functions simultaneously, and the use of \texttt{MPI\_THREAD\_MULTIPLE}
may carry a performance penalty, we prefer to sacrifice some of
\ptscotch's performance by requiring that it be compiled without the
\texttt{-DSCOTCH\_PTHREAD} flag. This is not detected at compilation time,
but with recent MPI libraries, \ptscotch will complain at run time
if it notices that the MPI thread safety level in insufficient.

Detailed build instructions, including troubleshooting instructions,
are given in the source tree's \texttt{INSTALL.txt} file.
In case of trouble, note especially the explanation relative to the
\texttt{dummysizes} executable, which is run to determine the
sizes of structures. On BlueGene/P type machines, it may be necessary
to start the build process, let it fail, run this executable
manually using \texttt{mpirun}, then pursue the build process.

\subsubsection{\med\label{sec:ext:med}}

The Autotools installation of MED is simple on most machines,
but a few remarks may be useful for specific cases.

MED has a C API, is written in a mix of C and C++ code,
and provides both a C (\texttt{libmedC}) and an Fortran API
(\texttt{libmed}). Both libraries are always built, so a Fortran
compiler is required, but \CS only links using the C API, so using
a different Fortran compiler to build MED and \CS is possible.

MED does require a C++ runtime library, which is usually transparent
when shared libraries are used. When built with static libraries
only, this is not sufficient, so when testing for a MED library,
the \CS \texttt{configure} script also tries linking with a C++
compiler if linking with a C compiler fails. This must be the
same compiler that was used for MED, to ensure the runtime matches.
The choice of this C++ compiler may be defined passing the
standard \texttt{CXX} variable to \texttt{configure}.

Also, when building MED in a cross-compiling situation,
\texttt{--med-int=int} or \texttt{--med-int=int64\_t} (depending
on whether 32 or 64 bit ids should be used) should be
passed to its \texttt{configure} script to avoid a run-time
test.

\subsubsection{libCCMIO\label{sec:ext:libccmio}}

Different versions of this library may use different build
systems, and use different names for library directories,
so using both the \texttt{--with-ccm=} or \texttt{--with-ccm-include=}
and \texttt{--with-ccm-lib=} options to \texttt{configure} is
usually necessary.
Also, the include directory should be the toplevel library,
as header files are searched under a \texttt{libccmio}
subdirectory\footnote{this is made necessary by libCCMIO version
2.6.1, in which this is hardcoded in headers including other
headers. In more recent versions such as 2.06.023, this is not the
case anymore, and an \texttt{include} subdirectory is present, but
it does not contain the \texttt{libccmioversion.h} file, which is
found only under the \texttt{libccmio} subdirectory, and is required
by \CS to handle differences between versions, so that source
directory is preferred to the installation \texttt{include}.}

A libCCMIO distribution usually contains precompiled
binaries, but recompiling the library is recommended.
Note that at least for version 2.06.023, the build will fail
building dump utilities, due to the \texttt{-l adf} option
being placed too early in the link command. To avoid this,
add \texttt{LDLIBS=-ladf} to the makefile command, for example:

\texttt{make -f Makefile.linux SHARED=1 LDLIBS=-ladf}

(\texttt{SHARED=1} and \texttt{DEBUG=1} may be used to force
shared library or debug builds respectively).

Finally, if using libCCMIO 2.6.1, remove the \texttt{libcgns*}
files from the libCCMIO libraries directory if also building
\CS with CGNS support, as those libraries are not required
for CCMIO, and are are an obsolete version of CGNS, which
may interfere with the version used by \CS.

\subsubsection{libxml2\label{sec:ext:libxml2}}

This library is usually available on all general purpose Linux
distributions, so it does not generally need to be rebuilt,
although the associated developpement package (and headers) must
as usual be installed.

For HPC clusters, it might not be available by default on compute nodes,
so it may need to be compiled. This library may be downloaded
at\url{ftp://xmlsoft.org/libxml2/} (with a possible mirror at
\url{ftp://fr.rpmfind.net/pub/libxml/}). All versions tested so far
(at least versions 2.6 to 2.9) have worked well with \CS, but to avoid
compilation issues (as well as generating a smaller library), it
may be useful to add the \texttt{--with-ftp=no --with-http=no} options
to libxml2's \texttt{configure} script.

\section{Preparing for build\label{sec:prepare}}

If the code was obtained as an archive, it must be unpacked:

\texttt{tar xvzf saturne.tar.gz}

If for example you unpacked the directory in a directory
named \texttt{/home/user/Code\_Saturne}, you will now
have a directory named \texttt{/home/user/Code\_Saturne/saturne}.

It is recommended to build the code in a separate directory from the source.
This also allows multiple builds, for example, building both an
optimized and a debugging version. In this case, choose a consistent
naming scheme, using an additional level of sub-directories,
for example:

\fbox{\begin{minipage}{\textwidth}\texttt{\\
\$ mkdir saturne\_build\\
\$ cd saturne\_build\\
\$ mkdir prod\\
\$ cd prod%
}\end{minipage}}

Some older system's {\tt make} command may not support compilation
in a directory different from the source directory ({\tt VPATH}
support). In this case, installing and using the GNU {\tt gmake}
tool instead of the native {\tt make} is recommended.

\subsection{Source trees obtained through a source code repository\label{sec:preparerepo}}

For developers obtaining the code was obtained through a version control
system such as Subversion, an additional step is required:

\fbox{\begin{minipage}{\textwidth}\texttt{\\
\$ cd saturne\\
\$ autoreconf -vi\\
\$ cd ..
}\end{minipage}}

In this case, additional tools need to be available:

\begin{itemize}
\item GNU Autotools: Autoconf, Automake, Libtool (2.2 or 2.4), and Gettext.
\item Bison (or Yacc) and Flex (or Lex)
\item PdfLaTeX and TransFig
\end{itemize}

These tools are not necessary for builds from tarballs; they
are called when building the tarball (using {\tt make dist}), so
as to reduce the number of prerequisites for regular users, while
developers building the code from a repository can be expected to
need a more complete developement environment.

Also, to build and install the documentation when building the code
from a repository instead of a tarball, the following stages are required:

\fbox{\begin{minipage}{\textwidth}\texttt{\\
\$ make pdf\\
\$ make install-pdf
}\end{minipage}}

\section{Configuration\label{sec:config}}

\CS uses a build system based on the GNU Autotools, which includes
its own documentation.

To obtain the full list of available configuration options,
run: {\tt configure~--help}.

Note that for all options starting with {\tt --enable-},
there is a matching options with {\tt --disable-}. Similarly,
for every {\tt --with-}, {\tt --without-} is also possible.

Select configuration options, then run {\tt configure}, for example:

\fbox{\begin{minipage}{\textwidth}\texttt{\\
\$ /home/user/Code\_Saturne/3.0/src/code\_saturne-\verscs/configure \textbackslash \\
\textcolor{Violet}{--prefix}=/home/user/Code\_Saturne/3.0/arch/prod
\textbackslash \\
\textcolor{Violet}{--with-med}=/home/user/opt/med-3.0 \textbackslash \\
\textcolor{red}{CC}=/home/user/opt/mpich2-1.4/bin/mpicc \textcolor{red}{FC}=gfortran
}\end{minipage}}

In the rest of this section, we will assume that we are in
a build directory separate from sources, as described in
\S\ref{sec:prepare}. In different examples, we assume
that third-party libraries used by \CS are either available
as part of the base system (i.e. as packages in a Linux distribution),
as Environment Modules, or are installed under a separate path.

\subsection{Debug builds\label{sec:config:shared}}

It may be useful to install debug builds alongside production
builds of \CS, especially when user subroutines are used
and the risk of crashes due to user programming error is high.
Running the code using a debug build is significantly
slower, but more information may be available in the case
of a crash, helping understand and fix the problem faster.

Here, having a consistent and practical naming scheme is useful.
For a side-by-side debug build for the example above, we simply replace \texttt{prod} by
\texttt{dbg} in the \texttt{--prefix} option, and add
\texttt{--enable-debug} to the configure command:

\fbox{\begin{minipage}{\textwidth}\texttt{\\
\$ cd ..\\
\$ mkdir dbg\\
\$ cd dbg\\
\$ ../../code\_saturne-\verscs/configure \textbackslash \\
\textcolor{Violet}{--prefix}=/home/user/Code\_Saturne/3.0/arch/\textcolor{Magenta}{dbg}
\textbackslash \\
\textcolor{Violet}{--with-med}=/home/user/opt/med-3.0 \textbackslash \\
\textcolor{Magenta}{--enable-debug} \textbackslash \\
\textcolor{red}{CC}=/home/user/opt/mpich2-1.4/bin/mpicc \textcolor{red}{FC}=gfortran
}\end{minipage}}

\subsection{Shared or static builds\label{sec:config:shared}}

By default, on most architectures, both shared and static libraries
for \CS will be built, and the executables will be linked with shared
libraries. To disable either shared or static libraries,
add either {\tt --disable-shared} or {\tt --disable-static}
to the options passed to {\tt configure}. This will speed-up the build,
process as each file will only be built once, and not twice.

In some cases, a shared build may fail due to some dependencies
on static-only MPI libraries. In this case, {\tt --disable-shared}
will be necessary. Disabling shared libraries has also been seen
to avoid issues with linking on Mac OSX systems.

In any case, be careful if you switch from one option to the other: as
linking will be done with shared libraries by default, a build
with static libraries only will not completely overwrite a build using
shared libraries, so uninstalling the previous build first
is recommended.

\subsection{Relocatable builds\label{sec:config:relocatable}}

By default, a build of \CS is not movable, as not only
are library paths hard-coded using \emph{rpath} type info,
but the code's scripts also contain absolute paths.

To ensure a build is movable, pass the \texttt{--enable-relocatable} option
to {\tt configure}.

Movable builds assume a standard directory hierarchy, so when running
{\tt configure}, the \texttt{--prefix} option may be used, but fine tuning
of installation directories using options such as \texttt{--bindir},
\texttt{--libdir}, or \texttt{--docdir} must not be used
(these options are useful to install to strict directory hierarchies,
such as when packaging the code for a Linux distribution,
in which case making the build relocatable would be nonsense anyways,
so this is not an issue.
\footnote{In the special case of packaging the code, which
may require both fine-grained control of the installation directories
and the possibility to support options such as \texttt{dpgg}'s
\texttt{--instdir}, it is assumed the packager has sufficient knowledge to
update both \emph{rpath} information and paths in scripts in the executables
and python package directories of a non-relocatable build, and that the
packaging mechanism includes the necessary tools and scripts to enable this.}

\subsection{Compiler flags and environment variables\label{sec:config:flags}}

As usual when using an Autoconf-based \texttt{configure} script,
some environment variables may be used. \texttt{configure --help}
will provide the list of recognized variables.
\texttt{CC} and \texttt{FC} allow selecting the C and Fortran compiler
respectively (possibly using an MPI compiler wrapper for the C parts
of FVM and the Kernel).

Compiler options are usually defined automatically, based on
detection of the compiler (and depending on whether \texttt{--enable-debug}
was used). This is handled in a \texttt{config/cs\_auto\_flags.sh}
and \texttt{libple/config/ple\_auto\_flags.sh} scripts.
These files are sourced when running \texttt{configure}, so
any modification to it will be effective as soon as \texttt{configure} is run.
When installing on an exotic machine, or with a new compiler, adapting this
file is useful (and providing feedback to the \CS development team
will enable support of a broader range of compilers and systems in the
future.

The usual \texttt{CPPFLAGS}, \texttt{CFLAGS},
\texttt{FCCFLAGS}, \texttt{LDFLAGS}, and \texttt{LIBS} environment variables
may also be used, an flags provided by the user are appended to the automatic
flags. To completely disable automatic setting of flags,
the \texttt{--disable-auto-flags} option may be used.

\subsection{MPI compiler wrappers\label{sec:config:mpicc}}

MPI environments generally provide compiler wrappers, usually
with names similar to \texttt{mpicc} for C, \texttt{mpicxx} for C++,
and \texttt{mpif90} for Fortran 90. Wrappers conforming to the
MPI standard recommendations should provide a \texttt{-show}
option, to show which flags are added to the compiler so as to
enable MPI. Using wrappers is fine as long as several third-party tools
do not provide their own wrappers, in which case either
a priority must be established. For example, using HDF5's
\texttt{h5pcc} compiler wrapper includes the options used by
\texttt{mpicc} when building HDF5 with parallel IO, in addition to
HDF5's own flags, so it could be used instead of \texttt{mpicc}.
On the contrary, when using a serial build of HDF5 for a parallel
build of \CS, the \texttt{h5cc} and \texttt{mpicc} wrappers
contain different flags, so they are in conflict.

Also, some MPI compiler wrappers may include optimization options
used to build MPI, which may be different from those we wish to use
that were passed.

To avoid issues with MPI wrappers, it is possible to select an
MPI library using the \texttt{--with-mpi} option to \texttt{configure}.
For finer control, \texttt{--with-mpi-include} and \texttt{--with-mpi-lib}
may be defined separately.

Still, this may not work in all cases, as a fixed list of libraries
is tested for, so using MPI compiler wrappers is the simplest and safest
solution. Simply use a \texttt{CC=mpicc} or similar option instead
of \texttt{--with-mpi}.

\emph{Never} use an \texttt{FC=mpif90} or equivalent option:
in \CS, MPI is never called directly from Fortran code,
so Fortran MPI bindings are not necessary, but they can lead to
build failures, especially in cross-compilation
configurations.\footnote{\texttt{configure} determines which libraries are
necessary to link the Fortran runtime using a C or C++ compiler as a linker.
This avoids conflicts between linking with a C++ compiler and linking with a
Fortran compiler when both runtimes are necessary,
for example when using the MED library.
When using an MPI Fortran wrapper, extra libraries that are not normally
necessary will be added to those we link with, and the Libtool script
that is part of the build system will often try to add further dependencies,
mixing-up front-end and compute node compiler options and
libraries (Libtool may be very practical when it works, but in complex
situations where is guesses incorrectly at the commands it should run, it always
acts as if it knows best, and is very difficult to work around).}

\subsection{Environment Modules\label{sec:config:envmode}}

As noted in \S\ref{sec:obtain_ext_lib}, on systems providing
Environment Modules with the {\tt module} command, \CS's {\tt configure}
script detects which modules are loaded and saves
this list so that future runs of the code use that same environment,
rather than the user's environment, so as to allows using versions of
\CS built with different modules safely and easily.

Given this, it is recommended that when configuring and installing
\CS, only the modules necessary for that build of for
profiling or debugging be loaded. Note that as \CS uses the module
environment detected and runtime instead of the user's current
module settings, debuggers requiring a specific module may
not work under a standard run script if they were not loaded when
installing the code.

The detection of environement modules may be disabled using the
\texttt{--without-modules} option,
or the use of a specified (colon-separated) list of modules
may be forced using the \texttt{--with-modules=} option.

\subsection{Remarks for very large meshes\label{sec:config:largemesh}}

If \CS is to be run on large meshes, several precautions regarding
its configuration and that of third-party software must be taken.

in addition to local connectivity arrays, \CS uses global element ids
for some operations, such as reading and writing meshes and restart files,
parallel interface element matching, and post-processing output.
For a hexahedral mesh with $N$ cells,
the number of faces is about $3N$ (6 faces per cell, shared by 2 cells each).
With 4 cells per face, the $face \rightarrow vertices$ array is of size
of the order of $4\times3N$, so global ids used in that array's index
will reach $2^{31}$ for a mesh in the range of $2^{31} / 12 \approxeq 178.10^6$.
In practice, we have encountered a limit with slightly smaller meshes,
around 150 million cells.

Above 150 million hexahedral cells or so, it is thus imperative to configure
the build to use 64-bit global element ids, with the
{\tt --enable-long-gnum} option. Local indexes will still use
the default {int} size, so memory consumption will only be slightly
increased.

Recent versions of some third-party libraries may also optionally use 64-bit ids,
independently of each other or of \CS.
This is the case for the \scotch and \metis, MED and
CGNS libraries. In the case of graph-based partitioning, only
global cell ids are used, so 64-bit ids should not in theory be necessary
for meshes under 2 billion cells. In a similar vein, for post-processing output
using nodal connectivity, 64-bit global ids should only be an imperative
when the number of cells or vertices approaches 2 billion.
Practical limits may be lower, if some intermediate internal counts
reach these limits earlier.

Note also that \metis 4 is known to crash for meshes in the range of
35 million cells and above, so \metis 5 or \scotch are necessary.
Partitoning a 158 million hexahedral mesh using \metis 5
on a front-end node with 128 Gb memory is possible,
but partitioning the same mesh on cluster nodes with 24 Gb each
may not, so using parallel partitioning \ptscotch or \parmetis
should be preferred.

\subsection{Installation with the SALOME platform\label{sec:config:salome}}

To enable SALOME platform (\url{http://www.salome-platform.org}) integration,
the \texttt{--with-salome} configuration option should be used, so as to
specify the directory of the SALOME installation (note that this should be
the main installation directory, not the default application directory,
also generated by SALOME's installers).

Whith SALOME support enabled, both the CFDSTUDY salome module
(available by running \texttt{code\_saturne salome)} after install)
and the \textit{Code\_Aster} coupling adapter should be available.

Note that specifying a SALOME directory does not automatically
allow the \CS \texttt{configure} script to find some libraries
which may be available in the SALOME distribution, such as HDF5,
MED, or CGNS. It is possible to use those libraries by specifying
the appropriate paths in the matching options, but other versions and builds
may also be used (as those file formats are portable, MED or CGNS files produced
by either \CS or SALOME remain interoperable).

\subsection{Example configuration commands\label{sec:config:examples}}

Most available prerequisites are auto-detected, so to install the
code to the default \texttt{/usr/local} sub-directory,
a command such as:

\texttt{\$ ../../code\_saturne-\verscs/configure}

should be sufficient.

For the following examples, Let us define environment variables repectively
reflecting the \CS source path, installation path, and a path where optional
libraries are installed:

\fbox{\begin{minipage}{\textwidth}\texttt{\\
\$ \textcolor{OliveGreen}{SRC\_PATH}=/home/projects/Code\_Saturne/3.0 \\
\$ \textcolor{OliveGreen}{INSTALL\_PATH}=/home/projects/Code\_Saturne/3.0 \\
\$ \textcolor{OliveGreen}{CS\_OPT}=/home/projects/opt
}\end{minipage}}

For an install on which multiple
versions and architectures of the code should be available,
configure commands with all bells and whistles (except SALOME support) for a
build on a cluster named \texttt{ivanoe}, using the Intel compilers
(made available through environment modules) may look like this:

\fbox{\begin{minipage}{\textwidth}\texttt{\\
\$ \textcolor{Magenta}{module purge} \\
\$ \textcolor{Magenta}{module load} intel\_compilers/12.1.1.256 \\
\$ \textcolor{Magenta}{module load} open\_mpi/gcc/1.4.5 \\
\$ \textcolor{OliveGreen}{\$SRC\_PATH}/code\_saturne-\verscs/configure \textbackslash \\
\textcolor{Violet}{--prefix}=\textcolor{OliveGreen}{\$INSTALL\_PATH}/arch/ivanoe\_ompi
\textbackslash \\
\textcolor{Violet}{--with-blas}=/opt/intel/composerxe\_xe\_2011\_sp1.7.256/mkl \textbackslash \\
\textcolor{Violet}{--with-libxml2}=\textcolor{OliveGreen}{\$CS\_OPT}/libxml2-2.8/arch/ivanoe \textbackslash \\
\textcolor{Violet}{--with-hdf5}=\textcolor{OliveGreen}{\$CS\_OPT}/hdf5-1.8.9/arch/ivanoe
\textbackslash \\
\textcolor{Violet}{--with-med}=\textcolor{OliveGreen}{\$CS\_OPT}/med-3.0/arch/ivanoe
\textbackslash \\
\textcolor{Violet}{--with-cgns}=\textcolor{OliveGreen}{\$CS\_OPT}/cgns-3.1/arch/ivanoe \textbackslash \\
\textcolor{Violet}{--with-ccm}=\textcolor{OliveGreen}{\$CS\_OPT}/libccmio-2.06.23/arch/ivanoe \textbackslash \\
\textcolor{Violet}{--with-scotch}=\textcolor{OliveGreen}{\$CS\_OPT}/scotch-6.0/arch/ivanoe\_ompi \textbackslash \\
\textcolor{Violet}{--with-metis}=\textcolor{OliveGreen}{\$CS\_OPT}/parmetis-4.0/arch/ivanoe\_ompi \textbackslash \\
\textcolor{Violet}{--with-eos}/\textcolor{OliveGreen}{\$CS\_OPT}/eos-1.2.0/arch/ivanoe\_ompi \textbackslash \\
\textcolor{red}{CC}=mpicc \textcolor{red}{FC}=ifort \textcolor{red}{CXX}=icpc
}\end{minipage}}

In the example above, we have appended the \texttt{\_ompi} postfix
to the architecture name for libraries using MPI, in case we intend
to install 2 builds, with different MPI libraries (such as Open MPI and MPICH2).
Note that optional libraries using MPI must also use the same MPI
library. This is the case for \ptscotch or \parmetis, but also HDF5,
CGNS, and MED if they are built with MPI-IO support.
Similarly, C++ and Fortran libraries, and even C libraries built
with recent optimizing C compilers, may require runtime libraries
associated to that compiler, so if versions using different compilers
are to be installed, it is recommended to use a naming scheme
which reflects this.
In this example, HDF5, CGNS and MED were built without MPI-IO support,
as \CS does not yet exploit MPI-IO for these libraries.

\subsection{Cross-compiling}

On machines with different front-end and compute node architectures,
such as IBM Blue Gene/P, cross-compiling is necessary.
To install and run \CS, 2 builds are required:

\begin{itemize}
\item a ``front-end'' build, based on front-end node's architecture. This is
      the build whose \texttt{code\_saturne} command, GUI, and documentation
      will be used, and with which meshes may be imported (i.e. whose
      Preprocessor will be used). This build is not intended for calculations,
      though it could be used for mesh quality criteria checks.
      This build will thus usually not need  MPI.
\item a ``compute'' build, cross-compiled to run on the compute nodes.
      This build does not need to include the GUI, documentation, or
      the \pcs.
\end{itemize}

A debug variant of the compute build is also recommended, as always.
Providing a debug variant of the front-end build is not generally useful.

A post-install step (see \S\ref{sec:post_install}) will allow
the scripts of the front-end build to access the compute build in a transparent
manner, so it will appear to the users that they are simply working with that
build.

Depending on their role, optional third-party libraries should be installed
either for the front-end, for the compute nodes, or both:

\begin{itemize}
\item BLAS will be useful only for the compute nodes, and are generally
      always available on large compute facilities.
\item Python and PyQt4 will run on the front-end node only.
\item Libxml2 must be available for the compute nodes if the GUI is used.
\item HDF5, MED, CGNSlib, and libCCMIO may be used by the Preprocessor on
      the front-end node to import meshes, and by the main solver on the
      compute nodes to output visualization meshes and fields.
\item \scotch or \metis may be used by a front-end node build of the
      solver, as serial partitioning of large meshes requires a lot of memory.
\item \ptscotch or \parmetis may be used by the main solver on the
      compute nodes.
\end{itemize}

\subsubsection{Cross-compiling configuaration for Blue Gene/P}

For an example, let us start with the front-end build:

\fbox{\begin{minipage}{\textwidth}\texttt{\\
\$ \textcolor{OliveGreen}{\$SRC\_PATH}/code\_saturne-\verscs/configure \textbackslash \\
\textcolor{Violet}{--prefix}=\textcolor{OliveGreen}{\$INSTALL\_PATH}/arch/frontend
\textbackslash \\
\textcolor{Violet}{--with-hdf5}=\textcolor{OliveGreen}{\$CS\_OPT}/hdf5-1.8.6/arch/frontend
\textbackslash \\
\textcolor{Violet}{--with-med}=\textcolor{OliveGreen}{\$CS\_OPT}/med-3.0/arch/frontend
\textbackslash \\
\textcolor{Violet}{--with-cgns}=\textcolor{OliveGreen}{\$CS\_OPT}/cgns-3.1/arch/frontend \textbackslash \\
\textcolor{Violet}{--with-scotch}=\textcolor{OliveGreen}{\$CS\_OPT}/scotch-6.0/arch/frontend \textbackslash \\
\textcolor{red}{PYTHON}=\textcolor{OliveGreen}{\$CS\_OPT}/python/arch/frontend/bin/python \textbackslash \\
\textcolor{red}{CFLAGS}="-m64" \textcolor{red}{FCFLAGS}="-m64" \textcolor{red}{CXXFLAGS}="-m64"
}\end{minipage}}

In this example, the front-end node is based on an IBM Power architecture,
on which the GCC compiler is available, but produces 32-bit code by default.
Adding the \texttt{"-m64"} flags force the compiler into 64-bit mode, allowing
the Preprocessor to import meshes up into the 100-million cell range.

For the compute node, we use the same version of Python (which
is used only for the GUI and scripts, which only run on the front-end
or service nodes), but the compilers are cross-compilers for the
compute nodes:

\fbox{\begin{minipage}{\textwidth}\texttt{\\
\$ \textcolor{OliveGreen}{\$SRC\_PATH}/code\_saturne-\verscs/configure \textbackslash \\
\textcolor{Violet}{--prefix}=\textcolor{OliveGreen}{\$INSTALL\_PATH}/arch/bgp
\textbackslash \\
\textcolor{Violet}{--with-blas}=/opt/ibmmath/essl/4.4 \textbackslash \\
\textcolor{Violet}{--with-libxml2}=\textcolor{OliveGreen}{\$CS\_OPT}/libxml2-2.3.32/arch/bgp \textbackslash \\
\textcolor{Violet}{--with-hdf5}=\textcolor{OliveGreen}{\$CS\_OPT}/hdf5-1.8.6/arch/bgp
\textbackslash \\
\textcolor{Violet}{--with-med}=\textcolor{OliveGreen}{\$CS\_OPT}/med-3.0/arch/bgp
\textbackslash \\
\textcolor{Violet}{--with-cgns}=\textcolor{OliveGreen}{\$CS\_OPT}/cgns-3.1/arch/bgp \textbackslash \\
\textcolor{Violet}{--with-scotch}=\textcolor{OliveGreen}{\$CS\_OPT}/scotch-6.0/arch/bgp \textbackslash \\
\textcolor{Violet}{
--disable-sockets --disable-dlloader -disable-nls \textbackslash \\
--disable-frontend --enable-long-gnum \textbackslash
} \\
\textcolor{Magenta}{--build}=ppc64
\textcolor{Magenta}{--host}=bluegenep \textbackslash \\
\textcolor{red}{CC}=mpixlc\_r \textcolor{red}{FC}=bgxlf90\_r
\textcolor{red}{CXX}=mpixlcxx\_r \textbackslash \\
\textcolor{red}{PYTHON}=\textcolor{OliveGreen}{\$CS\_OPT}/python/arch/bgp/bin/python
}\end{minipage}}

Here, the \texttt{--build=ppc64 --host=bluegenep} options ensure the
\texttt{configure} script into cross-compilation mode.
With a front-end base on an Intel or AMD, architecture,
\texttt{--build=x86\_64} or \texttt{--build=amd64} should be used
instead of \texttt{--build=ppc64}. For the host (target) architecture,
\texttt{--host=bluegenep} is recognized by current GNU Autoconf versions,
so it is preferred, but \texttt{--host=ppc} also works well. Actually,
any choice of build and host architectures recognized by Autoconf would
probably work, as long as build and host are different.

The C++ compiler is also specified, as it will be needed for
the link stage due to C++ dependencies in the MED library,
which is a static library in this example (see \S\ref{sec:ext:med}).

The thread-safe compiler wrappers used here should not be necessary for \CS, but in our
experience, the ESSL BLAS are correctly detected only with those wrappers,
not with the single-threaded versions.\footnote{This might be due to a bug in the ESSL
BLAS detection of \CS, although the code has been checked.}

Note that in the above examples, we specified an install of the \scotch
partitioning library both for the front-end and for the compute nodes.
The implies a serial build of \scotch on the front-end node, and a parallel
build (\ptscotch) on the compute nodes. Both are optional.
Similarly, \metis could be used on the front-end node, and \parmetis
on the compute nodes.

\subsubsection{Cross-compiling configuration for Blue Gene/Q}

In our example, the front-end node is based on an IBM Power architecture,
runnning under Red Hat Enterprise Linux 6, on which the Python/Qt4
environment should be available as an RPM package, and installed by the
administrators. If this is not possible, the Python/Qt4 aspects of the
Blue Gene/P example may be adapted here.

On the compute nodes, the IBM XL compilers produce static object files
by default, so the \texttt{--disable-shared} option is not necessary
for libraries using Autotools-based installs when using those compilers,
though using \texttt{--build=ppc64 --host=bluegeneq} in this case ensures
the cross-compiling environment is detected. This environment
is the suggested default, and prevents shared library builds.
To allow building with shared libraries while still ensuring the
cross-compiling environment is detected,
use \texttt{--host=powerpc64-bgq-linux} instead.

As the front-end nodes of Blue Gene/Q machines may be expected to run
Red Hat EL 6.x linux variants, instead of 5.x for blue Gene/P, more
up-to date compilers and libraries (such as Python/Qt4) should be available
as packages, easily installable by the system administrators.

For the compute nodes, the following remarks may be mode for prerequisites:

\begin{itemize}
\item LibXml: to reduce the size and simmplify the installation of this
library, the \texttt{--with-ftp=no}, \texttt{--with-http=no},
and \texttt{--without-modules} options may be used with \texttt{configure}.
\item HDF5: building this library with its \texttt{configure} script
is a pain\footnote{It requires running a \texttt{yodconfigure}
script and adapting other scripts (see documentation), then running
this as a submitted job (or under a SLURM allocation if you are lucky
enough to use this resource manager).}, but installing HDF5 1.8.9
using CMake is as simple as on a workstation, and simply requires
choosing the correct compilers and possibly a few other options (in
the EDF \CS build, the GCC compilers were chosen to reduce risks, and
the Fortran wrappers were not needed, so not built).
\item CGNS: building CGNS 3.1 is based on CMake, and no specific
problems have been observed.
\item MED: building MED 3.0.5 for \CS is easier than previous versions,
as a new \\ \texttt{--disable-fortan} option is available for the
\texttt{configure} script. Both the C and C++ compiler wrappers
must be specified, and the link may fail with the GNU compilers, due
to some shared library issue (trying to force \texttt{--disable-shared}).
With the IBM XL compilers, the same build works fine, as long as the
\texttt{CXXFLAGS=-qlanglvl=redefmac}) option is passed. Adding
the HDF5 tools path to the \texttt{\$PATH} environment variable for
the  configuration stage may also be required.
\end{itemize}

For an example, let us start with the front-end build:

\fbox{\begin{minipage}{\textwidth}\texttt{\\
\$ \textcolor{OliveGreen}{\$SRC\_PATH}/code\_saturne-\verscs/configure \textbackslash \\
\textcolor{Violet}{--prefix}=\textcolor{OliveGreen}{\$INSTALL\_PATH}/arch/frontend
\textbackslash \\
\textcolor{Violet}{--with-hdf5}=\textcolor{OliveGreen}{\$CS\_OPT}/hdf5-1.8.9/arch/frontend
\textbackslash \\
\textcolor{Violet}{--with-med}=\textcolor{OliveGreen}{\$CS\_OPT}/med-3.0/arch/frontend
\textbackslash \\
\textcolor{Violet}{--with-cgns}=\textcolor{OliveGreen}{\$CS\_OPT}/cgns-3.1/arch/frontend \textbackslash \\
\textcolor{Violet}{--with-scotch}=\textcolor{OliveGreen}{\$CS\_OPT}/scotch-6.0/arch/frontend \\
}\end{minipage}}

For the compute node, we use the same version of Python (which
is used only for the GUI and scripts, which only run on the front-end
or service nodes), but the compilers are cross-compilers for the
compute nodes:

\fbox{\begin{minipage}{\textwidth}\texttt{\\
\$ \textcolor{OliveGreen}{\$SRC\_PATH}/code\_saturne-\verscs/configure \textbackslash \\
\textcolor{Violet}{--prefix}=\textcolor{OliveGreen}{\$INSTALL\_PATH}/arch/bgq
\textbackslash \\
\textcolor{Violet}{--with-blas}=/opt/ibmmath/essl/5.1 \textbackslash \\
\textcolor{Violet}{--with-blas-type}=ESSL \textbackslash \\
\textcolor{Violet}{--with-libxml2}=\textcolor{OliveGreen}{\$CS\_OPT}/libxml2-2.8/arch/bgq \textbackslash \\
\textcolor{Violet}{--with-hdf5}=\textcolor{OliveGreen}{\$CS\_OPT}/hdf5-1.8.9/arch/bgq \textbackslash \\
\textcolor{Violet}{--with-med}=\textcolor{OliveGreen}{\$CS\_OPT}/med-3.0/arch/bgq \textbackslash \\
\textcolor{Violet}{--with-cgns}=\textcolor{OliveGreen}{\$CS\_OPT}/cgns-3.1/arch/bgq \textbackslash \\
\textcolor{Violet}{--with-scotch}=\textcolor{OliveGreen}{\$CS\_OPT}/scotch-6.0/arch/bgq \textbackslash \\
\textcolor{Violet}{
--disable-sockets --disable-dlloader -disable-nls \textbackslash \\
--disable-frontend --enable-long-gnum \textbackslash
} \\
\textcolor{Magenta}{--build}=ppc64
\textcolor{Magenta}{--host}=bluegeneq \textbackslash \\
\textcolor{red}{CC}=/bgsys/drivers/ppcfloor/comm/xl/bin/mpixlc\_r \textbackslash \\
\textcolor{red}{CXX}=/bgsys/drivers/ppcfloor/comm/xl/bin/mpixlcxx\_r \textbackslash \\
\textcolor{red}{FC}=bgxlf95\_r \\
}\end{minipage}}

The C++ compiler is specified, as it will be needed for
the link stage due to C++ dependencies in the MED library,
which is a static library in this example (see \S\ref{sec:ext:med}).

Note that in the above examples, we specified an install of the \scotch
partitioning library both for the front-end and for the compute nodes.
The implies a serial build of \scotch on the front-end node, and a parallel
build (\ptscotch) on the compute nodes. Both are optional, and the
serial partitioning on the front-end nodes should only be used as a
backup or as a reference for parallel partitioning. Unless robustness
or quality issues are encountered with parallel partitioning, it
should supercede serial partitioning, as it allows for a simpler
toolchain even for large meshes.
Similarly, \metis could be used on the front-end node, and \parmetis
on the compute nodes.

\subsection{Troubleshooting\label{sec:config:troubleshoot}}

If \texttt{configure} fails and reports an error, the message should
be sufficiently clear in most case to understand the cause of the
error and fix it. Do not forget that for libraries installed using
packages, the development versions of those packages are also
necessary, so if configure fails to detect a package which you
believe is installed, check the matching development package.

Also, whether it succeeds or fails, \texttt{configure} generates
a file named \texttt{config.log}, which contains details on tests
run by the script, and is very useful to troubleshoot
configuration problems. When \texttt{configure} fails due to a given
third-party library, details on tests relative to that library
are found in the \texttt{config.log} file. The interesting information
is usually in the middle of the file, so you will need to search
for strings related to the library to find the test that failed
and detailed reasons for its failure.

\section{Compile and install\label{sec:compile}}

Once the code is configured, it may be compiled and installed;
for example, to compile the code (using 4 parallel threads),
then install it:

\texttt{\$ make -j 4 \&\& make install}

To compile the documentation, add:

\texttt{\$ make pdf \&\& make install-pdf}

To clean the build directory, keeping the configuration,
use \texttt{make clean};
To uninstall an installed build, use \texttt{make uninstall}.
To clear all configuration info, use \texttt{make distclean}
(\texttt{make uninstall} will not work after this).

\subsection{Installing to a system directory\label{sec:sys_install}}

When installing to a system directory, such as \texttt{/usr}
or \texttt{/usr/local}, some Linux systems may require running
\texttt{ldconfig} as root or sudoer for the cdoe to work correctly.

\section{Post-install\label{sec:post_install}}

Once the code is installed, a post-install step may
be necessary for computing environments using a batch system,
for separate front-end and compute systems (such as Blue Gene
systems), or for coupling with \syrthes 4 or Code\_Aster.

Copy or rename the \texttt{<install-prefix>/etc/code\_saturne.cfg.template} to \\
\texttt{<install-prefix>/etc/code\_saturne.cfg},
and uncomment and define the applicable sections.

If used, the name of the batch system should match one of the templates \\
in \texttt{<install-prefix>/share/code\_saturne/batch},
and those may also be edited if necessary to match the local
batch configuration{\footnote Some batch systems allow a wide
range of alternate and sometimes incompatible options or keywords,
and it is for all practical purposes impossible to determine
which options are allowed for a given setup, so editing the
batch template to match the local setup may be necessary.}

Also, the \texttt{compute\_versions} section allows the administrator
to define one or several alternate builds which will be used for
compute stages. This is especially useful for installation
on BlueGene type machines, where 2 separate builds are required
(one for the front-end nodes and one for the compute nodes).
The compute-node build may be configured using the
\texttt{--disable-frontend} option so as only to build and install
the components required to run on compute-nodes,
while the front-end build may be configured without MPI support.
The front-end build's post-install step allows definition of
the associated compute build.

\section{Installing for \syrthes coupling\label{sec:syrthes}}

Coupling with \syrthes 4 requires defining the path to \syrthes 4
at the post-install stage.

When coupling with \syrthes 4, both \CS and \syrthes must
use the same MPI library, and must use the same version of the
PLE (Parallel Location and Exchange) library from \CS. By default, PLE
is built as a sub-library of \CS, but a standalone version may be
configured and built, using the \texttt{libple/configure} script
from the \CS source tree, instead of the top-level \texttt{configure}
script. \CS may then be configured to use the existing install of PLE
using the \texttt{--with-ple} option. Similarly, \syrthes must also
be configured to use PLE.

Alternatively, \syrthes 4 may simply be configured to use the PLE
library from an existing \CS install.

\section{Shell configuration}

If \CS is installed in a non-default system directory (i.e. outside
\texttt{/usr} or \texttt{/usr/local}, it is recommended to define
an alias (in the user's \texttt{.alias} or \texttt{.profile} file, so as to
avoid needing to type the full path when using the code:

\texttt{alias code\_saturne="\$prefix/code\_saturne-\$version/bin/code\_saturne"}

Note that when multiple versions of the code are installed side by side, using
a different alias for each will allow using them simultaneously, with no risk
of confusion.

If using the bash shell, you may also source a bash completion file,
so as to benefit from shell completion for \CS commands
and options, either using

\texttt{. <install-prefix>/etc/bash\_completion.d/code\_saturne}

or

\texttt{source <install-prefix>/etc/bash\_completion.d/code\_saturne}

On some systems, only the latter syntax is effective. For greater
comfort, you should save this setting in your \texttt{.bashrc}
or \texttt{.bash\_profile} file.

\section{Caveats}

\subsubsection{Moving an existing installation}

\textcolor{Red}{\emph{Never move an non-relocatable installation}} of \CS.
Using \texttt{LD\_LIBRARY\_PATH} or \texttt{LD\_PRELOAD}
may allow the executable to run despite \emph{rpath} info
not being up-to-date, but in environments where different library,
versions are available, there is a strong risk of not using
the correct library. In addition, the scripts will not work
unless paths in the installed scripts are updated.

To build a relocatable installation, see sectioon
\ref{sec:config:relocatable}.

If you are packaging the code and need both fine-grained control of
the installation directories, and the possibility to support
options such as \texttt{dpgg}'s \texttt{--instdir}, it is assumed
you have sufficient knowledge to update both \emph{rpath} information
and paths in scripts in the executables and python package directories,
and that the packaging mechanism includes the necessary tools and
scripts to enable this.

In any other case, you should not even think about moving a
non-relocatable build.

If you need to test an installation in a test directory before
installing it in a production directory, use the
\texttt{make install DESTDIR=<test\_prefix>} provided
by the Autotools mechanism rather than configuring an install for a
test directory and then moving it to a production directory.
Another less elegant but safe solution is to configure the build for
installation to a test directory, and once it is tested,
re-configure the build for installation to the final production
directory, and rebuild and install.

\subsubsection{Known issues with some packages}

On quite a few clusters, some issues have been encountered
when using versions of Open MPI built with the Intel compiler
suite. Typically, crashes in the MPI-IO layers are almost
guaranteed, but issues may also arise later, apparently  with some
collectives, so disabling MPI-IO is not enough.

Using Intel compilers for \CS itself and a build of Open MPI
using the GNU compilers usually works fine, and the performance
difference should be minimal (it can be higher using
the GNU compilers also for \CS itself), so the issue is not
in \CS itself, but it requires further investigation.
In any case, avoiding this buggy combination may avoid you
many wasted hours.

\end{document}

