DOC: update modules/README.md and Cross-Compile-mingw information

COMP: provide modules/Allwmake script

- unified entry point with -prefix=... handling (#1721)

doc/Cross-Compile-mingw.md

@@ -23,8 +23,11 @@ mingw64-winpthreads-devel
 
 mingw64-libfftw3
 mingw64-fftw3-devel
+
+mingw64-libz
+mingw64-zlib-devel
 ```
-This setup is missing `zlib`, so download that manually and compile as a
+If the `zlib` (or `libz`) setup does not worksetup, it is possible to download that manually and compile as a
 *static* library.
 ```
 CC="$(wmake -show-c)" CFLAGS="$(wmake -show-cflags)" ./configure --static
@@ -91,15 +94,17 @@ On openSUSE these runtime libraries are provided by the packages:
 ```
 mingw64-libgcc_s_seh1
 mingw64-libstdc++6
+mingw64-libz
 ```
 
 When running, the `WM_PROJECT_DIR` environment must be set.
 OpenFOAM will otherwise not be able to locate its files.
 
 
-## Known limitations (2019-06-24)
+## Known limitations (2020-06-16)
 
 - kahip does not build
+- ptscotch does not build
 - boost should build ok, but no CGAL support (ie, no foamyHexMesh)
 - no ParaView plugin, runTimePostProcessing
 - reacting EulerFoam solvers have too many interdependencies and do

modules/Allwmake

@@ -0,0 +1,43 @@
+#!/bin/sh
+cd "${0%/*}" || exit                            # Run from this directory
+targetType=libso
+. "${WM_PROJECT_DIR:?}"/wmake/scripts/AllwmakeParseArguments
+
+#------------------------------------------------------------------------------
+# Default build into OpenFOAM project locations unless specified with
+# -prefix or FOAM_MODULE_PREFIX env varable
+
+: "${FOAM_MODULE_PREFIX:=${FOAM_LIBBIN%/*}}"
+export FOAM_MODULE_PREFIX
+
+
+#------------------------------------------------------------------------------
+
+# Skip some directory names
+filterDir() {
+    case "$1" in
+    (build | platforms | doc)
+        echo ""
+        ;;
+    (*)
+        echo "$1"
+        ;;
+    esac
+}
+
+
+# Build each first-level directory with an Allwmake* file
+for moduleName in \
+    $(find . -mindepth 2 -maxdepth 2 -name 'Allwmake*' -print | \
+      sed -e 's@^\./@@; s@/.*$@@;' | sort | uniq)
+do
+    moduleName="$(filterDir "$moduleName")"
+
+    if [ -d "$moduleName" ]
+    then
+        ( cd "$moduleName" && wmake -all $targetType )
+    fi
+done
+
+
+#------------------------------------------------------------------------------

modules/README.md

@@ -1,28 +1,40 @@
 ## OpenFOAM Modules
 
-This directory is a location for additional OpenFOAM components or tools
+This directory is a location for additional OpenFOAM components or
-to placed and have them built as part of the normal OpenFOAM build
+tools to placed and have them built as part of the normal OpenFOAM
-process. It is assumed that each subdirectory contain an appropriate
+build process. It is assumed that each subdirectory contain an
-Allwmake file, and that they in all likelihood also build into
+appropriate `Allwmake` (or `Allwmake.override`) file.
-`$FOAM_APPBIN` and `$FOAM_LIBBIN` instead of
+
-`$FOAM_USER_APPBIN` and `$FOAM_USER_LIBBIN`.
+
+### Build locations
+
+Any individual _module_ will normally also be able to exist outside of
+the module directory structure and will typically build into user
+locations (`$FOAM_USER_APPBIN` and/or `$FOAM_USER_LIBBIN`).
+
+When compiled from the top-level OpenFOAM `Allwmake` or the
+`modules/Allwmake`, they should build into OpenFOAM project locations
+(`$FOAM_APPBIN` and/or `$FOAM_LIBBIN`). This can be adjusted by
+supplying an alternative `-prefix=` to the corresponding Allwmake
+command.
+
+
+### Adding additional components
 
 These additional components may be added as [git submodules][man git-submodule],
 by script or by hand.
 
 
-### git
+#### 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
@@ -46,20 +58,60 @@ cat .gitmodules
 
 Which will reveal content resembling the following:
 ```
-[submodule "catalyst"]
+[submodule "avalanche"]
-    path = modules/catalyst
+    path = modules/avalanche
-    url = https://develop.openfoam.com/Community/catalyst.git
+    url = https://develop.openfoam.com/Community/avalanche.git
 [submodule "cfmesh"]
     path = modules/cfmesh
     url = https://develop.openfoam.com/Community/integration-cfmesh.git
+...
 ```
 
-### doxygen
+### Documentation (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.
 
+
+### Developer Information
+
+#### Build locations
+
+To accomodate building into various locations, the module code should
+be adapted with the following changes:
+
+- ***Make/files***
+   ```
+   ...
+   EXE = $(FOAM_MODULE_APPBIN)/someExecutable
+
+   LIB = $(FOAM_MODULE_LIBBIN)/libSomeLibrary
+   ```
+
+- `Make/options` should include this
+  ```
+  include $(GENERAL_RULES)/module-path-user
+  ...
+  ```
+
+The following changes to `Make/options` are universally applicable
+(ie, work with older or other versions of OpenFOAM), but more verbose.
+
+- `Make/options` with the following
+  ```
+  sinclude $(GENERAL_RULES)/module-path-user
+
+  /* Failsafe - user locations */
+  ifeq (,$(FOAM_MODULE_APPBIN))
+  FOAM_MODULE_APPBIN = $(FOAM_USER_APPBIN)
+  endif
+  ifeq (,$(FOAM_MODULE_LIBBIN))
+  FOAM_MODULE_LIBBIN = $(FOAM_USER_LIBBIN)
+  endif
+  ...
+  ```
+
 <!-- General Information -->
 
 [man git-submodule]:  https://git-scm.com/docs/git-submodule

modules/doc/Allwmake

@@ -1,6 +1,6 @@
 #!/bin/sh
 # Dummy for "wmake -all"
-# Returns true so it does look like an error
+# Returns true so it does not look like an error
 
 echo "skip wmake target for modules doxygen directory"