DOC: added Build and Requirements information

21599f03 · Mark Olesen · Andrew Heather · b46992f6 · 21599f03 · 21599f03
Commit 21599f03 authored Jun 07, 2019 by Mark Olesen Committed by Andrew Heather Jun 07, 2019
--- a/doc/Build.md
+++ b/doc/Build.md
+## OpenFOAM&reg; 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
--- a/doc/Requirements.md
+++ b/doc/Requirements.md
+## 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