From 4e0222f887ba1b9462d027a32031d722fa3196f2 Mon Sep 17 00:00:00 2001 From: Mark Olesen <Mark.Olesen@esi-group.com> Date: Thu, 13 Jun 2019 18:43:07 +0200 Subject: [PATCH] DOC: relocated OpenFOAM etc/README.md to doc/Config.md - relocated BuildIssues.txt -> doc/BuildIssues.md --- BuildIssues.txt | 121 --------------------------------- README.md | 4 +- doc/Build.md | 14 ++-- doc/BuildIssues.md | 111 ++++++++++++++++++++++++++++++ etc/README.md => doc/Config.md | 0 doc/Requirements.md | 9 ++- etc/config.csh/vtk | 2 +- etc/config.sh/vtk | 2 +- 8 files changed, 130 insertions(+), 133 deletions(-) delete mode 100644 BuildIssues.txt create mode 100644 doc/BuildIssues.md rename etc/README.md => doc/Config.md (100%) diff --git a/BuildIssues.txt b/BuildIssues.txt deleted file mode 100644 index a05b5301c3c..00000000000 --- a/BuildIssues.txt +++ /dev/null @@ -1,121 +0,0 @@ -OpenFOAM-1712 -================== -Known Build Issues -================== - ---------------------- -Intel MPI (Gcc/Clang) ---------------------- - - Either I_MPI_ROOT or MPI_ROOT can be used to specify the Intel-MPI - installation directory path. - - The ThirdParty build of ptscotch uses `mpiicc` for Intel-MPI - instead of the usual `mpicc`. - When gcc or clang are used, it is highly likely that the - I_MPI_CC environment variable also needs to be set accordingly. - - See `mpiicc -help` for more information about environment variables. - - --------------- -Intel Compiler --------------- - - Since OpenFOAM uses C++11, a fairly recent version is required. - The Intel compiler - icc (ICC) 17.0.1 20161005 is ok, but the - initial release - icc (ICC) 17.0.0 20160721 - has a bug that - will result in these types of error messages. - - MatrixSpaceI.H(492): error: no instance of overloaded function - "Foam::MatrixSpace<Form, Cmpt, Mrows, Ncols>::Block<SubTensor, - BRowStart, BColStart>::operator=" matches the specified type - - ---- -VTK ---- - -If using the runTimePostProcessing to create on-the-fly images, you -can simply just compile ParaView and these libraries will be used. - -If you elect to use a separate VTK compilation (for example for -off-screen rendering), it is advisable to reuse the VTK libraries that -are provided with ParaView by making an appropriate symlink -prior to using makeVTK. This doesn't just reduce disk-space, but works -much better than using the VTK tar file. - -Using runTimePostProcessing with the 'plain' VTK libraries does -generally work, but does not exit cleanly: - - symbol lookup error: .../linux64Gcc/VTK-7.1.0/lib/libvtkCommonExecutionModel-7.1.so.1: - undefined symbol: _ZN33vtkFilteringInformationKeyManager13ClassFinalizeEv - - symbol lookup error: .../linux64Gcc/VTK-7.1.0/lib/libvtkCommonDataModel-7.1.so.1: - undefined symbol: _ZN49vtkInformationQuadratureSchemeDefinitionVectorKeyD1Ev - -This error appears to be suppressed if VTK is compiled with a Debug build-type. - - -------------------------- -Building on older systems -------------------------- - -If the system gcc is too old for building OpenFOAM, a third-party gcc or -clang/llvm installation can be used. If building clang/llvm, note that -there are also minimum gcc/g++ requirements there: - - Min gcc/g++ - =========== ========== - 4.4 llvm-3.4.2 - 4.7 llvm-3.5.2 - llvm-3.7.0 - - -If your system compiler is too old to build the minimum required gcc or -clang/llvm, it is just simply too old. - - ---------------------------------- -ThirdParty clang without gmp/mpfr ---------------------------------- - -If using ThirdParty clang without gmp/mpfr, the ThirdParty makeCGAL -script will need to be run manually and specify that there is no -gmp/mpfr. Eg, - - cd $WM_THIRD_PARTY_DIR - ./makeCGAL gmp-none mpfr-none - -Subequent compilation with Allwmake will now run largely without any -problems, except that the components linking against CGAL -(foamyMesh and surfaceBooleanFeatures) will also try to link against -a nonexistent mpfr library. As a workaround, the link-dependency can -be removed in wmake/rules/General/CGAL : - - CGAL_LIBS = \ - -L$(BOOST_ARCH_PATH)/lib \ - -L$(BOOST_ARCH_PATH)/lib$(WM_COMPILER_LIB_ARCH) \ - -L$(CGAL_ARCH_PATH)/lib \ - -L$(CGAL_ARCH_PATH)/lib$(WM_COMPILER_LIB_ARCH) \ - -lCGAL - -This is a temporary inconvenience until a more robust solution is found. - - -------------------------- -Building with spack -------------------------- - -If you are building with spack, note that the depends_on for paraview -resolves poorly. The +qt dependency (for building the reader module) -may need to be specified as a preference by including the following in -your `~/.spack/packages.yaml` file: - - packages: - paraview: - variants: +qt - -It appears that spack will otherwise ignore any paraview+qt version -and attempt to install a paraview~qt version instead. - --- diff --git a/README.md b/README.md index 163f443c55f..a98a5972931 100644 --- a/README.md +++ b/README.md @@ -33,9 +33,9 @@ Please see the relevant guides: [repo openfoam]: https://develop.openfoam.com/Development/OpenFOAM-plus/ [repo third]: https://develop.openfoam.com/Development/ThirdParty-plus/ -[link openfoam-issues]: https://develop.openfoam.com/Development/OpenFOAM-plus/blob/develop/BuildIssues.txt [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/etc/README.md +[link openfoam-issues]: https://develop.openfoam.com/Development/OpenFOAM-plus/blob/develop/doc/BuildIssues.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 diff --git a/doc/Build.md b/doc/Build.md index 97aafcb5f2f..a59c8e6aa9e 100644 --- a/doc/Build.md +++ b/doc/Build.md @@ -15,7 +15,8 @@ The [third-party][repo third] directory includes a [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. +can be found in the [$WM_PROJECT_DIR/doc/BuildIssues.md][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 @@ -94,10 +95,10 @@ simpleFoam 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. +will often 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. +If you do wish to compile ParaView from source, 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 @@ -123,8 +124,9 @@ More details in the [ThirdParty build guide][link third-build]. [repo openfoam]: https://develop.openfoam.com/Development/OpenFOAM-plus/ [repo third]: https://develop.openfoam.com/Development/ThirdParty-plus/ -[link openfoam-issues]: https://develop.openfoam.com/Development/OpenFOAM-plus/blob/develop/BuildIssues.txt -[link openfoam-config]: https://develop.openfoam.com/Development/OpenFOAM-plus/blob/develop/etc/README.md +[link openfoam-readme]: https://develop.openfoam.com/Development/OpenFOAM-plus/blob/develop/README.md +[link openfoam-issues]: https://develop.openfoam.com/Development/OpenFOAM-plus/blob/develop/doc/BuildIssues.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 diff --git a/doc/BuildIssues.md b/doc/BuildIssues.md new file mode 100644 index 00000000000..a3a4f5d3754 --- /dev/null +++ b/doc/BuildIssues.md @@ -0,0 +1,111 @@ +## Known Build Issues (OpenFOAM-v1906) + +### Intel MPI with Gcc/Clang) + +Either `I_MPI_ROOT` (preferred) or `MPI_ROOT` can be used to specify +the Intel-MPI installation directory path. +The ThirdParty build of ptscotch uses `mpiicc` for Intel-MPI instead +of the usual `mpicc`. When gcc or clang are used, it is quite likely +that the `I_MPI_CC` environment variable also needs to be set +accordingly. +See `mpiicc -help` for more information about environment variables. + + +### VTK + +If using the runTimePostProcessing to create on-the-fly images, you +can simply just compile ParaView and these libraries will be used. +If you elect to use a separate VTK compilation (for example for +off-screen rendering), it is advisable to reuse the VTK libraries that +are provided with ParaView by making an appropriate symlink +prior to using makeVTK. This doesn't just reduce disk-space, but works +much better than using the VTK tar file. + +Using runTimePostProcessing with the *plain* VTK libraries does +generally work, but may not exit cleanly: +``` +symbol lookup error: .../linux64Gcc/VTK-7.1.0/lib/libvtkCommonExecutionModel-7.1.so.1: +undefined symbol: _ZN33vtkFilteringInformationKeyManager13ClassFinalizeEv + +symbol lookup error: .../linux64Gcc/VTK-7.1.0/lib/libvtkCommonDataModel-7.1.so.1: +undefined symbol: _ZN49vtkInformationQuadratureSchemeDefinitionVectorKeyD1Ev +``` + +This error appears to be suppressed if VTK is compiled with a `Debug` build-type. + + +### Building on older systems + +If the system gcc is too old for building OpenFOAM, a third-party gcc or +clang/llvm installation can be used. If building clang/llvm, note that +there are also minimum gcc/g++ requirements as listed in the +detailed [build guide][link third-build]. + +If your system compiler is too old to build the minimum required gcc or +clang/llvm, it is just simply too old. + + +### ThirdParty clang without gmp/mpfr + +If using ThirdParty clang without gmp/mpfr, the ThirdParty makeCGAL +script will need to be run manually and specify that there is no +gmp/mpfr. Eg, +``` +cd $WM_THIRD_PARTY_DIR +./makeCGAL gmp-none mpfr-none +``` + +Subequent compilation with Allwmake will now run largely without any +problems, except that the components linking against CGAL +(foamyMesh and surfaceBooleanFeatures) will also try to link against +a nonexistent mpfr library. As a workaround, the link-dependency can +be removed in wmake/rules/General/CGAL : +``` +CGAL_LIBS = \ + -L$(BOOST_ARCH_PATH)/lib \ + -L$(BOOST_ARCH_PATH)/lib$(WM_COMPILER_LIB_ARCH) \ + -L$(CGAL_ARCH_PATH)/lib \ + -L$(CGAL_ARCH_PATH)/lib$(WM_COMPILER_LIB_ARCH) \ + -lCGAL +``` + +A robuster solution is still being sought. + + +### Building with spack + +If you are building with spack, note that the `depends_on` for paraview +resolves poorly. The `+qt` dependency (for building the reader module) +may need to be specified as a preference by including the following in +your `~/.spack/packages.yaml` file: +``` +packages: + paraview: + variants: +qt +``` +It appears that spack will otherwise ignore any `paraview+qt` version +and attempt to install a `paraview~qt` version instead. + +-- +<!-- Links --> + +[page ParaView]: http://www.paraview.org/ +[download ParaView]: https://www.paraview.org/download/ + + +<!-- OpenFOAM --> + +[repo openfoam]: https://develop.openfoam.com/Development/OpenFOAM-plus/ +[repo third]: https://develop.openfoam.com/Development/ThirdParty-plus/ + +[link openfoam-readme]: https://develop.openfoam.com/Development/OpenFOAM-plus/blob/develop/README.md +[link openfoam-issues]: https://develop.openfoam.com/Development/OpenFOAM-plus/blob/develop/doc/BuildIssues.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 + +--- +Copyright 2019 OpenCFD Ltd diff --git a/etc/README.md b/doc/Config.md similarity index 100% rename from etc/README.md rename to doc/Config.md diff --git a/doc/Requirements.md b/doc/Requirements.md index 5f9be72dae4..a78bbd53ccd 100644 --- a/doc/Requirements.md +++ b/doc/Requirements.md @@ -10,15 +10,21 @@ OpenFOAM requires a functioning C++11 compiler and `make` build toolchain. - fftw: 3.3.7 (recommended - required for FFT-related functionality) - paraview: 5.5.2 (for visualization) +If using the Intel® compiler, `17.0.1 20161005` is the minimum +usable version. + + To check the installed versions | Program | To check the version | |---------------|-----------------------| | gcc | gcc --version | +| icc | icc --version | | cmake | cmake --version | | openmpi | orterun --version | + ### Additional utilities - flex @@ -81,7 +87,6 @@ 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 | @@ -157,7 +162,7 @@ A partial list is given in the [ThirdParty requirements][link third-require]. <!-- OpenFOAM --> [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/etc/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 diff --git a/etc/config.csh/vtk b/etc/config.csh/vtk index dbd5edf90c6..eaabe270314 100644 --- a/etc/config.csh/vtk +++ b/etc/config.csh/vtk @@ -25,7 +25,7 @@ # # It is recommended to use VTK sources from ParaView (5.0.1 or later) # -# See BuildIssues.txt about problems that can be encountered when using +# See doc/BuildIssues.md about problems that can be encountered when using # the 'plain' VTK sources. #------------------------------------------------------------------------------ # USER EDITABLE PART: Changes made here may be lost with the next upgrade diff --git a/etc/config.sh/vtk b/etc/config.sh/vtk index 4815da2435c..38859432d64 100644 --- a/etc/config.sh/vtk +++ b/etc/config.sh/vtk @@ -26,7 +26,7 @@ # # It is recommended to use VTK sources from ParaView (5.0.1 or later) # -# See BuildIssues.txt about problems that can be encountered when using +# See doc/BuildIssues.md about problems that can be encountered when using # the 'plain' VTK sources. #------------------------------------------------------------------------------ # USER EDITABLE PART: Changes made here may be lost with the next upgrade -- GitLab