Commit 21599f03 authored by Mark Olesen's avatar Mark Olesen Committed by Andrew Heather
Browse files

DOC: added Build and Requirements information

parent b46992f6
## OpenFOAM® Quick Build Guide
Ensure that the [system requirements][link openfoam-require] are satisfied as described here,
and make sure to source the correct OpenFOAM environment. For example,
for the OpenFOAM-v1906 version:
```
source /installation/path/OpenFOAM-v1906/etc/bashrc
```
## Preliminaries
The [third-party][link third-party] directory includes a
[readme][link third-readme] and additional information about
[requirements][link third-require] and a more detailed
[build guide][link third-build].
Some known build issues related to specific compiler and VTK library versions
can be found in the [$WM_PROJECT_DIR/BuildIssues.txt][link openfoam-issues] file.
If you need to change the default versions for third-party libraries,
or use system libraries for some components, please some additional
information about the [config structure][link openfoam-config].
## Compile OpenFOAM
The compilation process is self-contained and will compile and install
all OpenFOAM code and dependencies.
- Test the system readiness (optional)
```
foamSystemCheck
```
- Change to the main OpenFOAM directory ($WM_PROJECT_DIR).
If this fails, the environment is not correctly configured.
```
foam
```
- Compile OpenFOAM
```
./Allwmake -s -l
```
- In case you need to stop the compilation, continue later by running
`./Allwmake` again.
## Compile OpenFOAM faster
For faster compilation, users should take advantage of multi-processor
machines when building the code. This is supported directly by `wmake`
and the `Allwmake` scripts. For example,
```
wmake -j # Use all cores
wmake -j 8 # Use specified number of cores
```
It can also be helpful to use the builtin queuing (the `-queue`
option), which collects subdirectories and dispatches to make in
larger chunks.
The following compilation sequence can be useful:
```
./Allwmake -j -s -q -l
```
This compiles with all cores (-j), reduced output (-s, -silent), with
queuing (-q, -queue) and logs (-l, -log) the output to a file such as
`log.linux64GccDPInt32Opt` for later inspection.
If you use the `-k` option (`-keep-going` = ignore errors) to compile
as much as possible on the first pass, be certain to follow that with
second pass (without the `-k` option) at a later stage to ensure that
you haven't missed any error messages.
## Post-compilation steps
- Open a new shell and source the OpenFOAM environment to see all
changes (refer to top of page).
- Validate the build by running
```
foamInstallationTest
```
- Create the user `run` directory:
```
mkdir -p $FOAM_RUN
```
- Test the installation with a simple tutorial:
```
run
cp -r $FOAM_TUTORIALS/incompressible/simpleFoam/pitzDaily ./
cd pitzDaily
blockMesh
simpleFoam
```
### ParaView
OpenFOAM ships with ParaView sources for post-processing OpenFOAM
field results. However, the paraview version distributed with
the operating system or a [binary package][download ParaView]
will be sufficient, and avoids additional compilation complexity.
If do you wish to compile ParaView from sources, it is recommended
that you do so *after* completing an initial compilation of OpenFOAM.
This gets the process started much more quickly. At a later stage,
OpenFOAM can be updated to compile with paraview. Only the affected
applications will be compiled (eg, the blockMesh reader module) and the
balance of the OpenFOAM installation will not affected.
If you decide to compiling in two passes, you only need to execute the
top-level `Allwmake` a second time. Do **not** use `wclean` to force a
complete rebuild! This is unnecessary.
More details in the [ThirdParty build guide][link third-build].
------------
<!-- Links -->
[page ParaView]: http://www.paraview.org/
[download ParaView]: https://www.paraview.org/download/
<!-- OpenFOAM -->
[link openfoam-issues]: https://develop.openfoam.com/Development/OpenFOAM-plus/blob/develop/BuildIssues.txt
[link openfoam-build]: https://develop.openfoam.com/Development/OpenFOAM-plus/blob/develop/doc/BUILD.md
[link openfoam-config]: https://develop.openfoam.com/Development/OpenFOAM-plus/blob/develop/etc/README.md
[link openfoam-require]: https://develop.openfoam.com/Development/OpenFOAM-plus/blob/develop/doc/Requirements.md
[link third-build]: https://develop.openfoam.com/Development/ThirdParty-plus/blob/develop/BUILD.md
[link third-require]: https://develop.openfoam.com/Development/ThirdParty-plus/blob/develop/Requirements.md
[link third-readme]: https://develop.openfoam.com/Development/ThirdParty-plus/blob/develop/README.md
[link third-party]: https://develop.openfoam.com/Development/ThirdParty-plus/
---
Copyright 2019 OpenCFD Ltd
## OpenFOAM&reg; System Requirements
OpenFOAM requires a functioning C++11 compiler and `make` build toolchain.
### Minimum recommended versions
- gcc: 4.8.5
- cmake: 3.3 (required for ParaView and CGAL build)
- boost: 1.48 (required for CGAL build and some functionality)
- fftw: 3.3.7 (recommended - required for FFT-related functionality)
- paraview: 5.5.2 (for visualization)
To check the installed versions
| Program | To check the version |
|---------------|-----------------------|
| gcc | gcc --version |
| cmake | cmake --version |
| openmpi | orterun --version |
### Additional utilities
- flex
- QT: 5.9 (optional - for ParaView build)
### Ubuntu (eg, 19.04)
Install dependencies by executing the following lines on the command line:
```
sudo apt-get install build-essential flex cmake zlib1g-dev libopenmpi-dev openmpi-bin gnuplot libreadline-dev libncurses-dev
sudo apt-get install libgmp-dev libmpfr-dev libmpc-dev
```
Additional libraries will be required if compiling ParaView from
source, however it is suggested to skipped this initially since
it generally represent the main compilation difficulty.
In many cases, a system installation of paraview or a
[precompiled binary][download ParaView]
will be much easier.
Some libraries can be installed from from the operating system, or
compiled from the ThirdParty directory.
The default configuration for OpenFOAM assumes OpenMPI from the system
and ThirdParty installations for most others (boost, CGAL, FFTW,
Kahip, Scotch). This is generally the most portable configuration
across various Linux distributions, but it may be desirable to use
more system libraries on Ubuntu.
To inspect the available system versions, use the `apt-cache show`
command. For example,
```
sudo apt-cache show fftw3-dev
```
| Program | apt-cache show | Ubuntu | Version |
|-----------|-----------------|---------|---------|
| boost | libboost-dev | 19.04 | 1.67 |
| CGAL | libcgal-dev | 19.04 | 4.13 |
| FFTW | libfftw3-dev | 19.04 | 3.3.8 |
| scotch | libscotch-dev | 19.04 | 6.0.6 |
| Program | Ubuntu | Program version |
|-----------|-----------|-----------------|
| gcc | 19.04 | 8.3.0 |
| openmpi | 19.04 | 3.1.3 |
| cmake | 19.04 | 3.13.4 |
| flex | 19.04 | 2.6.4 |
### openSUSE (eg, Leap-15.0)
Install the dependencies by copying and pasting the following lines to the command line:
```
sudo zypper install -t pattern devel_C_C++
sudo zypper install cmake boost-devel mpfr-devel gmp-devel openmpi-devel gnuplot
```
This installs
| Program | openSUSE | Program version |
|-----------|-----------|-----------------|
| gcc | 15.0 | 7.4.3 |
| openmpi | 15.0 | 1.10.7 |
| cmake | 15.0 | 3.10.2 |
| flex | 15.0 | 2.6.4 |
#### OpenMPI
Check that the openmpi installation can be found:
```
orterun --version
```
And the command `mpicc --show` should display a complete compilation
line. This information is used in OpenFOAM to obtain the
compilation and link options.
For openSUSE it is common that this command cannot be found.
The reason being that the operating system can have several different
MPI vendors and versions installed and the user or sysadmin needs to
defined the preferred MPI. For this task, the `mpi-selector` and
`mpi-selector-menu` programs are used. These are automatically installed
by the system when openmpi has been installed.
If openmpi has been selected, the output will resemble the following:
```
$ mpi-selector --query
default:openmpi
level:user
```
If this is not the case, the `mpi-selector-menu` can be used to define
the preferred default.
***Note that changes in the preferred MPI do not take effect until the
next login.***
If all else fails, a brute force solution can also be used by simply
adding the corresponding lines to the `$HOME/.bashrc` file:
```
export PATH=$PATH:/usr/lib64/mpi/gcc/openmpi/bin
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib64/mpi/gcc/openmpi/lib
```
This solution is not particularly nice, but may also be necessary if
some other part of the operating system installation is incomplete.
### Using IntelMPI
To run with IntelMPI, the LD_PRELOAD environment variable can be used
to pre-load the appropriate Intel&reg; MPI binding library. For more
details, see INTELMPI release note page 13.
The following line can be the `$HOME/.bashrc` file:
```
export LD_PRELOAD="libmpi.so"
```
### Additional libraries
When compiled ParaView from source additional dependencies will be
required.
A partial list is given in the [ThirdParty requirements][third-require].
**Please help us with keeping that information up-to-date and accurate.**
<!-- Links -->
[page ParaView]: http://www.paraview.org/
[download ParaView]: https://www.paraview.org/download/
<!-- OpenFOAM -->
[link openfoam-build]: https://develop.openfoam.com/Development/OpenFOAM-plus/blob/develop/doc/BUILD.md
[link openfoam-config]: https://develop.openfoam.com/Development/OpenFOAM-plus/blob/develop/etc/README.md
[link openfoam-require]: https://develop.openfoam.com/Development/OpenFOAM-plus/blob/develop/doc/Requirements.md
[link third-build]: https://develop.openfoam.com/Development/ThirdParty-plus/blob/develop/BUILD.md
[link third-require]: https://develop.openfoam.com/Development/ThirdParty-plus/blob/develop/Requirements.md
[link third-readme]: https://develop.openfoam.com/Development/ThirdParty-plus/blob/develop/README.md
---
Copyright 2019 OpenCFD Ltd
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment