The simplest install procedure is as the `root` user:

    ./configure
    make
    sudo make install

The `configure` program is a script that runs tests of your system
and the availability of some required and optional libraries for Rheolef.
Upon termination, it prints a summary and generates two files:
`config/config.mk` and `config/config.h`.
The `make` program then runs the conpilation and
the `make install` stage copies the produced files.
By default, the main destination directory is `/usr/local`.
Commands are installed in `/usr/local/bin`, libraries in `/usr/local/lib`,
headers in `/usr/local/include` and the documentation in `/usr/local/share`.

Alternative install directory
=============================

Since the default install prefix is `/usr/local`, it requires to
be logged as `root` in order to install.
If you are not the `root` user, or prefer
an alternative install directory, e.g. `$HOME/sys`, enter:

    ./configure --prefix="$HOME/sys"

In that case, you have to add the following lines at the end
of your `.profile` or `.bash_profile` file:

    export PATH="$HOME/sys/bin:$PATH"
    export LD_LIBRARY_PATH="$HOME/sys/lib:$LD_LIBRARY_PATH"
    export MANPATH="$HOME/sys/man:$MANPATH"

Assuming you are using the `sh` or the `bash` unix interpreter.
Conversely, if you are using `csh` or `tcsh`, add
at the bottom of your `.cshrc` file:

    set path = ("$HOME/sys/bin" $path)
    setenv LD_LIBRARY_PATH "$HOME/sys/lib:$LD_LIBRARY_PATH"
    setenv MANPATH "$HOME/sys/man:$MANPATH"

If you are unsure about unix interpreter, get the SHELL value:

    echo $SHELL

Then, you have to `source` the modified file, e.g.:

    source ~/.bashrc

HPUX users should replace `LD_LIBRARY_PATH` by `SHLIB_PATH`.
If you are unsure, get the shared library path variable:

    rheolef-config --shlibpath-var

Check also your installation by compiling a sample
program with the installed library:

    make installcheck

Since it is a common mistake, you can later, at each time, test
your run-time environment sanity with:

    rheolef-config --check

Required libraries
==================

The following required libraries are available as precompiled packages under
Debian GNU/Linux and Ubuntu systems.

The `boost` library.
  It provides useful extensions of the c++ standard template library.
  See http://www.boost.org .

The `eigen` library.
  It provides efficient c++ linear algebra subroutines.
  See http://eigen.tuxfamily.org .

Recommended libraries
=====================
The following libraries are optional but highly recommended.

The `umfpack` library.
  It provides a multifrontal sparse direct solver.
  Rheolef solvers run faster when using this library.
  See http://faculty.cse.tamu.edu/davis/suitesparse.html .

The `cgal` library.
  It provide an easy access to efficient and reliable geometric algorithms.
  With it, Rheolef implements the characteristic method and interpolation from one mesh to another.
  This library is optional, but allows, when available, extended Rheolef features.
  See http://www.cgal.org .

Parallel computations
=====================

With the optional following libraries, Rheolef is able to run in parallel and
and with distributed memory.
By default, the Rheolef `configure` script tries to autodetect these
libraries and be able to run in parallel.
When these libraries are not found, the distributed features are turned off.
If your libraries are installed in a non-standard location, you should
indicate it by a suitable `configure` option. See below for these options.

A `mpi` library.
  Rheolef bases on `mpi`, the message passing interface standard.
  A popular implementation is the `openmpi` library.
  When no `mpi` library is found, the distributed feature is turned off.

The `mumps` library.
  It is a massively distributed sparse direct solver.
  The use of implicit numerical schemes leads to the
  resolution of large sparse linear systems.
  See http://graal.ens-lyon.fr/MUMPS .
  When `mumps` is not found, the distributed feature is turned off.

Either the `scotch` or the `metis` library.
  It provides the distributed mesh partitioning.
  For `scotch` see http://www.labri.fr/perso/pelegrin/scotch 
  and for `metis` see http://www.cs.umn.edu/~metis .
  When neither `scotch` nor `metis` are founded, the distributed feature is turned off.

The `trilinos/ifpack` library.
  It provides a distributed preconditioner used for iterative solvers.
  See http://trilinos.sandia.gov .
  When `trilinos` is not available, a less efficient builtin IC0 preconditioner is used.
  The `trilinos` support is actually broken, it will be available in a forthcoming version.

Run-time tools
==============

Using Rheolef suggests the use of the following optional tools
for pre- and post-processing purpose:

    gmsh
    gnuplot
    paraview

None of these tools are required when building and installing Rheolef.

Tools for developpers
=====================

These tools are required if you build from the development version,
from the `git` repository:

- Re-generating some source files, as initiated with the `bootstrap` command,
  requires the `autotools` suite: `autoconf`, `automake` and `libtool`.
- It requires also `flex` and `bison` for building file format parsers.

Portability issues
==================

Rheolef is based on standard C++ and the `boost` library.
Therefore you need a compiler that supports at least the 2011 C++ standards.

Current distributed version of Rheolef has been heavily tested with GNU C++, CLANG C++
and INTEL C++ on debian, ubuntu, mint, suse and redhat GNU/Linux systems for various
32 and 64 bits architectures, with massively distributed memories and processes.
Successful installation from sources on MAC-OS-X systems has been also repported 
recently.

- The GNU C++ compiler `g++` is a free software
  available at http://www.gnu.org .
- The CLANG C++ compiler `clang++` is also a free software
  available at http://clang.llvm.org .
- The Intel C++ compiler is a privative software.

So, the Rheolef library is expected to compile without problems
with one of these compilers.
If you are running a another compiler and operating system combination,
please run the non-regression test suite:

    make check

Please, send mails and bug reports to the mailing list mailto:rheolef@grenet.fr .


Older Rheolef 5.x versions was tested also on the
KAI  C++ compiler (KCC-3.2b) and the
CRAY C++ compiler (CC-3.0.2.0)
on the following operating systems:

- mac os x (i386-apple-darwin9.8.0), using GNU C++
- sun solaris 2.8, ultrasparc, using GNU C++
- compacq OSF1 alpha (V5.1, V4.0), using Compacq C++
- aix 4.1 ibm sp2, multiprocessor based on rs6000
- cray unicos t3e, multiprocessor based on 64 bits dec alpha
- cray unicos c94
- hpux 9.05 and 10.20, hppa
- sgi irix 6.3, mips
- sun solaris 2.5.1, sparc

where

- The KAI C++ is available at http://www.kai.com .
- The CRAY C++ is available on CRAY platforms.

Nevertheless, the current version has no more been tested
on these old compilers and systems.

Configure options
=================

If the required libraries are located in a non-standard directory, please use
the configure options:

    ./configure --help

and also consider the CXX, CXXFLAGS and LIBS variables, as in the following more complex
configure command:

    CXX=clang++ CXXFLAGS=-I/misc/include LIBS="-L/misc/lib" ./configure

Finaly, if troubles still persist after the configure step, you can also edit
directly the config/config.mk and config/config.h files. In these cases please also post
to the mailling list mailto:rheolef@grenet.fr for any portability problem.

Here are all the supported configure command line options.

`-h`, `--help`
>       Display a summary of command line options and exit
`--help=short`
>       Display only options specific to Rheolef and exit
`--with-float`=option
>       Turns on/off the extended arithmetic feature.
>       The *option* could be either
>       `float128` (quadruple precision, 32 digits),
>       or the default `double` (double precision, 16 digits).
`--enable-permissive`
>       The compiler do not turns all warnings into errors and becomes permissive.
>       This feature is for code developers and is off by default.
`--enable-debian-packaging`
>       Install files in the debian way 
>       by respecting the `Debian Policy Manual`.
>       This is not the default behavior.
`--enable-documentation`
>       By default, both the reference manual and the users guide
>       documentations are generated when required tools are available.
>       The required tool for the reference manual is `doxygen`.
>       The required tools for the users guide are
>       `pdflatex`, `bibtex`, `makeindex`, `gs`, `pdffonts`, `fig2dev`, `gnuplot`, `cairosvg`. `pdfcrop`
>       This option allows one to turn off the generation of these
>       documentation.
`--with-bigfloat`=digits10
>       Turn on Bruno Haible's `cln` arbitrary
>       precision float library with *digits10* precision,
>       See http://clisp.cons.org/~haible/packages-cln.html .
>       Default is off.
>       The *digits10* argument value is optional and
>       default value is *digits10*=60.
>       This feature is still under development.
`--with-cln`=clndir
>       Set the home directory for the `cln` library
>       used by the `--with-bigfloat` previous option.
>       Default *clndir* is `/usr/local/math`.
`--enable-maintainer-mode`
>       This option is off by default.
>       When false, it turns off by default the `ginac` feature (see below).
>       If you are not a Rheolef library code developper,
>       you could safely turn it off.
>       This option is provided for compatibility with the Debian packaging
>       system `debhelper`.
`--enable-ginac`
>       This option is off by default.
>       Ginac is computer algebra system in C++
>       that is used to automatically generate the C++ code
>       for some low-order FEM basis (P1, bubble, etc).
>       If you are not a Rheolef library code developper,
>       you could safely turn it off.
`--with-boost-incdir`=incdir_boost
>       Specifies the include directory
>       for the `boost` library.
>       This library is required by rheolef.
`--with-boost-libdir`=libdir_boost
>       Specifies the corresponding library directory.
`--with-eigen-incdir`=incdir_eigen
>       Specifies the include directory
>       for the `eigen` library.
>       This library is required by rheolef.
`--with-eigen-libdir`=libdir_eigen
>       Specifies the corresponding library directory.
`--enable-debug`
>       Produce a `c++ -g` like code and turn on some runtime checks.
`--enable-dmalloc`
>       With debugging, also uses dynamic allocation runtime checking
>	     with `dmalloc` when available.
`--enable-mpi`
>       Turns on/off the distributed computation features.
>       Default is on when distributed is on. This feature is currently in development.
>       When on, configure try to detect either the scotch or the parmetis libraries.
`--with-scotch-incdir`=incdir_scotch
>       Specifies the include directory
>       for the `scocth` distributed mesh partitioner.
>       Default is to auto-detect when mpi is available.
`--with-scotch-libdir`=libdir_scotch
>       Specifies the corresponding library directory.
>       Check in *libdir_scotch* for `libptscotchparmetis.so`, 
>       `libptscotch.so` and `libptscotcherrexit.so` or
>       corresponding `.a` libraries.
`--with-scotch-libs`=libs_scotch
>       Specifies some alternating library compile flag e.g.
>       `-lscotch`. 
`--with-parmetis-incdir`=incdir_parmetis
>       Specifies the include directory
>       for the `parmetis` distributed mesh partitioner.
>       Default is to autodetect when mpi is available and scotch is unavailable.
`--with-parmetis-libdir`=libdir_parmetis
>       Specifies the corresponding library directory.
>       Check in *libdir_parmetis* for `libparmetis.so`,
>       `libparmetis.a` and also `libmetis.a`
>       `libmetis.so`.
`--with-blas-libdidr`=rheo_libdir_blas
>       Specifies the include directory
>       for the `blas` linear algebra library.
>       Default is to auto-detect.
`--with-blas-libs`=rheo_libs_blas
>       Specifies the corresponding library directory.
`--with-scalapack-libdir`=rheo_libdir_scalapack
>       Specifies the library directory
>       for the `scalapack` library.
>       Default is to auto-detect when `mpi` is available.
`--with-scalapack-libs`=rheo_libs_scalapack
>       Specifies some alternating library compile flag e.g.
>       `-lscalapack`. 
`--with-mumps-incdir`=incdir_mumps
>       Specifies the include directory
>       for the `mumps` linear algebra library.
>       Default is to auto-detect.
`--with-mumps-libdir`=libdir_mumps
>       Specifies the corresponding library directory.
`--with-mumps-libs`=libs_mumps
>       Specifies some alternating library compile flag e.g.
>       `-lmumps`. 
`--with-trilinos`=libdir_trilinos
>       Specifies the library directory
>       for the `trilinos/ifpack` preconditioner library.
>       Check in *libdir_trilinos* for `libtrilinos_ifpack.so`, 
>       or the corresponding `.a` libraries.
>       The `trilinos` support is actually broken.
`--with-cholmod-incdir`=incdir_cholmod
>       Specifies the include directory
>       for the `cholmod` direct solver library
>       for sparse symmetric definite positive matrix.
>       Default is to auto-detect.
`--with-cholmod-libdir`=libdir_cholmod
>       Specifies the corresponding library directory.
>       Default *incdir_cholmod* is *libdir_cholmod*\ .
>       Check in *libdir_cholmod* for `libcholmod.so` or
>       `libcholmod.a` and for header
>       *incdir_cholmod*\ `/cholmod.h` or *incdir_cholmod*\ `/cholmod/cholmod.h`.
`--with-cholmod-libs`=libs_cholmod
>       Specifies some alternating library compile flag e.g.
>       `-lcholmod`. 
`--with-umfpack-incdir`=incdir_umfpack
>       Specifies the include directory
>       for the `umfpack` direct solver library
>       for sparse unsymmetric matrix.
>       Default is to auto-detect.
`--with-umfpack-libdir`=libdir_umfpack
>       Specifies the corresponding library directory.
>       Default *incdir_umfpack* is *libdir_umfpack*\ .
>       Check in *libdir_umfpack* for `libumfpack.so` or
>       `libumfpack.a` and for header
>       *incdir_umfpack*\ `/umfpack.h`
>       or *incdir_umfpack*\ `/umfpack/umfpack.h`.
`--with-umfpack-libs`=libs_umfpack
>       Specifies some alternating library compile flag e.g.
>       `-lumfpack`. 
`--with-cgal-incdir`=incdir_cgal
>       Specifies the include directory
>       for the `cgal` discrete geometry library.
>       Default is to auto-detect.
`--with-cgal-libdir`=libdir_cgal
>       Check in *libdir_cgal* for `libcgal.so`, 
>       or the corresponding `.a` libraries.
`--with-cgal-libs`=libs_cgal
>       Specifies some alternating library compile flag e.g.
        `-lCGAL`. 
`--enable-optim`
>       Turns compile-time optimization to maximum available.
>       Include architecture-dependent compilation (e.g. on intel, executable
>       are less portable across intel variants).
>       Default is on.