ENH: add 'subcommand' handling to wmake (#1693)

- initial split of wmake-related commands into "plumbing" and
  "porcelain" akin to how git handles things.

- wmakeBuildInfo (very low-level), now relocated to the wmake/scripts
  and accessible for the user as "wmake -build-info".

  This satisfies a long-standing desire to access build information
  in a fashion similar to the api/patch information.

CONFIG: avoid git information when building with a debian/ directory

- when a 'debian/' directory exists, there is a high probability that
  the '.git/' directory is from debian and not from OpenFOAM (ie,
  useless here). This corresponds to an implicit '-no-git', which has
  no effect when building from pristine sources.

ENH: wmakeCheckPwd becomes scripts/wmake-check-dir

- accessible for the user as "wmake -check-dir" and with 1 or 2
  directory names. A wmakeCheckPwd symlink left for compatibility.

Allwmake

 #!/bin/sh
 # Run from OPENFOAM top-level directory only
 cd "${0%/*}" || exit
-wmakeCheckPwd "$WM_PROJECT_DIR" 2>/dev/null || {
+wmake -check-dir "$WM_PROJECT_DIR" 2>/dev/null || {
     echo "Error (${0##*/}) : not located in \$WM_PROJECT_DIR"
     echo "    Check your OpenFOAM environment and installation"
     exit 1

META-INFO/README.md

 # META-INFO
 
-Meta-information is for OpenFOAM internal use only.
-
-Do not rely on any files or any file contents in this directory,
-or even the existence of this directory.
+Meta-information is generally for OpenFOAM internal use only.
 
 The format, content and meaning may be changed at anytime without
-notice.
+notice. If any of these are changed, these are some of places that
+will need to be updated accordingly:
 
-The information is provided here for internal documentation purposes.
+  - bin/foamEtcFile
+  - bin/tools/foamConfigurePaths
+  - bin/tools/foamPackRelease
+  - etc/openfoam
+  - wmake/scripts/wmake-build-info
 
 ## api-info
 
 This file and its contents are to be tracked by git.
 
-- File content (api) generated by wmakeBuildInfo from OPENFOAM define
-  in `wmake/rules/General/general`
-
+- File content (api) generated by `wmake -build-info` from the
+  `OPENFOAM` define in `wmake/rules/General/general`
 - File content (patch) is manually generated content.
 
 
 ## build-info
 
-This file is *never* to be tracked by git, but may be present in shipped
-source archives.
+This file is ***never*** to be tracked by git, but may be present in
+shipped source archives.
 
-- File content (branch, build) generated by wmakeBuildInfo from git
-  information and cached from previous wmake (api)
+- File content (branch, build) generated by `wmake -build-info` from
+  git information and cached from previous wmake (api)
 
 
 ## Content types
 
 ### api
 
+Format: `date +%y%m`
+
 - 4-digit year-month (YYMM) integer corresponding to the major
   release or in unusual cases an intermediate release.
-
-- Format is year-month, as per `date +%y%m`.
-  Eg, `1712` for the Dec-2017 release.
+  Example, `1712` for the Dec-2017 release.
 
 
 ### patch
 
+Format: `date +%y%m%d`
+
 - 6-digit year-month-day (YYMMDD) integer corresponding to a patch-level
   for the given **released** API.
-
-- Format is year-month-day, as per `date +%y%m%d`.
-
-- The first release can have a patch value of `0` (unpatched = just
-  released) or a patch value corresponding to the release date.
+- The first release can have a patch value of `0` or `1` which
+  indicates that it is unpatched or just released. Alternatively
+  it can have a patch value corresponding to the release date.
 
 The patch value is only meaningful together with the api value.
 However, for *development* branches, the patch level should not be
-ascribed much meaning -- it can be `0` or have a value corresponding
-to the last merge with a *maintenance* (*eg*, `master`) branch.
+ascribed too much meaning, but will often correspond to the last
+merge with a *maintenance* (*eg*, `master`) branch.
 
 
 ## Flow of information
@@ -70,9 +71,9 @@ distributions to have a record of the same information.
 | build     | git                       | build-info |
 
 
-The command `wmakeBuildInfo -check` is used to determine if
+The command `wmake -build-info -check` is used to determine if
 the saved information needs synchronization. The command
-`wmakeBuildInfo -update` preforms the synchronitzation.
+`wmake -build-info -update` performs the synchronization.
 
 
 ## Notes
@@ -82,4 +83,4 @@ contains more permanent information, whereas the `build-info` is more
 transient in nature.
 
 ----
-2019-01-23
+2020-05-05

README.md

@@ -85,10 +85,10 @@ As can be seen in this example, the git build information is
 supplemented by the date when the last change was authored, which can
 be helpful when the repository contains local changes. If you simply
 wish to know the current API and patch levels directly, the
-`wmakeBuildInfo` script provides the relevant information even
+`wmake -build-info` provides the relevant information even
 when OpenFOAM has not yet been compiled:
 ```
-$ wmakeBuildInfo
+$ wmake -build-info
 make
     api = 1812
     patch = 190531
@@ -207,4 +207,4 @@ ThirdParty directory will contain either an `Allwmake` file or a
 - [Community](http://www.openfoam.com/community/), [Governance](http://www.openfoam.com/governance/)
 - [Contacting OpenCFD](http://www.openfoam.com/contact/)
 
-Copyright 2016-2019 OpenCFD Ltd
+Copyright 2016-2020 OpenCFD Ltd

applications/Allwmake

 #!/bin/sh
 # Run from OPENFOAM applications/ directory only
 cd "${0%/*}" || exit
-wmakeCheckPwd "$WM_PROJECT_DIR/applications" 2>/dev/null || {
+wmake -check-dir "$WM_PROJECT_DIR/applications" 2>/dev/null || {
     echo "Error (${0##*/}) : not located in \$WM_PROJECT_DIR/applications"
     echo "    Check your OpenFOAM environment and installation"
     exit 1

bin/foamEtcFile

@@ -43,9 +43,11 @@
 # Note
 #     This script must exist in the project 'bin' directory
 #
-#     The '-show-api' and '-show-patch' options implement partial logic
-#     from wmake/wmakeBuildInfo.
-#     Make sure that any changes there are also reflected here.
+#     The '-show-api' and '-show-patch' options extract values from
+#     the "META-INFO/api-info" file
+#
+# SeeAlso
+#     META-INFO/README.md for other routines that also use META-INFO.
 #
 #-------------------------------------------------------------------------------
 printHelp() {

bin/tools/foamPackRelease

@@ -264,7 +264,7 @@ patch="$(git --git-dir="$gitbase/.git" show "$sha1" | sed -ne s/patch=//p)"
 
 [ -n "$api" ] || die "Could resolve api value"
 
-# Determine the BUILD information from git, as per wmakeBuildInfo.
+# Determine the BUILD information from git, as per `wmake -build-info`
 build="$(git --git-dir="$gitbase/.git" log -1 --date=short --format='%h=%ad' 2>/dev/null|sed 's/-//g;s/=/-/')"
 
 echo "Detected api, patch, build as '$api', '$patch', '$build'" 1>&2

etc/openfoam

@@ -34,6 +34,9 @@
 #     However, the '-D' options grant more flexibility. For example,
 #         etc/openfoam -DWM_COMPILER=Clang
 #
+# SeeAlso
+#     META-INFO/README.md for other routines that also use META-INFO.
+#
 #------------------------------------------------------------------------------
 # Auto-detect from location. Do not call from within the etc/directory itself!
 projectDir="$(\cd "$(dirname "${0%/*}")" && \pwd -L)"

src/Allwmake

 #!/bin/sh
 # Run from OPENFOAM src/ directory only
 cd "${0%/*}" || exit
-wmakeCheckPwd "$WM_PROJECT_DIR/src" 2>/dev/null || {
+wmake -check-dir "$WM_PROJECT_DIR/src" 2>/dev/null || {
     echo "Error (${0##*/}) : not located in \$WM_PROJECT_DIR/src"
     echo "    Check your OpenFOAM environment and installation"
     exit 1

src/OpenFOAM/Alltouch

@@ -6,11 +6,11 @@ touch=true
 
 case "$1" in
 -check)
-    if wmakeBuildInfo -check
+    if wmake -build-info -check
     then
         unset touch
     fi
-;;
+    ;;
 esac
 
 if [ -n "$touch" ]

wmake/rules/General/version

@@ -4,7 +4,7 @@ SUFFIXES += .Cver
 
 # Update strings in C++ file and in META-INFO files
 Cvertoo = \
-    wmakeBuildInfo -update -filter $< > $(@D)/$(<F).C; \
+    $(WM_SCRIPTS)/wmake-build-info -update -filter $< > $(@D)/$(<F).C; \
     $(CC) $(c++FLAGS) -c $(@D)/$(<F).C -o $@
 
 #------------------------------------------------------------------------------

wmake/scripts/wcleanObjects

@@ -6,11 +6,10 @@
 #   \\  /    A nd           | www.openfoam.com
 #    \\/     M anipulation  |
 #------------------------------------------------------------------------------
-#     Copyright (C) 2017-2018 OpenCFD Ltd.
+#     Copyright (C) 2017-2020 OpenCFD Ltd.
 #------------------------------------------------------------------------------
 # License
-#     This file is part of OpenFOAM, licensed under GNU General Public License
-#     <http://www.gnu.org/licenses/>.
+#     This file is part of OpenFOAM, distributed under GPL-3.0-or-later.
 #
 # Script
 #     wcleanBuild, wcleanPlatform
@@ -88,8 +87,8 @@ done
 
 #------------------------------------------------------------------------------
 # Run from OPENFOAM or THIRDPARTY top-level directory only
-wmakeCheckPwd -q "$WM_PROJECT_DIR"     2>/dev/null || \
-wmakeCheckPwd -q "$WM_THIRD_PARTY_DIR" 2>/dev/null || \
+wmake -check-dir -quiet "$WM_PROJECT_DIR"     2>/dev/null || \
+wmake -check-dir -quiet "$WM_THIRD_PARTY_DIR" 2>/dev/null || \
 {
 cat<<ERROR
 ${0##*/}: Error incorrect top-level directory

wmake/wmakeBuildInfo → wmake/scripts/wmake-build-info

@@ -12,7 +12,8 @@
 #     This file is part of OpenFOAM, distributed under GPL-3.0-or-later.
 #
 # Script
-#     wmakeBuildInfo
+#     wmake/scripts/wmake-build-info
+#     Backend for "wmake -build-info"
 #
 # Description
 #     Print the api/version and other build information for the project.
@@ -22,10 +23,19 @@
 #     - WM_PROJECT_VERSION
 #     - WM_DIR              (unset defaults to WM_PROJECT_DIR/wmake)
 #
+# Files
+#     - META-INFO/{api-info,build-info}
+#     - wmake/rules/General/general
+#     - debian : implicitly disables git queries
+#
 # Note
-#     Partial logic is also implemented in the bin/foamEtcFile
-#     -show-api and -show-patch options.
-#     Make sure that changes here are also reflected there.
+#     When a 'debian/' directory exists, the '.git/' directory is most
+#     likely from debian and not from OpenFOAM (ie, useless here).
+#     This corresponds to an implicit '-no-git', which has no effect
+#     when building from pristine sources.
+#
+# SeeAlso
+#     META-INFO/README.md for other routines that also use META-INFO.
 #
 #------------------------------------------------------------------------------
 # Locations
@@ -33,11 +43,9 @@ rulesFile="${WM_DIR:-$WM_PROJECT_DIR/wmake}/rules/General/general"
 META_INFO="$WM_PROJECT_DIR/META-INFO"
 FOAM_GIT_DIR="$WM_PROJECT_DIR/.git"
 
-usage() {
-    exec 1>&2
-
-    while [ "$#" -ge 1 ]; do echo "$1"; shift; done
+printHelp() {
     cat<<USAGE
+
 Usage: ${0##*/} [OPTION]
        ${0##*/} [-update] -filter FILE
 options:
@@ -56,7 +64,7 @@ options:
   -show-patch   Print patch value from meta-info and exit
   -help         Print the usage
 
-Query/manage status of api,branch,build information.
+Query/manage status of {api,branch,build} information.
 Default without any arguments is the same as '-query-make'.
 
 USAGE
@@ -85,7 +93,7 @@ while [ "$#" -gt 0 ]
 do
     case "$1" in
     -h | -help*)
-        usage
+        printHelp
         ;;
     -cmp | -check)
         optCheck=true
@@ -124,7 +132,7 @@ do
         unset FOAM_GIT_DIR
         ;;
     *)
-        die "unknown option/argument: '$1'"
+        die "Unknown option/argument: '$1'"
         ;;
     esac
     shift
@@ -137,6 +145,11 @@ done
 [ -d "$META_INFO" ] || \
     die "No ${META_INFO##*/}/ directory for project"
 
+# Disable git queries for debian packaging (see notes above)
+if [ -d "$WM_PROJECT_DIR/debian" ]
+then
+    unset FOAM_GIT_DIR
+fi
 
 #------------------------------------------------------------------------------
 
@@ -146,7 +159,7 @@ then
     if [ -f "$META_INFO/build-info" ]
     then
         echo "Removing project ${META_INFO##*/}/build-info" 1>&2
-        rm -f "$META_INFO/build-info" 2>/dev/null
+        rm -f "$META_INFO/build-info"
     else
         echo "Already removed project ${META_INFO##*/}/build-info" 1>&2
     fi

wmake/scripts/wmake-check-dir

+#!/bin/sh
+#------------------------------------------------------------------------------
+# =========                 |
+# \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+#  \\    /   O peration     |
+#   \\  /    A nd           | www.openfoam.com
+#    \\/     M anipulation  |
+#-------------------------------------------------------------------------------
+#     Copyright (C) 2011-2015 OpenFOAM Foundation
+#     Copyright (C) 2020 OpenCFD Ltd.
+#------------------------------------------------------------------------------
+# License
+#     This file is part of OpenFOAM, distributed under GPL-3.0-or-later.
+#
+# Script
+#     wmake/scripts/wmake-check-dir
+#     Backend for "wmake -check-dir"
+#
+#     wmake/wmakeCheckPwd (1912 and earlier)
+#
+# Usage
+#     wmake-check-dir <dir>
+#     wmake-check-dir <dir> <dir2>
+#
+# Description
+#     Check that two directories are identical after resolving the absolute
+#     paths. If only a single directory is specified, check against the
+#     working directory.
+#
+#     Exit status 0 when directories are identical.
+#
+#-------------------------------------------------------------------------------
+printHelp() {
+    cat<<USAGE
+
+Usage: ${0##*/} [OPTION] dir [dir2]
+
+options:
+  -q | -quiet       suppress all normal output
+  -h | -help        display short help and exit
+
+Check that two directories are identical after resolving the absolute paths.
+If only a single directory is specified, check against the working directory.
+
+Exit status 0 when directories are identical
+Exit status 1 on error
+
+USAGE
+    exit 0  # A clean exit
+}
+
+# Report error and exit
+unset optQuiet
+die()
+{
+    if [ -z "$optQuiet" ]
+    then
+        exec 1>&2
+        echo "${0##*/}: $1"
+        shift
+        while [ "$#" -ge 1 ]; do echo "    $1"; shift; done
+    fi
+    exit 1
+}
+
+#------------------------------------------------------------------------------
+
+# Parse options
+while [ "$#" -gt 0 ]
+do
+    case "$1" in
+    -h | -help*)
+        printHelp
+        ;;
+    -q | -quiet | -s | -silent)
+        optQuiet=true
+        ;;
+    --)
+        shift
+        break
+        ;;
+    -*)
+        die "Unknown option: '$1'"  "See '${0##*/} -help' for usage"
+        ;;
+    *)
+        break
+        ;;
+    esac
+    shift
+done
+
+dirName1="${1%/}"
+dirName2="${2%/}"
+
+: "${dirName1:=/}"
+: "${dirName2:=$PWD}"
+
+[ "$#" -eq 1 ] || \
+[ "$#" -eq 2 ] || \
+    die "Expected 1 or 2 arguments, was given $#"
+
+
+# Simple lexical check
+[ "$dirName1" = "$dirName2" ] && exit 0
+
+# Check existence
+[ -d "$dirName1" ] || die "Directory does not exist '$dirName1'"
+
+resolved1="$(cd "$dirName1" 2>/dev/null && pwd -P)"
+if [ "$#" -eq 1 ]
+then
+    resolved2="$(pwd -P)"
+else
+    # Check existence
+    [ -d "$dirName2" ] || die "Directory does not exist '$dirName2'"
+
+    resolved2="$(cd "$dirName2" 2>/dev/null && pwd -P)"
+fi
+
+
+# Compare absolute paths, without symlinks
+if [ "$resolved1" = "$resolved2" ]
+then
+    exit 0
+fi
+
+if [ "$#" -eq 1 ]
+then
+    die "Current directory is not '$dirName1'"
+else
+    die "Directories are different"
+fi
+
+#------------------------------------------------------------------------------

wmake/wclean

@@ -175,15 +175,15 @@ then
                       -name .git -prune -o -type d -print)
     do
         echo "    searching: ${d#./}"
-        find $d -depth -empty -type d -delete -print
+        find "$d" -depth -empty -type d -delete -print
     done
 
     # Second pass: clean up object directories with WM_PROJECT_DIR that don't
     # have respective source code folders, along with the respective binaries
-    if [ "$(expandPath $PWD)" = "$(expandPath $WM_PROJECT_DIR)" ]
-    then
-        objectsDir=$(findObjectDir $PWD 2>/dev/null) || exit 1 # Fatal
 
+    if "$scriptsDir"/wmake-check-dir "$WM_PROJECT_DIR" && \
+        objectsDir=$(findObjectDir . 2>/dev/null)
+    then
         if [ -d "$objectsDir" ]
         then
             echo "    Removing redundant object directories in $objectsDir"

wmake/wmake

@@ -29,8 +29,7 @@
 #     wmake
 #
 # Description
-#     General, wrapped make system for multi-platform development with
-#     support for local and network parallel compilation.
+#     General, wrapped make system for multi-platform development.
 #
 #     Intermediate object and dependency files retain the tree structure
 #     of the original source files, with its location depending on the
@@ -55,24 +54,27 @@
 #
 # See also
 #     wmakeLnInclude, wmakeLnIncludeAll, wmakeCollect, wdep, wrmdep, wrmo,
-#     wclean, wcleanPlatform, wcleanLnIncludeAll
+#     wclean, wcleanLnIncludeAll
 #
 #------------------------------------------------------------------------------
-Script="${0##*/}"           # Use 'Script' for error messages in wmakeFunctions
-. "${0%/*}"/scripts/wmakeFunctions              # Source wmake functions
+Script="${0##*/}"                   # Need 'Script' for wmakeFunctions messages
+scriptsDir="${0%/*}"/scripts        # wmake/scripts directory
+. "$scriptsDir"/wmakeFunctions      # Source wmake functions
 
 printHelp() {
     cat<<HELP_HEAD
 
 Usage: $Script [OPTION] [dir]
        $Script [OPTION] target [dir [MakeDir]]
+       $Script -subcommand ...
+
 options:
-  -s | -silent      Silent mode (does not echo commands)
+  -s | -silent      Silent mode (do not echo commands)
   -a | -all         wmake all sub-directories, running Allwmake if present
   -q | -queue       wmakeCollect sub-directories, running Allwmake if present
   -k | -keep-going  Keep going even when errors occur (-non-stop)
   -j | -jN | -j N   Compile using all or specified N cores/hyperthreads
-  -update           Update lnInclude dirs, dep files, remove deprecated files/dirs
+  -update           Update lnInclude, dep files, remove deprecated files/dirs
 HELP_HEAD
 
 if [ -n "$1" ]
@@ -95,20 +97,36 @@ cat<<HELP_FULL
 HELP_FULL
 fi
 
-cat<<HELP_TAIL_COMMON
+cat<<TAIL_OPTIONS
   -pwd              Print root directory containing a Make/ directory
   -version | --version  Print version (same as -show-api)
   -h | -help        Display short help and exit
   -help-full        Display full help and exit
 
-A general, easy-to-use make system for multi-platform development
-with support for local and network parallel compilation.
+subcommands (wmake subcommand -help for more information):
+TAIL_OPTIONS
+
+if [ -n "$1" ]
+then
+cat<<HELP_SUBCOMMANDS
+  -build-info       Query/manage status of {api,branch,build} information
+  -check-dir        Check directory equality
+HELP_SUBCOMMANDS
+else
+cat<<HELP_SUBCOMMANDS
+  -build-info -check-dir
+HELP_SUBCOMMANDS
+fi
+
+cat<<HELP_TAIL_COMMON
 
+General, wrapped make system for multi-platform development.
 HELP_TAIL_COMMON
 
 if [ -n "$1" ]
 then
 cat<<HELP_TAIL_FULL
+
 Makefile targets:   platforms/linux64GccDPInt32Opt/.../fvMesh.o (for example)
 Special targets:
   all | queue       Same as -all | -queue options
@@ -116,8 +134,8 @@ Special targets:
   lib               Compile statically linked archive lib (.a)
   libo              Compile statically linked lib (.o)
   libso             Compile dynamically linked lib (.so)
-  dep               Compile lnInclude and dependencies only
-  updatedep         Compile dependencies only (in case of broken dependencies)
+  dep               Create lnInclude and dependencies only
+  updatedep         Create dependencies only (in case of broken dependencies)
   objects           Compile but not link
 
 Environment
@@ -126,6 +144,7 @@ Environment
 HELP_TAIL_FULL
 else
 cat<<HELP_TAIL_BRIEF
+
 Some special targets (see -help-full for details):
   all | queue       Same as -all | -queue options
   exe               Executables
@@ -169,7 +188,12 @@ allCores()
 #------------------------------------------------------------------------------
 
 # Default to compiling the local target only
-unset all update optDebug optShow optPrintRootDir
+unset optAll optUpdate optDebug optQuiet optShow optPwd
+
+# Consistency with inherited values
+if [ "$WM_QUIET" = true ]
+then optQuiet=true
+fi
 
 while [ "$#" -gt 0 ]
 do
@@ -180,7 +204,23 @@ do
         -h | -help*) # Short help
             printHelp
             ;;
+
+        # Forward to scripts/wmake-build-info
+        -build-info) shift
+            exec "$scriptsDir/wmake-build-info" "$@"
+            exit $?
+            ;;
+
+        # Forward to scripts/wmake-check-dir
+        # Out of order options: (-quiet)
+        -check-dir) shift
+            exec "$scriptsDir/wmake-check-dir" \
+                ${optQuiet:+-silent} "$@"
+            exit $?
+            ;;
+
         -s | -silent)
+            optQuiet=true
             export WM_QUIET=true
             ;;
         -debug)
@@ -197,10 +237,10 @@ do
             optShow=true
             ;;
         -a | -all | all)
-            all=all
+            optAll=all
             ;;
         -q | -queue | queue)
-            all=queue
+            optAll=queue
             ;;
         # Parallel compilation on all cores (or specified number of cores)
         -j)
@@ -231,7 +271,7 @@ do
             ;;
         # Print root directory containing a Make/ directory and exit
         -pwd)
-            optPrintRootDir=true
+            optPwd=true
             ;;
         # Meant to be used following a pull, this will:
         # - remove dep files that depend on deleted files;
@@ -240,8 +280,8 @@ do
         # - remove empty directories, along with deprecated object directories
         #   and respective binaries.
         -update)
-            update=true
-            : "${all:=all}" # implies 'all', unless previous set to 'queue' etc.