ENH: support alternative build-root location (#2286)

- specify any of these

    ./Allwmake -build-root=...
    wmake -build-root=...
    FOAM_BUILDROOT=... wmake

  these specify an alternative root where build artifacts are to land.
  Currently only used as an alternative for the 'build/' hierarchy
  since the 'platforms/' target normally includes inputs as well.

  Possible use:
  ```
  (
      export WM_MPLIB="%{foam_mplib}"
      export FOAM_MPI="%{foam_mpi}"
      export MPI_ARCH_PATH="%{mpi_prefix}"

      export FOAM_BUILDROOT=/tmp/mpibuild
      export FOAM_MPI_LIBBIN="$FOAM_BUILDROOT/platforms/$WM_OPTIONS/lib/$FOAM_MPI"

      src/Pstream/Allwmake-mpi
   )
   ```

wmake/scripts/AllwmakeParseArguments

@@ -6,7 +6,7 @@
 #    \\/     M anipulation  |
 #------------------------------------------------------------------------------
 #     Copyright (C) 2014-2017 OpenFOAM Foundation
-#     Copyright (C) 2019-2020 OpenCFD Ltd.
+#     Copyright (C) 2019-2021 OpenCFD Ltd.
 #------------------------------------------------------------------------------
 # License
 #     This file is part of OpenFOAM, distributed under GPL-3.0-or-later.
@@ -28,6 +28,8 @@
 # Parsed options (wmake)
 #     -debug
 #     -q | -queue
+#     -build-root=...
+#         Exports FOAM_BUILDROOT value.
 #     -module-prefix=...
 #         Exports FOAM_MODULE_PREFIX value.
 #         Unsets FOAM_MODULE_APPBIN, FOAM_MODULE_LIBBIN.
@@ -107,6 +109,13 @@ do
         # Pass onwards to other Allwmake scripts
         ;;
 
+    -build-root=*)
+        # Alternative location for build intermediates
+        export FOAM_BUILDROOT="${arg#*=}"
+        echo "Build-root = ${FOAM_BUILDROOT:-[]}" 1>&2
+        continue    # Argument handled, remove it
+        ;;
+
     -module-prefix=* | -prefix=* | --prefix=*)
         # As per setModulePrefix (wmakeFunctions)
         export FOAM_MODULE_PREFIX="${arg#*=}"

wmake/scripts/wmakeFunctions

@@ -214,7 +214,7 @@ cdSource()
 # - the objectsDir
 #
 # Global variables used:
-# - WM_PROJECT_DIR, WM_OPTIONS
+# - FOAM_BUILDROOT, WM_PROJECT_DIR, WM_OPTIONS
 findObjectDir()
 {
     local project="$(expandPath "$WM_PROJECT_DIR")"
@@ -225,8 +225,13 @@ findObjectDir()
     relativeDir="${absdir#${project}/}"
     if [ "$relativeDir" != "$absdir" ]
     then
-        [ -w "$WM_PROJECT_DIR" ] && \
+        if [ -n "$FOAM_BUILDROOT" ] && [ -w "$FOAM_BUILDROOT" ]
+        then
+            objectsDir="${FOAM_BUILDROOT}/build/${WM_OPTIONS}/${relativeDir}"
+        elif [ -w "$WM_PROJECT_DIR" ]
+        then
             objectsDir="${WM_PROJECT_DIR}/build/${WM_OPTIONS}/${relativeDir}"
+        fi
     fi
 
     # Default (local) build directory

wmake/wmake

@@ -37,6 +37,7 @@
 #     3. (OR) descend into each sub-directory and repeat.
 #
 # Environment
+#     FOAM_BUILDROOT
 #     FOAM_EXTRA_CFLAGS FOAM_EXTRA_CXXFLAGS FOAM_EXTRA_LDFLAGS
 #     FOAM_MODULE_PREFIX
 #
@@ -69,6 +70,7 @@ if [ -n "$1" ]
 then
 cat<<HELP_FULL
   -debug            Define c++DBUG='-DFULLDEBUG -g' as override
+  -build-root=PATH  Specify FOAM_BUILDROOT for compilation intermediates
   -module-prefix=PATH   Specify FOAM_MODULE_PREFIX as absolute/relative path
   -module-prefix=TYPE   Specify FOAM_MODULE_PREFIX as predefined type
                         (u,user | g,group | o,openfoam)
@@ -250,6 +252,11 @@ do
             optDebug=true
             ;;
 
+        -build-root=*)
+            export FOAM_BUILDROOT="${1#*=}"
+            echo "Build-root = ${FOAM_BUILDROOT:-[]}" 1>&2
+            ;;
+
         -module-prefix=*)
             setModulePrefix "${1#*=}"
             ;;
@@ -599,15 +606,20 @@ fi
 # files and options being built in parallel
 #------------------------------------------------------------------------------
 
-# Mini-version of findObjectDir
+# Mini-version of findObjectDir (from wmakeFunctions)
 unset objectsDir
 
-# Handle project/{applications,src} as out-of-source build
+# Handle project/{applications,src} as out-of-source build.
 relativeDir="${PWD#${WM_PROJECT_DIR}/}"
 if [ "$relativeDir" != "$PWD" ]
 then
-    [ -w "$WM_PROJECT_DIR" ] && \
+    if [ -n "$FOAM_BUILDROOT" ] && [ -w "$FOAM_BUILDROOT" ]
+    then
+        objectsDir="${FOAM_BUILDROOT}/build/${WM_OPTIONS}/${relativeDir}"
+    elif [ -w "$WM_PROJECT_DIR" ]
+    then
         objectsDir="${WM_PROJECT_DIR}/build/${WM_OPTIONS}/${relativeDir}"
+    fi
 fi
 
 # Default (local) build directory