Skip to content
Snippets Groups Projects

BUG: fix broken links, intra anchors, typos (#47)

Closed BUG: fix broken links, intra anchors, typos (#47)
bug-47-buildGuide into develop
Closed Kutalmış Berçin requested to merge bug-47-buildGuide into develop
Compare
and
1 file
+ 112
− 107
Preferences
Compare changes
BUILD.md
+ 112
− 107
@@ -26,7 +26,7 @@ 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
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,
```
@@ -41,11 +41,11 @@ usage: makeFFTW [OPTION] [fftw-VERSION]
0. Review the [system requirements][link openfoam-require]
and decide on the following:
* compiler type/version - if the system compiler is not relatively recent,
you will need a [third-party compiler](#makeGcc) installation.
you will need a [third-party compiler](#bootstrapping-optional) installation.
* MPI type/version.
* ParaView type/version.
* CMake type/version, ...
1. If you are using a system MPI (eg, openmpi), ensure that this environment
1. If you are using a system MPI (eg, Open MPI), 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.
@@ -60,7 +60,8 @@ which mpicc
- 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.
- After making the desired changes, use `wmRefresh` or
equivalent to use the configurations.
---
@@ -74,9 +75,10 @@ ThirdParty components prior to building OpenFOAM itself.
### Bootstrapping *(optional)*
* `makeGcc` _or_ `makeLLVM` <a name="makeGcc"></a>
- Makes a third-party [gcc](#gcc-compiler) or [clang](#clang-compiler) installation,
which is needed if the system gcc is [too old](#gcc-compiler).
* `makeGcc` _or_ `makeLLVM`
- Makes a third-party [GCC](#gcc-compiler) or [Clang](#clang-compiler)
installation, which is needed if the system GCC is
[too old](#gcc-compiler).
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:
@@ -87,11 +89,12 @@ ThirdParty components prior to building OpenFOAM itself.
`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
- *Attention*: If you are building a newer version of Clang, you may need to
update your CMake beforehand.
* `makeCmake`
- Makes a third-party [CMake](#general-packages) installation, which is
needed if a system CMake does not exist or is [too old](#min-cmake),
- Makes a third-party [CMake](#general) installation, which is
needed if a system CMake does not exist or is
[too old](#cmake-minimum-requirements),
- 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.
@@ -99,33 +102,33 @@ ThirdParty components prior to building OpenFOAM itself.
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
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:
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:
* 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.
* 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.
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.
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.
since this is the component that uses the MPFR library.
For example,
```
gmp_version=gmp-6.1.2
@@ -139,10 +142,12 @@ export GMP_ARCH_PATH=$WM_THIRD_PARTY_DIR/platforms/$WM_ARCH$WM_COMPILER_ARCH/$mp
### 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.
- 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 (Open MPI or MPICH), Scotch decomposition,
Boost, CGAL, FFTW.
- If the optional KaHIP or METIS directories are found,
they will also be compiled.
2. `makeParaView` *(optional)*
- This is optional, but extremely useful for visualization and for
run-time post-processing function objects.
@@ -155,20 +160,20 @@ export GMP_ARCH_PATH=$WM_THIRD_PARTY_DIR/platforms/$WM_ARCH$WM_COMPILER_ARCH/$mp
#### Optional Components
`makeAdios2`
- Only required for [ADIOS](#parallel) support.
- Only required for [ADIOS](#parallel-processing) support.
`makeCGAL`
- Builds [boost](#general-packages) and [CGAL](#general-packages).
- Builds [Boost](#general) and [CGAL](#general).
Automatically invoked from the ThirdParty `Allwmake`,
but can be invoked directly to resolve possible build errors.
`makeFFTW`
- Builds [FFTW](#general-packages).
- Builds [FFTW](#general).
Automatically invoked from the ThirdParty `Allwmake`,
but can be invoked directly to resolve possible build errors.
`makeKAHIP`
- Builds [KaHIP](#parallel) decomposition library.
- Builds [KaHIP](#parallel-processing) decomposition library.
Automatically invoked from the ThirdParty `Allwmake`,
but can be invoked directly to resolve possible build errors.
@@ -178,7 +183,7 @@ export GMP_ARCH_PATH=$WM_THIRD_PARTY_DIR/platforms/$WM_ARCH$WM_COMPILER_ARCH/$mp
but can be invoked directly to resolve possible build errors.
`makeSCOTCH`
- Builds [scotch, ptscotch](#parallel) decomposition libraries.
- Builds [Scotch, PT-Scotch](#parallel) decomposition libraries.
Automatically invoked from the ThirdParty `Allwmake`,
but can be invoked directly for special configurations
or to resolve possible build errors.
@@ -196,7 +201,7 @@ export GMP_ARCH_PATH=$WM_THIRD_PARTY_DIR/platforms/$WM_ARCH$WM_COMPILER_ARCH/$mp
suggestions about compiling such a configuration.
`makeQt`
- Script to build a [Qt](#makeQt), including qmake.
- Script to build a [Qt](#making-qt), including qmake.
- Possibly needed for `makeParaView`.
- The associated `etc/relocateQt` may be of independent use.
Read the file for more details.
@@ -209,8 +214,8 @@ export GMP_ARCH_PATH=$WM_THIRD_PARTY_DIR/platforms/$WM_ARCH$WM_COMPILER_ARCH/$mp
Report in sorted order.
`Allclean`
- After building, this script may be used to remove intermediate build information
and save some disk space.
- After building, this script may be used to remove intermediate build
information and save some disk space.
## Build Notes
@@ -256,7 +261,7 @@ set(VTK_BUILD_VERSION 0)
- 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](#makeQt) if necessary.
See additional notes below about [making Qt](#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
@@ -268,7 +273,7 @@ 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)
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:
@@ -276,7 +281,7 @@ detailed information:
$ export LIBGL_DEBUG=verbose
```
The call to paraview now emits this information:
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
@@ -294,7 +299,7 @@ version mismatch.
#### 5.6.x, 5.5.x binary packages
For general functionality, the paraview version distributed with
For general functionality, the ParaView version distributed with
the operating system or a [binary package][download ParaView]
may be sufficient for your needs.
- No known issues with the native OpenFOAM reader.
@@ -320,21 +325,21 @@ may not be important for you):
#### 5.3.0 and older are neither recommended nor supported
- Various compilation issues and known bugs.
### Making Qt <a name="makeQt"></a>
### 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 Qt5] package and
unpack in the third-party directory.
2. Use the `makeQt` script with the QT version number. For example,
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,
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.
- 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
@@ -342,38 +347,38 @@ may not be important for you):
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][link Qt56]) instead.
latest Qt. In these cases, it is sometimes possible to build a
slightly older Qt (eg, [qt-5.6.3][link Qt56]) instead.
---
## Versions
### Gcc Compiler <a name="gcc-compiler"></a>
### GCC Compiler
The minimum version of gcc required is **4.8.5**
The minimum version of GCC required is **4.8.5**
| Name | Location
|-------------------|--------------------------------------------
| [gcc][page gcc] | [releases][link gcc]
| [gmp][page gmp] | system is often ok, otherwise [download][link gmp]
| [mpfr][page mpfr] | system is often ok, otherwise [download][link mpfr]
| [mpc][page mpc] | system is often ok, otherwise [download][link mpc]
| [GCC][page gcc] | [releases][link gcc]
| [GMP][page gmp] | system is often ok, otherwise [download][link gmp]
| [MPFR][page mpfr] | system is often ok, otherwise [download][link mpfr]
| [MPC][page mpc] | system is often ok, otherwise [download][link mpc]
#### 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
If you select 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*).
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 ...`
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)
@@ -384,59 +389,59 @@ which is normally disabled, since many (most?) 64-bit systems do not
install the 32-bit development libraries by default.
### Clang Compiler <a name="clang-compiler"></a>
### Clang Compiler
The minimum version of clang required is **3.7**
The minimum version of Clang required is **3.7**
*Attention*: If you are building a newer version of clang, you may need to
*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.
to Clang version 3.9.
If your system gcc is particularly old
(see [minimum gcc requirements for clang](#min-gcc))
you may have additional hurdles to using the newest versions of clang.
If your system GCC is particularly old
(see [minimum GCC requirements for Clang](#gcc-minimum-requirements))
you may have additional hurdles to using the newest versions of Clang.
| Name | Location
|-----------------------|------------------------
| [clang][page clang] | [download][link clang] or [newer][newer clang]
| [llvm][page llvm] | [download][link llvm] or [newer][newer llvm]
| [openmp][page omp] | [download][link omp] or [newer][newer omp]
| [Clang][page clang] | [download][link clang] or [newer][newer clang]
| [LLVM][page llvm] | [download][link llvm] or [newer][newer llvm]
| [OpenMP][page omp] | [download][link omp] or [newer][newer omp]
### General <a name="general-packages"></a>
### General
| Name | Location
|-----------------------|------------------------
| [CMake][page cmake] | [download][link cmake]
| [boost][page boost] | [download][link boost]
| [Boost][page boost] | [download][link boost]
| [CGAL][page CGAL] | [download][link CGAL]
| [FFTW][page FFTW] | [download][link FFTW]
| [ADF/CGNS][page CGNS], ccm | [link ccmio][link ccmio]
| gperftools | [repo][repo gperftools] or [download][link gperftools]
### Parallel Processing <a name="parallel"></a>
### Parallel Processing
| Name | Location
|-----------------------|------------------------
| [openmpi][page openmpi] | [download][link openmpi]. The newer [openmpi][newer openmpi] make exhibit stability issues.
| [adios][page adios] | [repo][repo adios] or [github download][link adios] or [alt download][altlink adios]
| [scotch, ptscotch][page scotch] | [download][link scotch] or [older][older scotch]
| [kahip][page kahip] | [download][link kahip] or [older][older kahip]
| [metis][page metis] | [download][link metis]
| [Open MPI][page openmpi] | [download][link openmpi]. The newer [Open MPI][newer openmpi] make exhibit stability issues.
| [ADIOS1, ADIOS2][page adios] | [repo][repo adios] or [github download][link adios] or [alt download][altlink adios]
| [Scotch, PT-Scotch][page scotch] | [download][link scotch] or [older][older scotch]
| [KaHIP][page kahip] | [download][link kahip] or [older][older kahip]
| [METIS][page metis] | [download][link metis]
### Visualization <a name="viz-version"></a>
### Visualization
| Name | Location
|-----------------------|------------------------
| [MESA][page mesa] | [download][link mesa] or [older 13][link mesa13], [older 11][link mesa11]
| [ParaView][page ParaView] | [download][link ParaView] or [older paraview-55][link ParaView55], [older paraview-54][link ParaView54] or [binaries][download ParaView]
| [Qt][page Qt] | [QT5][link Qt5] for ParaView-5.3.0 and later, or the [older qt-56][link Qt56] for older systems.
| [Qt][page Qt] | [Qt5][link Qt5] for ParaView-5.3.0 and later, or the [older qt-56][link Qt56] for older systems.
### CMake Minimum Requirements <a name="min-cmake"></a>
### CMake Minimum Requirements
The minimum CMake requirements for building various components.
```
@@ -452,9 +457,9 @@ The minimum CMake requirements for building various components.
3.6 ADIOS2
```
### GCC Minimum Requirements <a name="min-gcc"></a>
### GCC Minimum Requirements
The minimum gcc/g++ requirements for building various components.
The minimum GCC/g++ requirements for building various components.
```
4.7 llvm-3.7.0
4.7 llvm-3.6.2
@@ -462,20 +467,20 @@ The minimum gcc/g++ requirements for building various components.
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.
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.
<!-- OpenFOAM, Internal links -->
[link AddOns]: https://develop.openfoam.com/Community/OpenFOAM-addOns
[link openfoam-readme]: https://develop.openfoam.com/Development/OpenFOAM-plus/blob/develop/README.md
[link openfoam-config]: https://develop.openfoam.com/Development/OpenFOAM-plus/blob/develop/doc/Config.md
[link openfoam-build]: https://develop.openfoam.com/Development/OpenFOAM-plus/blob/develop/doc/Build.md
[link AddOns]: https://develop.openfoam.com/Community/OpenFOAM-addOns
[link openfoam-readme]: https://develop.openfoam.com/Development/OpenFOAM-plus/blob/develop/README.md
[link openfoam-config]: https://develop.openfoam.com/Development/OpenFOAM-plus/blob/develop/doc/Config.md
[link openfoam-build]: https://develop.openfoam.com/Development/OpenFOAM-plus/blob/develop/doc/Build.md
[link openfoam-require]: https://develop.openfoam.com/Development/OpenFOAM-plus/blob/develop/doc/Requirements.md
[link third-readme]: https://develop.openfoam.com/Development/ThirdParty-plus/blob/develop/README.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-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
## Software Links
@@ -498,7 +503,7 @@ easier to use `grep` and find the relevant pages and links.
[link mpc]: ftp://ftp.gnu.org/gnu/mpc/mpc-1.1.0.tar.gz
<!-- clang-related -->
<!-- Clang-related -->
[page llvm]: http://llvm.org/
[page clang]: http://clang.llvm.org/
[page omp]: http://openmp.llvm.org/
@@ -513,7 +518,7 @@ easier to use `grep` and find the relevant pages and links.
<!-- parallel -->
[page adios]: https://www.olcf.ornl.gov/center-projects/adios/
[page adios]: https://csmd.ornl.gov/adios
[repo adios]: https://github.com/ornladios/ADIOS
[link adios]: https://github.com/ornladios/ADIOS2/archive/v2.5.0.tar.gz
[altlink adios]: http://users.nccs.gov/~pnorbert/adios-1.13.1.tar.gz
@@ -538,8 +543,8 @@ easier to use `grep` and find the relevant pages and links.
[page mpich]: http://www.mpich.org/
[link mpich]: http://www.mpich.org/static/downloads/3.3/mpich-3.3.tar.gz
[page mvpapich]: http://mvapich.cse.ohio-state.edu/
[link mvpapich]: http://mvapich.cse.ohio-state.edu/download/mvapich/mv2/mvapich2-2.3.tar.gz
[page mvpapich]: http://mvapich.cse.ohio-state.edu/
[link mvpapich]: http://mvapich.cse.ohio-state.edu/download/mvapich/mv2/mvapich2-2.3.tar.gz
<!-- general -->
@@ -556,8 +561,8 @@ easier to use `grep` and find the relevant pages and links.
[link FFTW]: http://www.fftw.org/fftw-3.3.7.tar.gz
[page cgns]: http://cgns.github.io/
[link ccmio]: http://portal.nersc.gov/project/visit/third_party/libccmio-2.6.1.tar.gz (check usage conditions)
[altlink ccmio]: http://portal.nersc.gov/svn/visit/trunk/third_party/libccmio-2.6.1.tar.gz (check usage conditions)
[link ccmio]: ftp://www.daba.lv/pub/TIS/bibliotekas/dazadas/libccmio-2.6.1.tar.gz (check usage conditions)
[altlink ccmio]: ftp://www.daba.lv/pub/TIS/bibliotekas/dazadas/libccmio-2.6.1.tar.gz (check usage conditions)
[repo gperftools]: https://github.com/gperftools/gperftools
[link gperftools]: https://github.com/gperftools/gperftools/releases/download/gperftools-2.5/gperftools-2.5.tar.gz
@@ -568,22 +573,22 @@ easier to use `grep` and find the relevant pages and links.
<!-- Visualization -->
[page ParaView]: http://www.paraview.org/
[page ParaView]: http://www.paraview.org/
[download ParaView]: https://www.paraview.org/download/
[link ParaView54]: http://www.paraview.org/files/v5.4/ParaView-v5.4.1.tar.gz
[link ParaView54]: http://www.paraview.org/files/v5.4/ParaView-v5.4.1.tar.gz
[link ParaView55]: http://www.paraview.org/files/v5.5/ParaView-v5.5.2.tar.gz
[link ParaView56]: http://www.paraview.org/files/v5.6/ParaView-v5.6.0.tar.gz
[link ParaView]: http://www.paraview.org/files/v5.6/ParaView-v5.7.0.tar.gz
[page mesa]: http://mesa3d.org/
[link mesa]: ftp://ftp.freedesktop.org/pub/mesa/mesa-17.1.1.tar.xz
[link mesa13]: ftp://ftp.freedesktop.org/pub/mesa/13.0.6/mesa-13.0.6.tar.xz
[link mesa11]: ftp://ftp.freedesktop.org/pub/mesa/older-versions/11.x/11.2.2/mesa-11.2.2.tar.xz
[page Qt]: https://www.qt.io/download-open-source/
[repo Qt]: http://code.qt.io/cgit/qt-creator/qt-creator.git
[link Qt56]: http://download.qt.io/official_releases/qt/5.6/5.6.3/single/qt-everywhere-opensource-src-5.6.3.tar.xz
[link Qt5]: http://download.qt.io/official_releases/qt/5.9/5.9.3/single/qt-everywhere-opensource-src-5.9.3.tar.xz
[link ParaView56]: http://www.paraview.org/files/v5.6/ParaView-v5.6.0.tar.gz
[link ParaView]: http://www.paraview.org/files/v5.7/ParaView-v5.7.0.tar.gz
[page mesa]: http://mesa3d.org/
[link mesa]: ftp://ftp.freedesktop.org/pub/mesa/older-versions/17.x/mesa-17.1.1.tar.xz
[link mesa13]: ftp://ftp.freedesktop.org/pub/mesa/older-versions/13.x/13.0.6/mesa-13.0.6.tar.xz
[link mesa11]: ftp://ftp.freedesktop.org/pub/mesa/older-versions/11.x/11.2.2/mesa-11.2.2.tar.xz
[page Qt]: https://www.qt.io/download-open-source/
[repo Qt]: http://code.qt.io/cgit/qt-creator/qt-creator.git
[link Qt56]: https://download.qt.io/archive/qt/5.6/5.6.3/single/qt-everywhere-opensource-src-5.6.3.tar.xz
[link Qt5]: http://download.qt.io/official_releases/qt/5.9/5.9.3/single/qt-everywhere-opensource-src-5.9.3.tar.xz
---