DOC: added Build and Requirements information
This commit is contained in:
Mark Olesen
Andrew Heather
parent
b46992f66b
commit
21599f0365
134
doc/Build.md
Normal file
134
doc/Build.md
Normal file
@ -0,0 +1,134 @@
|
||||
## 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
|
||||
167
doc/Requirements.md
Normal file
167
doc/Requirements.md
Normal file
@ -0,0 +1,167 @@
|
||||
## OpenFOAM® 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® 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
|
||||
Loading…
Reference in New Issue
Block a user