diff --git a/doc/Build.md b/doc/Build.md new file mode 100644 index 0000000000000000000000000000000000000000..7e524ebed3403dfb88e3dcef1c9bd7066d2020fa --- /dev/null +++ b/doc/Build.md @@ -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 diff --git a/doc/Requirements.md b/doc/Requirements.md new file mode 100644 index 0000000000000000000000000000000000000000..1ddf73f0fb8ee0cf7bf3be9d1a85575dc4553936 --- /dev/null +++ b/doc/Requirements.md @@ -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