DOC: relocated OpenFOAM etc/README.md to doc/Config.md

- relocated BuildIssues.txt -> doc/BuildIssues.md

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

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

BuildIssues.txt → doc/BuildIssues.md

-OpenFOAM-1712
-==================
-Known Build Issues
-==================
+## Known Build Issues (OpenFOAM-v1906)
 
----------------------
-Intel MPI (Gcc/Clang)
----------------------
+### Intel MPI with Gcc/Clang)
 
-  Either I_MPI_ROOT or MPI_ROOT can be used to specify the Intel-MPI
-  installation directory path.
+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.
 
-  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
----
+### 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:
+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/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
+```
 
-    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.
 
-This error appears to be suppressed if VTK is compiled with a Debug build-type.
 
-
--------------------------
-Building on older systems
--------------------------
+### 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
-
+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
----------------------------------
+### 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
+```
+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
+```
 
-    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.
+A robuster solution is still being sought.
 
 
--------------------------
-Building with spack
--------------------------
+### 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)
+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.
 
-    packages:
-        paraview:
-            variants: +qt
+--
+<!-- Links -->
 
-It appears that spack will otherwise ignore any paraview+qt version
-and attempt to install a paraview~qt version instead.
+[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

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

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

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