Skip to content
GitLab
Explore
Sign in
Primary navigation
Search or go to…
Project
pugs
Manage
Activity
Members
Labels
Plan
Issues
Issue boards
Milestones
Wiki
Code
Merge requests
Repository
Branches
Commits
Tags
Repository graph
Compare revisions
Snippets
Build
Pipelines
Jobs
Pipeline schedules
Artifacts
Deploy
Releases
Model registry
Operate
Environments
Monitor
Incidents
Analyze
Value stream analytics
Contributor analytics
CI/CD analytics
Repository analytics
Model experiments
Help
Help
Support
GitLab documentation
Compare GitLab plans
Community forum
Contribute to GitLab
Provide feedback
Keyboard shortcuts
?
Snippets
Groups
Projects
Show more breadcrumbs
code
pugs
Commits
14be3644
Commit
14be3644
authored
2 years ago
by
Stéphane Del Pino
Browse files
Options
Downloads
Patches
Plain Diff
Improve README.md
parent
881604e2
No related branches found
No related tags found
1 merge request
!156
Improve cmake scripts to find required utilities
Changes
2
Show whitespace changes
Inline
Side-by-side
Showing
2 changed files
CMakeLists.txt
+3
-1
3 additions, 1 deletion
CMakeLists.txt
README.md
+262
-3
262 additions, 3 deletions
README.md
with
265 additions
and
4 deletions
CMakeLists.txt
+
3
−
1
View file @
14be3644
...
@@ -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)$"
)
...
...
This diff is collapsed.
Click to expand it.
README.md
+
262
−
3
View file @
14be3644
The
P
ugs framework
The
`p
ugs
`
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`
).
This diff is collapsed.
Click to expand it.
Preview
0%
Loading
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Save comment
Cancel
Please
register
or
sign in
to comment