STYLE: update BuildIssues with CGAL mpfr-none problem (issue #674)

- add some notes about 'git submodule' in modules/README.md

BuildIssues.txt

-OpenFOAM-1706
+OpenFOAM-1712
 ==================
 Known Build Issues
 ==================
@@ -75,6 +75,33 @@ 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
 -------------------------

etc/bashrc

@@ -36,7 +36,7 @@ export WM_PROJECT=OpenFOAM
 export WM_PROJECT_VERSION=plus
 
 # [FOAM_INST_DIR] - parent directory containing the OpenFOAM installation.
-#  * When this file is located as $WM_PROJECT_DIR/etc/bashrc, the next lines
+# \- When this file is located as $WM_PROJECT_DIR/etc/bashrc, the next lines
 #    should work when sourced by BASH or ZSH shells. If this however fails,
 #    set one of the fallback values to an appropriate path.
 # --
@@ -104,23 +104,18 @@ export WM_MPLIB=SYSTEMOPENMPI
 
 ################################################################################
 
-# The old dirs to be cleaned from the environment variables
+# Old directories to be cleaned from PATH, LD_LIBRARY_PATH
 foamOldDirs="$WM_PROJECT_DIR $WM_THIRD_PARTY_DIR \
     $HOME/$WM_PROJECT/$USER $FOAM_USER_APPBIN $FOAM_USER_LIBBIN \
     $WM_PROJECT_SITE $FOAM_SITE_APPBIN $FOAM_SITE_LIBBIN"
 
-# Location of installation
-# ~~~~~~~~~~~~~~~~~~~~~~~~
+# Location of installation and third-party software
 export WM_PROJECT_INST_DIR=$FOAM_INST_DIR
 export WM_PROJECT_DIR=$WM_PROJECT_INST_DIR/$WM_PROJECT-$WM_PROJECT_VERSION
-
-# Location of third-party software
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 export WM_THIRD_PARTY_DIR=$WM_PROJECT_INST_DIR/ThirdParty-$WM_PROJECT_VERSION
 
-# Location of site-specific templates etc
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# unset is equivalent to $WM_PROJECT_INST_DIR/site
+# [WM_PROJECT_SITE] - Location of site-specific (group) files
+# default (unset) implies WM_PROJECT_INST_DIR/site
 if [ -d "$WM_PROJECT_SITE" ]
 then
     export WM_PROJECT_SITE
@@ -128,12 +123,10 @@ else
     unset WM_PROJECT_SITE
 fi
 
-# Location of user files
-# ~~~~~~~~~~~~~~~~~~~~~~
+# [WM_PROJECT_USER_DIR] - Location of user files
 export WM_PROJECT_USER_DIR=$HOME/$WM_PROJECT/$USER-$WM_PROJECT_VERSION
 
 # Load shell functions
-# ~~~~~~~~~~~~~~~~~~~~
 . $WM_PROJECT_DIR/etc/config.sh/functions
 
 # Override definitions via prefs, with 'other' first so the sys-admin
@@ -163,35 +156,29 @@ cleaned=$($foamClean "$MANPATH" "$foamOldDirs") && MANPATH="$cleaned"
 export PATH LD_LIBRARY_PATH MANPATH
 
 
-# Source project setup files
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~
+# Setup for OpenFOAM compilation etc
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 _foamEtc config.sh/settings
 
-if /usr/bin/tty -s 2>/dev/null  # Interactive shell
-then
-    _foamEtc config.sh/aliases
-
-    # Bash completions
-    if [ "${BASH_VERSINFO:-0}" -ge 4 ]
-    then
-        _foamEtc config.sh/bash_completion
-    fi
-fi
-
-
-# Source user setup files for optional packages
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# Setup for third-party packages
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 _foamEtc config.sh/mpi
 _foamEtc config.sh/paraview
 _foamEtc config.sh/vtk
 _foamEtc config.sh/ensight
 _foamEtc config.sh/gperftools
-
-#_foamEtc config.sh/ADIOS
+## _foamEtc config.csh/ADIOS
 _foamEtc config.sh/CGAL
 _foamEtc config.sh/scotch
 _foamEtc config.sh/FFTW
 
+# Interactive shell
+if /usr/bin/tty -s 2>/dev/null
+then
+    _foamEtc config.sh/aliases
+    [ "${BASH_VERSINFO:-0}" -ge 4 ] && _foamEtc config.sh/bash_completion
+fi
+
 
 # Clean environment paths again. Only remove duplicates
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -214,13 +201,13 @@ then
 fi
 
 
-# Cleanup environment
-# ~~~~~~~~~~~~~~~~~~~
+# Cleanup temporary information
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-# Functions
+# Unload shell functions
 . $WM_PROJECT_DIR/etc/config.sh/functions
 
-# Variables (do as last for a clean exit code)
+# Variables (done as the last statement for a clean exit code)
 unset cleaned foamClean foamOldDirs
 
 #------------------------------------------------------------------------------

etc/config.csh/settings

@@ -149,15 +149,14 @@ setenv FOAM_LIBBIN $WM_PROJECT_DIR/platforms/$WM_OPTIONS/lib
 # External (ThirdParty) libraries
 setenv FOAM_EXT_LIBBIN $WM_THIRD_PARTY_DIR/platforms/$WM_ARCH$WM_COMPILER$WM_PRECISION_OPTION$WM_LABEL_OPTION/lib
 
-# Site-specific directory
+# Site-specific (group) files
 if ( $?WM_PROJECT_SITE ) then
     set siteDir=$WM_PROJECT_SITE
 else
     set siteDir=$WM_PROJECT_INST_DIR/site
 endif
 
-# Shared site executables/libraries
-# Similar naming convention as ~OpenFOAM expansion
+# Shared site (group) executables/libraries
 setenv FOAM_SITE_APPBIN $siteDir/$WM_PROJECT_VERSION/platforms/$WM_OPTIONS/bin
 setenv FOAM_SITE_LIBBIN $siteDir/$WM_PROJECT_VERSION/platforms/$WM_OPTIONS/lib
 
@@ -165,8 +164,8 @@ setenv FOAM_SITE_LIBBIN $siteDir/$WM_PROJECT_VERSION/platforms/$WM_OPTIONS/lib
 setenv FOAM_USER_APPBIN $WM_PROJECT_USER_DIR/platforms/$WM_OPTIONS/bin
 setenv FOAM_USER_LIBBIN $WM_PROJECT_USER_DIR/platforms/$WM_OPTIONS/lib
 
-# DynamicCode templates
-# - default location is the "~OpenFOAM/codeTemplates/dynamicCode" expansion
+# [FOAM_CODE_TEMPLATES] - dynamicCode templates
+# * fallback == "foamEtcFile -list codeTemplates/dynamicCode"
 # setenv FOAM_CODE_TEMPLATES $WM_PROJECT_DIR/etc/codeTemplates/dynamicCode
 
 # Convenience

etc/config.sh/settings

@@ -133,7 +133,7 @@ export FOAM_LIBBIN=$WM_PROJECT_DIR/platforms/$WM_OPTIONS/lib
 # External (ThirdParty) libraries
 export FOAM_EXT_LIBBIN=$WM_THIRD_PARTY_DIR/platforms/$WM_ARCH$WM_COMPILER$WM_PRECISION_OPTION$WM_LABEL_OPTION/lib
 
-# Site-specific directory
+# Site-specific (group) files
 if [ -n "$WM_PROJECT_SITE" ]
 then
     siteDir=$WM_PROJECT_SITE
@@ -141,8 +141,7 @@ else
     siteDir=$WM_PROJECT_INST_DIR/site
 fi
 
-# Shared site executables/libraries
-# Similar naming convention as ~OpenFOAM expansion
+# Shared site (group) executables/libraries
 export FOAM_SITE_APPBIN=$siteDir/$WM_PROJECT_VERSION/platforms/$WM_OPTIONS/bin
 export FOAM_SITE_LIBBIN=$siteDir/$WM_PROJECT_VERSION/platforms/$WM_OPTIONS/lib
 
@@ -150,8 +149,8 @@ export FOAM_SITE_LIBBIN=$siteDir/$WM_PROJECT_VERSION/platforms/$WM_OPTIONS/lib
 export FOAM_USER_APPBIN=$WM_PROJECT_USER_DIR/platforms/$WM_OPTIONS/bin
 export FOAM_USER_LIBBIN=$WM_PROJECT_USER_DIR/platforms/$WM_OPTIONS/lib
 
-# DynamicCode templates
-# - default location is the "~OpenFOAM/codeTemplates/dynamicCode" expansion
+# [FOAM_CODE_TEMPLATES] - dynamicCode templates
+# * fallback == "foamEtcFile -list codeTemplates/dynamicCode"
 # export FOAM_CODE_TEMPLATES=$WM_PROJECT_DIR/etc/codeTemplates/dynamicCode
 
 # Convenience

etc/cshrc

@@ -36,7 +36,7 @@ setenv WM_PROJECT OpenFOAM
 setenv WM_PROJECT_VERSION plus
 
 # [FOAM_INST_DIR] - parent directory containing the OpenFOAM installation.
-#  * When this file is located as $WM_PROJECT_DIR/etc/cshrc, the next lines
+# \- When this file is located as $WM_PROJECT_DIR/etc/cshrc, the next lines
 #    should work when sourced by CSH or TCSH shells. If this however fails,
 #    set one of the fallback values to an appropriate path.
 # --
@@ -101,7 +101,7 @@ setenv WM_MPLIB SYSTEMOPENMPI
 
 ################################################################################
 
-# The old dirs to be cleaned from the environment variables
+# Old directories to be cleaned from PATH, LD_LIBRARY_PATH
 set foamOldDirs=
 if ( $?WM_PROJECT_DIR ) then
    set foamOldDirs="$foamOldDirs $WM_PROJECT_DIR"
@@ -119,18 +119,13 @@ if ( $?FOAM_SITE_LIBBIN ) then
    set foamOldDirs="$foamOldDirs $FOAM_SITE_LIBBIN"
 endif
 
-# Location of installation
-# ~~~~~~~~~~~~~~~~~~~~~~~~
+# Location of installation and third-party software
 setenv WM_PROJECT_INST_DIR $FOAM_INST_DIR
-setenv WM_PROJECT_DIR $WM_PROJECT_INST_DIR/$WM_PROJECT-$WM_PROJECT_VERSION
+setenv WM_PROJECT_DIR      $WM_PROJECT_INST_DIR/$WM_PROJECT-$WM_PROJECT_VERSION
+setenv WM_THIRD_PARTY_DIR  $WM_PROJECT_INST_DIR/ThirdParty-$WM_PROJECT_VERSION
 
-# Location of third-party software
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-setenv WM_THIRD_PARTY_DIR $WM_PROJECT_INST_DIR/ThirdParty-$WM_PROJECT_VERSION
-
-# Location of site-specific templates etc
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# unset is equivalent to $WM_PROJECT_INST_DIR/site
+# [WM_PROJECT_SITE] - Location of site-specific (group) files
+# default (unset) implies WM_PROJECT_INST_DIR/site
 if ( $?WM_PROJECT_SITE ) then
     set foamOldDirs="$WM_PROJECT_SITE $foamOldDirs"
     if ( ! -d "$WM_PROJECT_SITE" ) unsetenv WM_PROJECT_SITE
@@ -138,8 +133,7 @@ else
     unsetenv WM_PROJECT_SITE
 endif
 
-# Location of user files
-# ~~~~~~~~~~~~~~~~~~~~~~
+# [WM_PROJECT_USER_DIR] - Location of user files
 setenv WM_PROJECT_USER_DIR $HOME/$WM_PROJECT/$LOGNAME-$WM_PROJECT_VERSION
 
 # Source an etc file, possibly with some verbosity
@@ -210,27 +204,26 @@ set cleaned=`$foamClean "$MANPATH" "$foamOldDirs"`
 if ( $status == 0 ) setenv MANPATH $cleaned
 
 
-# Source project setup files
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~
+# Setup for OpenFOAM compilation etc
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 _foamEtc config.csh/settings
 
-if ($?prompt) then  # Interactive shell
-    _foamEtc config.csh/aliases
-    _foamEtc config.csh/tcsh_completion
-endif
-
-
-# Source user setup files for optional packages
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# Setup for third-party packages
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 _foamEtc config.csh/mpi
 _foamEtc config.csh/paraview
 _foamEtc config.csh/vtk
 _foamEtc config.csh/ensight
-
-#_foamEtc config.csh/ADIOS
+## _foamEtc config.csh/ADIOS
 _foamEtc config.csh/CGAL
 _foamEtc config.csh/FFTW
 
+# Interactive shell
+if ($?prompt) then
+    _foamEtc config.csh/aliases
+    _foamEtc config.csh/tcsh_completion
+endif
+
 
 # Clean environment paths again. Only remove duplicates
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -253,12 +246,15 @@ if ( $?LD_PRELOAD ) then
 endif
 
 
-# Cleanup environment
-# ~~~~~~~~~~~~~~~~~~~
-unset cleaned foamClean foamOldDirs
+# Cleanup temporary information
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+# Unload shell "functions"
 unalias _foamEtc
 unalias _foamAddPath
 unalias _foamAddLib
 unalias _foamAddMan
 
+unset cleaned foamClean foamOldDirs
+
 #------------------------------------------------------------------------------

modules/README.md

 OpenFOAM Modules
 ================
 
-This directory is a location to place additional OpenFOAM components
-or tools and have them built as part of the normal OpenFOAM build
+This directory is a location for additional OpenFOAM components or tools
+to placed and have them built as part of the normal OpenFOAM build
 process. It is assumed that each subdirectory contain an appropriate
-Allwmake file, and that they should in all likelihood also build into
+Allwmake file, and that they in all likelihood also build into
 `$FOAM_APPBIN` and `$FOAM_LIBBIN` instead of
 `$FOAM_USER_APPBIN` and `$FOAM_USER_LIBBIN`.
 
-These additional components may be added as git submodules, by script
-or by hand.
+These additional components may be added as [git submodules][man git-submodule],
+by script or by hand.
+
+
+### git
+
+On the first use, it will be necessary to register the submodules:
+
+    git submodule init
+
+
+This will clone the relevant submodules from their respective
+repositories.
+
+
+The following will indicate the current state:
+
+    git submodule status
+
+
+On the first use, or after merging upstream changes in the OpenFOAM
+repository, it will be necessary to update the submodules:
+
+    git submodule update
+
+
+A quick overview of `git submodule` can be in this
+[*blog*][blog git-submodule] with full details in the
+[*manpage*][man git-submodule].
+
+
+An easy way to see which submodules are actually in use:
+
+    `cat .gitmodules`
+
+Which will reveal content resembling the following:
+
+    [submodule "cfmesh"]
+        path = modules/cfmesh
+        url = https://develop.openfoam.com/Community/integration-cfmesh.git
+
+
+### doxygen
 
 To build the doxygen information for the components, it is also
 necessary to link the directories to the doc/ subdirectory.
+This is a purely manual operation.
+
+<!-- General Information -->
+
+[man git-submodule]:  https://git-scm.com/docs/git-submodule
+[blog git-submodule]: http://blog.joncairns.com/2011/10/how-to-use-git-submodules/
+
+---