ThirdParty-common/BUILD.md

OpenFOAM® ThirdParty Build

OpenFOAM depends to a certain extent on third-party libraries (opensource only). It also provides some interfaces to opensource or proprietary libraries. This third-party collection contains configurations and scripts for building third-party packages. It will normally only be used in conjunction with the corresponding OpenFOAM version.

Directory Organization

The ThirdParty directory contains a number of build scripts as well as some directories:

Directory	Contains
etc/	auxiliary tools and content used for the build process
build/	intermediate build objects
platforms/	the installation directories

Configuration of Third-Party Versions

For most of the build scripts, the default software version is provided by an appropriate OpenFOAM etc/config.sh/... entry. This approach avoids duplicate entries for the default versions and ensures the best overall consistency between the OpenFOAM installation and its corresponding third-party installation.

Nonetheless, the distributed make scripts can generally be used for a variety of versions of the third-party libraries, with the software version specified on the command-line. For example,

$ ./makeFFTW -help
Usage: makeFFTW [OPTION] [fftw-VERSION]

---

Before Starting

0. Review the system requirements and decide on the following:
   • compiler type/version - if the system compiler is not relatively recent, you will need a third-party compiler installation.
   • MPI type/version.
   • ParaView type/version.
   • CMake type/version, ...
1. If you are using a system MPI (eg, openmpi), ensure that this environment has also been properly activated for your user. Often (but not always) a mpi-selector command is available for this purpose. You may need to open a new shell afterwards for the change to take effect. Using the following command may help diagnosing things:

which mpicc

2. Adjust the OpenFOAM etc/bashrc, etc/config.sh/... or equivalent the etc/prefs.{csh,sh} files to reflect your preferred configuration. For many config files, there are several configuration possibilities:
   • Define a particular third-party version.
   • Use a system installation.
   • Disable use of an optional component.
   • Define an alternative site-wide central location.

See the OpenFOAM configuration information for more details. After making the desired changes, use the wmRefresh alias or equivalent to enable the configuration.

---

Building

Many components of ThirdParty are optional or are invoked automatically as part of the top-level OpenFOAM Allwmake. Nonetheless it may be necessary or useful to build various ThirdParty components prior to building OpenFOAM itself.

Bootstrapping (optional)

• makeGcc or makeLLVM
  • Makes a third-party gcc or clang installation, which is needed if the system gcc is too old. If your system compiler is recent enough, you can skip this step.
  • If you do use this option, you will need the following adjustments to the OpenFOAM etc/bashrc or your equivalent prefs.sh file:
    • WM_COMPILER_TYPE=ThirdParty
    • WM_COMPILER=Gcc48 (for example)
    • WM_COMPILER=Clang40 (for example)
    • or WM_COMPILER=Clang and adjust clang_version in the OpenFOAM etc/config.sh/compiler or equivalent.
  • More description is contained in the header comments of the makeGcc and makeLLVM files.
  • Attention: If you are building a newer version of clang, you may need to update your CMake beforehand.
• makeCmake
  • Makes a third-party CMake installation, which is needed if a system CMake does not exist or is too old,
  • Note that CMake is being used by an number of third-party packages (CGAL, LLVM, ParaView, VTK, ...) so this may become an increasingly important aspect of the build.

Note that the order of the bootstrapping process may need to be reversed, or even require a few loops. For example, if you may need a newer version of CMake before being able to build LLVM/Clang and subsequently use the newly build clang to create a newer version of CMake in the desired location.

Additionally, if you are using clang but with ThirdParty locations for gmp/mpfr you will need some extra work. Here is an example:

• Compile a new ThirdParty clang version:

./makeLLVM llvm-4.0.1

• Now adjust the OpenFOAM prefs.sh to use the new compiler settings, and update the OpenFOAM environment (eg, wmRefresh)

• Next use (abuse) the makeGcc script to compile gmp/mpfr libraries. It is best to pass the desired versions explicitly, and necessary to set the CC/CXX variables so that the correct compiler is used:

CC=clang CXX=clang++  ./makeGcc gmp-6.1.2 mpfr-4.0.0 gcc-system

specifying gcc-system effectively disables building of gcc, but will build the gmp/mpfr components.

• As a final step, it will be necessary to add the ThirdParty gmp/mpfr locations in the OpenFOAM config files since they are normally only used in combination with a ThirdParty gcc. The location to make these changes is in the etc/config.sh/CGAL, since this is the component that uses the mpfr library. For example,

gmp_version=gmp-6.1.2
mpfr_version=mpfr-4.0.0
export GMP_ARCH_PATH=$WM_THIRD_PARTY_DIR/platforms/$WM_ARCH$WM_COMPILER_ARCH/$gmp_version
export GMP_ARCH_PATH=$WM_THIRD_PARTY_DIR/platforms/$WM_ARCH$WM_COMPILER_ARCH/$mpfr_version

• Update update the OpenFOAM environment (eg, wmRefresh) again.

Build Sequence

1. Allwmake
   • This will be automatically invoked by the top-level OpenFOAM Allwmake, but can also be invoked directly to find possible build errors.
   • Builds an mpi library (openmpi or mpich), scotch decomposition, boost, CGAL, FFTW.
   • If the optional kahip or metis directories are found, they will also be compiled.
2. makeParaView (optional)
   • Can be useful for visualization and for run-time post-processing function objects. You can build this at a later point in time, and rebuild the visualization modules.
3. Make any additional optional components

Optional Components

makeAdios2

• Only required for ADIOS support.

makeCGAL

• Builds boost and CGAL. Automatically invoked from the ThirdParty Allwmake, but can be invoked directly to resolve possible build errors.

makeFFTW

• Builds FFTW. Automatically invoked from the ThirdParty Allwmake, but can be invoked directly to resolve possible build errors.

makeKAHIP

• Builds KaHIP decomposition library. Automatically invoked from the ThirdParty Allwmake, but can be invoked directly to resolve possible build errors.

makeOPENMPI

• Builds OPENMPI library.

makePETSC

• Only required for PETSC support.

makeMETIS

• Builds METIS decomposition library. Automatically invoked from the ThirdParty Allwmake, but can be invoked directly to resolve possible build errors.

makeSCOTCH

• Builds scotch, ptscotch decomposition libraries. Automatically invoked from the ThirdParty Allwmake, but can be invoked directly for special configurations or to resolve possible build errors.

makeMGridGen

• Optional agglomeration routines.

makeCCMIO

• Only required for conversion to/from STARCD/STARCCM+ files.

makeMesa, makeVTK

• Additional support for building offscreen rendering components. Useful if you want to render on computer servers without graphics cards. The makeParaView.example and makeVTK.example files offer some suggestions about compiling such a configuration.

makeQt

• Script to build a Qt, including qmake.
• Possibly needed for makeParaView.
• The associated etc/relocateQt may be of independent use. Read the file for more details.

makeGperftools

• Build gperftools (originally Google Performance Tools)

minCmake

• Scour specified directories for CMakeLists.txt and their cmake_minimum. Report in sorted order.

Allclean

• After building, this script may be used to remove intermediate build information and save some disk space.

Build Notes

CGAL

• The zlib library and development headers are required.

Scotch

• The zlib library and development headers are required.

Mesa

• Needed for off-screen rendering.
• Building with mesa-11 and mesa-13 both seem okay, as does building with mesa-17.
• Building with mesa-12 is not possible since it fails to create the necessary include/GL directory and osmesa.h file.

VTK

• Needed for off-screen rendering and run-time post-processing without ParaView.
• Rather than downloading VTK separately, it is easy to reuse the VTK sources that are bundled with ParaView. For example, by using a symbolic link:

ln -s ParaView-v5.6.0/VTK VTK-8.2.0

The appropriate VTK version number can be found from the contents of the vtkVersion.cmake file. For example,

$ cat ParaView-v5.6.0/VTK/CMake/vtkVersion.cmake

contains this type of information

# VTK version number components.
set(VTK_MAJOR_VERSION 8)
set(VTK_MINOR_VERSION 2)
set(VTK_BUILD_VERSION 0)

ParaView

• Building ParaView requires CMake, qmake and a qt development files. Use the -cmake, -qmake and -qt-* options for makeParaView as required. See additional notes below about making Qt if necessary.

NOTE this step may not be entirely successful for your particular system. Building ParaView itself is generally not a significant problem but its dependency on particular Qt versions can be a problem.

If you fail at this step due to Qt dependencies, you may have success building a slightly older Qt version. Another alternative may be to use the ParaView-5.4 sources that were included in the ThirdParty-v1712 source pack. This, however, has never been tested in combination with the OpenFOAM Catalyst insitu visualization.

If you encounter problems starting paraview (eg, segmentation fault) it could be related to the graphics libraries not being properly found. The LIBGL_DEBUG environment variable can be used to obtain more detailed information:

$ export LIBGL_DEBUG=verbose

The call to paraview now emits this information:

libGL: screen 0 does not appear to be DRI2 capable
libGL: OpenDriver: trying /usr/lib64/dri/tls/swrast_dri.so
libGL: OpenDriver: trying /usr/lib64/dri/swrast_dri.so
...
libGL error: No matching fbConfigs or visuals found
libGL error: failed to load driver: swrast

Indicating that the drivers are probably not correctly installed. The /var/log/Xorg.0.log file or the dmesg command may yield more information to the cause. In this particular case, the Nvidia drivers had a client/server version mismatch.

5.6.x, 5.5.x binary packages

For general functionality, the paraview version distributed with the operating system or a binary package may be sufficient for your needs.

• No known issues with the native OpenFOAM reader.

Using a binary package does mean you miss these elements (which may or may not be important for you):

• cannot visualize a blockMeshDict
• cannot build Catalyst insitu visualization
• no alternative OpenFOAM reader module for some special features not found in the native OpenFOAM reader.

5.5.x

• Requires patching for the vtk-m configuration (on some systems).
• Recommended patching for ParaView Catalyst.
• Recommended patching for file series No known issues with the native OpenFOAM reader.

5.4.x

• Compiles without patching. No known issues with the native OpenFOAM reader.

5.3.0 and older are neither recommended nor supported

• Various compilation issues and known bugs.

Making Qt

• Building a third-party Qt installation (prior to building ParaView) requires some additional effort, but should nonetheless work smoothly.

1. Download a qt-everywhere-opensource-src package and unpack in the third-party directory.
2. Use the makeQt script with the QT version number. For example,

./makeQt 5.9.3

3. Build ParaView using this third-party QT. For example,

./makeParaView -qt-5.9.3  5.6.0

• ParaView versions prior to 5.3.0 do not properly support QT5.

• If you relocate the third-party directory to another location (eg, you built in your home directory, but want to install it in a central location), you will need to use the etc/relocateQt script afterwards.

Note On some older systems it can be quite difficult to build the latest QT. In these cases, it is sometimes possible to build a slightly older QT (eg, qt-5.6.3) instead.

---

Versions

Gcc Compiler

The minimum version of gcc required is 4.8.5

Name	Location
gcc	releases
gmp	system is often ok, otherwise download
mpfr	system is often ok, otherwise download
mpc	system is often ok, otherwise download

Potential MPFR conflicts

If you elect to use a third-party version of mpfr, you may experience conflicts with your installed system mpfr. On some systems, mpfr is compiled as non-threaded, whereas the third-party will use threaded by default. This can cause some confusion at the linker stage, since it may resolve the system mpfr first (and find that it is non-threaded).

You can avoid this by one of two means:

1. Use system components for gmp/mpfr/mpc: makeGcc -system ...
2. Use third-party mpfr, but without threading: makeGcc -no-threadsafe ...

32-bit build (on 64-bit)

If you have a 64-bit system, but wish to have a 32-bit compiler, you will need to enable multi-lib support for Gcc: makeGcc -multilib, which is normally disabled, since many (most?) 64-bit systems do not install the 32-bit development libraries by default.

Clang Compiler

The minimum version of clang required is 3.7

Attention: If you are building a newer version of clang, you may need to update your CMake beforehand since GNU configure can only be used prior to clang version 3.9.

If your system gcc is particularly old (see minimum gcc requirements for clang) you may have additional hurdles to using the newest versions of clang.

Name	Location
clang	download or newer
llvm	download or newer
openmp	download or newer

General

Name	Location
CMake	download
boost	download
CGAL	download
FFTW	download
HDF5	download
PETSC	download
HYPRE	repo or download
ADF/CGNS, ccm	link ccmio
gperftools	repo or download

Parallel Processing

Name	Location
openmpi	download. Some openmpi2/openmpi3 versions exhibit stability issues
adios	repo or github download
scotch, ptscotch	repo or download or older
kahip	download or older
metis	download

Visualization

Name	Location
MESA	download or older 13, older 11
ParaView	download or older paraview-56 or binaries
Qt	QT5 for ParaView-5.3.0 and later, or the older qt-56 for older systems.

CMake Minimum Requirements

The minimum CMake requirements for building various components.

2.8         llvm-3.4.2
2.8.11      CGAL-4.9
2.8.11      CGAL-4.11
3.1         CGAL-4.12 -> CGAL-4.14.3
2.8.12.2    llvm-3.7.0
2.8.12.2    llvm-3.8.0
2.8.4       cmake-3.6.0
3.3         ParaView-5.6.3
3.10        ParaView-5.7.0 - ParaView-5.8.0
3.12 - 3.16 ParaView-5.9.0 - ParaView-5.10.1
3.4.3       llvm-3.9.1
3.4.3       llvm-4.0.0 - llvm-6.0.0
3.12        ADIOS2

GCC Minimum Requirements

The minimum gcc/g++ requirements for building various components.

4.7         llvm-3.7.0
4.7         llvm-3.6.2
4.7         llvm-3.5.2
4.4         llvm-3.4.2

If your system gcc/g++ is too old to build the desired llvm/clang version, you may need to build a lower llvm/clang version and then use that clang compiler for building the newer llvm/clang version.

Software Links

If you have access to this information file in its raw form, you will note that most of the software pages and download links are listed as a collection at the end of the file. This is designed to make it easier to use grep and find the relevant pages and links.

---

Copyright 2016-2024 OpenCFD Ltd