diff --git a/CMakeLists.txt b/CMakeLists.txt
index c490e2259a30b3c82da656886a665b39365bea60..c95457bc6c19b6467eedabcb97f9d332d5442d1d 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -638,7 +638,9 @@ message(" kokkos devices: ${PUGS_BUILD_KOKKOS_DEVICES}")
if (MPI_FOUND)
message(" MPI: ${MPI_CXX_LIBRARY_VERSION_STRING}")
else()
- if(NOT PARMETIS_LIBRARIES)
+ if (PUGS_ENABLE_MPI MATCHES "^OFF$")
+ message(" MPI: deactivated!")
+ elseif(NOT PARMETIS_LIBRARIES)
message(" MPI: deactivated: ParMETIS cannot be found!")
else()
if (PUGS_ENABLE_MPI MATCHES "^(AUTO|ON)$")
diff --git a/README.md b/README.md
index 4d1ed7f40f80eeb7a25b6b39871ae3c5402b6ee5..62d6b43773cb0164a29e8a3716a818c5ec219c7d 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,263 @@
-The Pugs framework
-==================
+The `pugs` framework
+====================
-Pugs stands for Parallel Unstructured Grid Solver.
+`pugs` stands for Parallel Unstructured Grid Solvers.
+
+It aims at providing a collection of numerical methods and utilities
+that are assembled together by a user friendly language.
+
+# Building `pugs`
+
+## Requirements
+
+For the most basic build, `pugs` only requires
+- a C++-17 compiler.
+ - g++-10 or higher versions
+ - clang-10 or higher versions
+- `CMake` (at least 3.16)
+
+> **Warning**:<br>
+> Building `pugs` in its source directory is **forbidden**. Trying to
+> do so will result in a failure. However it generally leaves some
+> garbage files in the source directory, namely the `CMakeCache.txt`
+> and the `CMakeFiles` directory. `CMake` itself is not able to remove
+> them, to avoid the risk of compilation issues, one has to dot it
+> manually...
+
+In the build directory, one for instance launches
+```shell
+cmake path-to-pugs-source
+```
+and then
+```shell
+make -j nb_jobs
+```
+Specifying the compiler is done for instance as
+```shell
+CXX=g++ CC=gcc cmake path-to-pugs-source
+```
+
+When compilation is done, `pugs` binary is produce. Additionally, one
+can run unit tests by
+```shell
+make check
+```
+
+## Optional packages
+
+`pugs` can benefit from additional packages to gain more
+functionalities or development tools.
+
+### Optional numerical tools
+
+#### MPI support
+
+`pugs` integrates MPI support and should compile with any MPI-3
+implementation. However in order to dispatch meshes on MPI processes
+`pugs` requires `ParMETIS`. Without, MPI support will be automatically
+deactivated.
+
+The easiest way to enable MPI support on Debian-like systems is to run
+```shell
+apt install libparmetis-dev
+```
+
+#### `PETSc`
+
+`pugs` can use `PETSc` to solve linear systems. In `pugs` the `PETSc`
+support requires MPI support.
+
+To install `PETSc` on Debian-like systems
+```shell
+apt install petsc-dev
+```
+
+#### `SLEPc`
+
+`SLEPc` is an eigenvalue problem solver based on `PETSc`. It requires
+`PETSc`.
+
+To install `SLEPc` on Debian-like systems
+```shell
+apt install slepc-dev
+```
+
+## Documentation
+
+### User documentation
+
+To build documentation one requires `emacs` and `gnuplot`,
+additionally since examples results are generated, the documentation
+can only be produced after the compilation of `pugs` itself.
+
+To install `emacs` on Debian-like systems
+```shell
+apt install emacs
+```
+To install `gnuplot` one can either use
+```shell
+apt install gnuplot-nox
+```
+or
+```shell
+apt install gnuplot-x11
+```
+> **Warning**:<br>
+> When building the documentation for the first time, a local `emacs`
+> configuration is generated. *This requires an internet connection.*
+
+These packages are enough to build the html documentation. To build
+the pdf documentation one requires a few more packages: `pdflatex`
+(actually a fresh texlive installation is probably necessary) and `pygmentize`
+
+On Debian-like systems these two packages are installed after
+```shell
+apt install texlive-full
+```
+
+Running the command
+```shell
+make doc
+```
+produces both the `html` and `pdf` documentation. Additional targets
+are
+- `userdoc`, `userdoc-pdf` and `userdoc-html`.
+
+> **Warning**:<br>
+> The documentation building **should not** be run in
+> parallel. Generation uses similar temporary files. A generation race
+> can produce corrupted documentations.
+
+### `doxygen` documentation
+
+## Development tools
+
+### `clang-format`
+
+If `clang-format` is found, a new compilation target is defined which
+allows to run
+
+```shell
+make clang-format
+```
+
+This allows to run `clang-format` on the entire code. **This should
+never be run** on non main development branches since `clang-format`
+versions may experience unpleasant compatibility issues.
+
+### Static analysis
+
+#### `scan-build`
+
+To install `scan-build`
+```shell
+apt install clang-tools
+```
+It is fairly simple to use. First launch
+```shell
+scan-build cmake path-to-pugs-source -DCMAKE_BUILD_TYPE=Debug
+```
+Observe that the code is built in debug mode to reduce false
+positives.
+
+Then compile `pugs`
+```shell
+scan-build make -j nb-jobs pugs
+```
+One can use any other generator such as `Ninja` for instance. Here we
+only build `pugs`'s binary, which is generally enough.
+
+At the end of the compilation, an hint such as
+```
+scan-build: Run 'scan-view /tmp/scan-build-XXXX-XX-XX-XXXXXX-XXXXX-X' to examine bug reports.
+```
+is produced. Running this command opens the report in the default
+browser.
+
+`scan-build` is a precious tool but may unfortunately produce false
+positives.
+
+#### `clang-tidy`
+
+We do not give details here about `clang-tidy`. It is a much more
+complex tool and should be used by more experienced developers since
+it requires fine tuning and produces a lot of false positive.
+
+#### `clazy`
+
+`clazy` is another great static-analysis tool. It checks constructions
+and gives some performances hints. It can be install by
+```shell
+apt install clazy
+```
+When `clazy` is installed a new target is defined and one just has to
+run
+```shell
+make clazy-standalone
+```
+
+> **Warning**:<br>
+> Since some generated sources files are required, one must first run
+> a classic compilation in the same build directory.
+
+This is a special homemade compilation procedure: specifying jobs has
+no effect. Each file is checked serially.
+
+## `CMake` building options
+
+In this section we give specific options that can be used to modify
+the way `pugs` is built.
+
+### Optimization options
+
+| Description | Variable | Values |
+|:------------|:------------------------|:---------------------------------------:|
+| Build type | `CMAKE_BUILD_TYPE` | `Release`(default), `Debug`, `Coverage` |
+| OpenMP | `Kokkos_ENABLE_OPENMP` | `ON`(default), `OFF` |
+| Pthread | `Kokkos_ENABLE_PTHREAD` | `ON`, `OFF`(default) |
+| Serial | `Kokkos_ENABLE_SERIAL` | `ON`, `OFF`(default) |
+
+- `Coverage` is a special compilation mode. It forces the run of unit
+ tests and produces coverage reports. See below for coverage
+ instructions.
+- OpenMP, PThread and Serial builds are mutually exclusive. OpenMP
+ support is automatically enabled as soon as the C++ compiler
+ supports it.
+
+### Additional packages support
+
+| Description | Variable | Values |
+|:----------------|:--------------------|:----------------------------:|
+| MPI support | `PUGS_ENABLE_MPI` | `AUTO`(default), `ON`, `OFF` |
+| `PETSc` support | `PUGS_ENABLE_PETSC` | `AUTO`(default), `ON`, `OFF` |
+| `SLEPc` support | `PUGS_ENABLE_SLEPC` | `AUTO`(default), `ON`, `OFF` |
+
+### Code coverage build
+
+To enable coverage more, one requires the following tools:
+- `lcov`
+- `gcov`
+- and `fastcov` when using `g++` as a compiler.
+
+To install these tools
+```shell
+apt install lcov gcov python3-pip
+```
+then to install `fastcov`, as the user do
+```shell
+pip3 install fastcov
+```
+
+Then to get coverage reports one can do
+```shell
+CXX=g++ CC=gcc cmake path-to-pugs-source -DCMAKE_BUILD_TYPE=Coverage
+```
+and
+```shell
+make -j nb-jobs
+```
+This produces a text report summary and a detailed html report is
+produced in the `coverage` directory.
+
+One can also use `clang` but the production of the report is much
+slower (does not use `fastcov`).