- call also be used non-interactively for simple 'one-shot' use of
  OpenFOAM utilities or solvers

STYLE: use dash instead of brackets for '- see www.OpenFOAM.com'

- less cluttered in combination with API information

- makes the standard config variables more visible

- add a '-SPDP' option

- remove the '-archOption' for forcing a '-m32' build on 64-bit
  architecture, which is now considered too obscure.
  Must edit files manually if this option is really required.

- now only needed when specify compiling -m32 on a 64-bit system.

  Internally use the __SIZEOF_LONG__ compiler macro (gcc, icc, llvm)
  to define when long is actually an int32_t.

- add vsmall pTraits for scalars
- report the solve scalar in buildArch information

- in addition to managing different vendors and versions, it may also
  be necessary or desirable to have a particular variant
  (eg, profiling, release, etc).

  Devise a new meaningful name for the variant and create a
  corresponding wmake rule.

  Eg, SYSTEMOPENMPI-profiling with a corresponding
      "wmake/rules/linux64Gcc/mplibSYSTEMOPENMPI-profiling" file
  that has suitable content for your system.

CONFIG: intel-mpi use intel64/ paths only for config and wmake rules (#1153)

- previously adjusted the config files, but missed the changes
  required for the wmake rules too.

  Now simply migrate to using  "intel64/{include,bin,lib}"
  instead of the older naming  "{include,bin,lib}64"

  These changes work since at least intel-mpi 2015 (5.x), but possibly
  earlier as well

- was WM_PROJECT_API in the environment and FOAM_API in dictionaries.

  Make these both consistently FOAM_API.
  This is a non-breaking change, since the value of WM_PROJECT_API
  (added in 1812) and/or FOAM_API is purely informative.
  For the current correct values, always use

    * foamEtcFile -show-api
    * wmakeBuildInfo -show-api

- instead of

      WM_COMPILER=GccKNL WM_COMPILE_OPTION=Opt

      -> linux64GccKNLDPInt32Opt

  now specify

      WM_COMPILER=Gcc  WM_COMPILE_OPTION=OptKNL

      -> linux64GccDPInt32OptKNL

This makes it easier (and more obvious) for adding different tweaks
without needing to generate too many files.
Eg,

    cd wmake/rules/linux64Gcc

    cp cOpt   cOptBdw
    cp c++Opt c++OptBdw

    edit these two files and then use WM_COMPILE_OPTION=OptBdw

CONFIG: provide some default c/c++ flags in General compiler rules

- can make is easier when deriving new compile options, and ensures
  that '-02' is enabled as an initial default.

- was WM_PROJECT_API in the environment and FOAM_API in dictionaries.

  Make these both consistently FOAM_API.
  This is a non-breaking change, since the value of WM_PROJECT_API
  (added in 1812) and/or FOAM_API is purely informative.
  For the current correct values, always use

    * foamEtcFile -show-api
    * wmakeBuildInfo -show-api

- the result of lsof, which is used in the etc/cshrc to locate the
  installation, may contain trailing information about host and mount
  point.

  There is also a moderate concern with people sourcing the
  file indirectly with their own version in the same directory.
  For example, a 'etc/cshrc-site' that actually sources 'etc/cshrc'.
  This leads to multiple matches in the lsof output, so we only take
  the first one, stop there and hope they didn't do something even
  trickier.

- provide default WM_DIR if not already set, to improve robustness if a
  reduced environment is used

- add etc/ to WM_PROJECT_SITE search. This makes the site directory
  structure consistent with the OpenFOAM structure.
  Eg,

      WM_PROJECT_SITE/etc/..
      WM_PROJECT_SITE/bin/..
      WM_PROJECT_SITE/platforms/..

- Don't set/export WM_OSTYPE.  The default is POSIX and is properly
  defaulted throughout, including in CMakeLists-OpenFOAM.txt (also for
  Catalyst)

- Use the OPENFOAM define (eg, 1806, 1812), which normally corresponds
  to a major release, to define an API level. This remains consistent
  within a release cycle and means that it is possible to manage
  several sub-versions and continue to have a consistent lookup.

  The current API value is updated automatically during the build
  and cached as meta data for later use, even when the wmake/ directory
  is missing or OpenFOAM has not yet be initialized.

  The version information reported on program start or with -help
  usage adjusted to reflect this. The build tag from git now also
  carries the date as being more meaningful to trace than a hash
  value.

- Update etc/bashrc and etc/cshrc to obtain the project directory
  directly instead of via its prefix directory. The value obtained
  corresponds to an absolute path, from which the prefix directory
  can be obtained.

  The combination of these changes removes the reliance on any
  particular directory naming convention.
  For example,

     With an 1812 version (API level):

     WM_PROJECT_VERSION=myVersion

     installed as /some/path/somewhere/openfoam-mySandbox

  This makes the -prefix, -foamInstall, -projectVersion, -version
  values of foamEtcFiles, and similar entries for foamConfigurePaths
  superfluous.

  WM_PROJECT_INST_DIR is no longer required or used

ENH: improve handling and discovery of ThirdParty

- improve the flexibility and reusability of ThirdParty packs to cover
  various standard use cases:

    1. Unpacking initial release tar files with two parallel directories
       - OpenFOAM-v1812/
       - ThirdParty-v1812/

    2. With an adjusted OpenFOAM directory name, for whatever reason
       - OpenFOAM-v1812-myCustom/
       - openfoam-1812-other-info/

    3. Operating with/without ThirdParty directory

  To handle these use cases, the following discovery is used.

  Note PROJECT = the OpenFOAM directory `$WM_PROJECT_DIR`
       PREFIX = the parent directory
       VERSION = `$WM_PROJECT_VERSION`
       API = `$WM_PROJECT_API`, as per `foamEtcFiles -show-api`

   0. PROJECT/ThirdParty
      - for single-directory installations

   1. PREFIX/ThirdParty-VERSION
      - this corresponds to the traditional approach

   2. PREFIX/ThirdParty-vAPI
      - allows for an updated value of VERSION (eg, v1812-myCustom)
        without requiring a renamed ThirdParty. The API value
        would still be '1812' and the original ThirdParty-v1812/
        would be found.

   3. PREFIX/ThirdParty-API
      - this is the same as the previous example, but using an unadorned
        API value. This also makes sense if the chosen version name also
        uses the unadorned API value in its naming
        (eg, 1812-patch190131, 1812.19W03)

   4. PREFIX/ThirdParty-common
      - permits maximum reuse for various versions, but only for
        experienced user who are aware of potential version
        incompatibilities

   Directory existence is checked as is the presence of an Allwmake file
   or a platforms/ directory. This reduces the potential of false positive
   matches and limits the selection to directories that are either
   with sources (has the Allwmake file), or pre-compiled binaries (has
   the platforms/ directory).

   If none of the explored directories are found to be suitable,
   it reverts to using a PROJECT/ThirdParty dummy location since
   this is within the project source tree and can be trusted to
   have no negative side-effects.

ENH: add csh support to foamConfigurePaths

- this removes the previously experienced inconsistence in config file
  contents.

REMOVED: foamExec

- was previously used when switching versions and before the
  bashrc/cshrc discovery logic was added. It is now obsolete.

- was PREFIX/site, now PROJECT/site

  This avoids several issues when installing OpenFOAM in clusters
  without an intermediate OpenFOAM-specific installation prefix.

  The 'site' directory may have a reserved meaning in these situations
  and it is undesirable to 'leak' upwards into the parent directory to
  look for configuration files.

  Placing the default within the project directory avoids this.
  Alternative locations can be given via the WM_PROJECT_SITE variable.

- comments in bashrc, cshrc.
- about controlDict names for allowSystemOperations

- since 1612, FOAM_INST_DIR and foamInstDir longer have any
  special meanings when sourcing the bashrc or cshrc files.
  Thus no need for special treatment in any of the dispatch wrappers.

  Retained FOAM_INST_DIR as (unexported) variable in etc/bashrc,
  just in case people are using patched versions of etc/bashrc
  as part of their installation.

ENH: relax prefix restrictions on foamCreateVideo (issue #904)

- shift the implicit '.' to be part of the default prefix. This allows
  things like "-image myimages_00" to work as might be expected.

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

- adjust comment formatting to reduce clutter

- relocate WM_COMPILER_ARCH, WM_COMPILER_LIB_ARCH from
  etc/{bashrc,cshrc} to etc/config.{csh,sh}/settings since these
  should not be changed by the user anyhow.

- Use gcc/g++ as common base and specialize afterwards (to reduce
  duplication)

- adjust format of WM_PROJECT_SITE fallback to allow for easier
  automated edits

- easier to ensure that flags are consistent

- primary points for an external user are the polyMesh constructor

- add config info for gcc-7.3.0

COMP: intel-2017. Ignore unknown pragmas. Disambiguate method resolution.

- forward command-line arguments for paraview, where they may also be
  evaluated (cshrc, POSIX shell)
  Eg,
      . etc/bashrc ParaView_VERSION=5.4.1-mpipy
      source etc/cshrc ParaView_VERSION=5.4.1-mpipy

- export library path for gmp/mpfr from CGAL config files.
  This is required when non-system gmp/mpfr libraries are being
  used, but not using a ThirdParty compiler installation.

- automatically handle lib/ vs lib64/ (eg, for central installations)
  for packages such as boost, CGAL, etc. While the ThirdParty
  compilation of these will normally land in lib64/, this may not be
  the case when they are supplied by another means.

- reworked the handling of foamEtcFile and foamCleanPath for less
  clutter in the configuration files.
  Added the bin/tools/lib-dir script to handle logic that is
  too complex to easily manage in csh.

- FOAM_CONFIG_NOUSER
  Suppress use of user/group configuration files.
  This is useful when packaging for a central installation.

- allow additional user tuning of compiler settings.
  Per-compiler overrides in "compiler-$WM_COMPILER" files