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 package contains configurations and scripts for building third-party packages. It should normally only be used in conjunction with the corresponding OpenFOAM version.

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.

Nonethess, 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 prefs.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.
   • After making the desired changes, use wmRefresh or equivalent to use the configurations.

---

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.

Build Sequence

1. makeGcc or makeLLVM (optional)
   • 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)
     • or WM_COMPILER=Clang and adjust the clang_version entry 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.
2. makeCmake (optional)
   • 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.
3. 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.
4. makeParaView (optional but highly recommended)
   • This is optional, but extremely useful for visualization and for run-time post-processing function objects. You can build this at a later point in time, but then you should remember to rebuild the post-processing function objects and the reader module as well.
5. Make any additional optional components

Optional Components

makeADIOS

• Only required for ADIOS support, which is currently staged in the add-ons repository.

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.

makeMETIS

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

makeMGridGen

• Optional agglomeration routines.

makeCCMIO

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

makeTecio

• Only required for conversion of results to Tecplot format.

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

Scotch

• The zlib library and zlib 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.4.1/VTK VTK-8.1.0
  

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

  $ cat ParaView-v5.4.1/VTK/CMake/vtkVersion.cmake
  
  # VTK version number components.
  set(VTK_MAJOR_VERSION 8)
  set(VTK_MINOR_VERSION 1)
  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.

5.4.x

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

5.3.0

• Compiles without patching. The native OpenFOAM reader has a bug reading tetrahedrals.

5.2.0

• Compiles without patching, but the native OpenFOAM reader is broken in this version.

4.4.0/5.0.0/5.0.1/5.1.2

• When using makeParaView, the following patches will be automatically applied (see the etc/patches directory):
  • Bugfix for STL reader - affects 4.4.0 only.
  • Broken installation (ui_pqExportStateWizard.h) - affects 4.4.0/5.0.0/5.0.1/5.1.x
  • Building with gcc-6.1.0 - affects 4.4.0/5.0.0/5.0.1 (patch applied for 5.0.1)
  • The SciberQuestToolKit plugin fails to compile with gcc-6.1.0 and causes the compilation of ParaView to halt. The easiest solution is to delete the ParaView-5.0.1/Plugins/SciberQuestToolKit directory.

ADIOS

• The github release currently requires GNU autoconf tools (eg, autoconf, autoheader, automake) for its configuration.
• Some inconsistency in directory names (ADIOS vs. adios) between releases.
• Optionally uses bzip2, zlib development headers (eg, libbz2-devel, zlib-devel) for the corresponding compression tranforms.
• The zfp floating point compression library is now included as part of ADIOS.

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][link Qt] package and unpack in the third-party directory.

2. Use the makeQt script with the QT version number. For example,

   ./makeQt 4.8.7
   

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

   ./makeParaView -qt-4.8.7 5.0.1
   

• 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.

---

Versions

Gcc Compiler

The minimum version of gcc required is 4.8.0.

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.3.

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

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
ADF/CGNS, ccm	link ccmio
tecio	link tecio
gperftools	repo or download

Parallel Processing

Name	Location
openmpi	download. The newer openmpi make exhibit stability issues.
adios	repo or github download or alt download
scotch, ptscotch	download
kahip	download
metis	download

Visualization

Name	Location
MESA	download or older 13, older 11
ParaView	download
Qt	Either the older QT4 or the newer QT5, which only works with ParaView-5.3.0 and later.

CMake Minimum Requirements

The minimum CMake requirements for building various components.

2.8         llvm-3.4.2
2.8.8       ParaView-5.0.1
2.8.11      CGAL-4.9
2.8.11      CGAL-4.11
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.1.2
3.3         ParaView-5.2.0
3.3         ParaView-5.3.0
3.3         ParaView-5.4.1
3.4.3       llvm-3.9.1
3.4.3       llvm-4.0.0
3.5         ParaView-5.1.0

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

Additional OpenFOAM Links

• Community AddOns repository
• Collaborative and Community-based Developments
• Download and installation instructions
• Documentation
• Reporting bugs/issues (including bugs/suggestions/feature requests) in OpenFOAM
• Contacting OpenCFD

---

Copyright 2016-2017 OpenCFD Ltd