Skip to content
Snippets Groups Projects
Commit 14be3644 authored by Stéphane Del Pino's avatar Stéphane Del Pino
Browse files

Improve README.md

parent 881604e2
No related branches found
No related tags found
1 merge request!156Improve cmake scripts to find required utilities
...@@ -638,7 +638,9 @@ message(" kokkos devices: ${PUGS_BUILD_KOKKOS_DEVICES}") ...@@ -638,7 +638,9 @@ message(" kokkos devices: ${PUGS_BUILD_KOKKOS_DEVICES}")
if (MPI_FOUND) if (MPI_FOUND)
message(" MPI: ${MPI_CXX_LIBRARY_VERSION_STRING}") message(" MPI: ${MPI_CXX_LIBRARY_VERSION_STRING}")
else() 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!") message(" MPI: deactivated: ParMETIS cannot be found!")
else() else()
if (PUGS_ENABLE_MPI MATCHES "^(AUTO|ON)$") if (PUGS_ENABLE_MPI MATCHES "^(AUTO|ON)$")
......
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`).
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment