ENH: improve consistency in version handling for foamEtcFile (issue #1010)

- Prefer the $WM_PROJECT_VERSION from the environment, since this
  is consistent with the foamEtcFile script, and matches better to
  user expectations.

doc/codingStyleGuide.org

@@ -109,17 +109,17 @@
         #+begin_src C++
         //- Search for \em name
         //  in the following hierarchy:
-        //  -# personal settings:
+        //  -# user settings
         //    - ~/.OpenFOAM/\<VERSION\>/
         //      <em>for version-specific files</em>
         //    - ~/.OpenFOAM/
         //      <em>for version-independent files</em>
-        //  -# site-wide settings:
+        //  -# group settings
         //    - $WM_PROJECT_INST_DIR/site/\<VERSION\>
         //      <em>for version-specific files</em>
         //    - $WM_PROJECT_INST_DIR/site/
         //      <em>for version-independent files</em>
-        //  -# shipped settings:
+        //  -# other (shipped) settings
         //    - $WM_PROJECT_DIR/etc/
         //
         //  \return the full path name or fileName() if the name cannot be found

src/OpenFOAM/db/dictionary/functionEntries/includeEtcEntry/includeEtcEntry.H

@@ -3,7 +3,7 @@
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     |
     \\  /    A nd           | Copyright (C) 2015-2016 OpenFOAM Foundation
-     \\/     M anipulation  |
+     \\/     M anipulation  | Copyright (C) 2018 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -25,27 +25,12 @@ Class
     Foam::functionEntries::includeEtcEntry
 
 Description
-    A dictionary directive for including a file found using the findEtcFile()
-    mechanism.
+    A dictionary directive for including a file found using the
+    Foam::findEtcFile() mechanism.
 
     Specify an etc file to include when reading dictionaries, expects a
     single string to follow.
 
-    Searches for files from user/group/shipped directories.
-    The search scheme allows for version-specific and
-    version-independent files using the following hierarchy:
-    - \b user settings:
-      - ~/.OpenFOAM/\<VERSION\>
-      - ~/.OpenFOAM/
-    - \b group (site) settings (when $WM_PROJECT_SITE is set):
-      - $WM_PROJECT_SITE/\<VERSION\>
-      - $WM_PROJECT_SITE
-    - \b group (site) settings (when $WM_PROJECT_SITE is not set):
-      - $WM_PROJECT_INST_DIR/site/\<VERSION\>
-      - $WM_PROJECT_INST_DIR/site/
-    - \b other (shipped) settings:
-      - $WM_PROJECT_DIR/etc/
-
     An example of the \c \#includeEtc directive:
     \verbatim
         #includeEtc "etcFile"

src/OpenFOAM/db/dictionary/functionEntries/includeFuncEntry/includeFuncEntry.H

@@ -28,20 +28,9 @@ Description
     Specify a functionObject dictionary file to include, expects the
     functionObject name to follow with option arguments (without quotes).
 
-    Searches for functionObject dictionary file in user/group/shipped
-    directories allowing for version-specific and version-independent files
-    using the following hierarchy:
-    - \b user settings:
-      - ~/.OpenFOAM/\<VERSION\>/caseDicts/postProcessing
-      - ~/.OpenFOAM/caseDicts/postProcessing
-    - \b group (site) settings (when $WM_PROJECT_SITE is set):
-      - $WM_PROJECT_SITE/\<VERSION\>/caseDicts/postProcessing
-      - $WM_PROJECT_SITE/caseDicts/postProcessing
-    - \b group (site) settings (when $WM_PROJECT_SITE is not set):
-      - $WM_PROJECT_INST_DIR/site/\<VERSION\>/caseDicts/postProcessing
-      - $WM_PROJECT_INST_DIR/site/caseDicts/postProcessing
-    - \b other (project) settings:
-      - $WM_PROJECT_DIR/etc/caseDicts/postProcessing
+    Uses functionObjectList::readFunctionObject() method to search
+    within user/group/other "caseDicts/postProcessing" directories
+    as per Foam::functionObjectList::findDict() and Foam::findEtcFiles()
 
     The optional field arguments included in the name are inserted in 'field' or
     'fields' entries in the functionObject dictionary and included in the name

src/OpenFOAM/db/functionObjects/functionObjectList/functionObjectList.H

@@ -3,7 +3,7 @@
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     |
     \\  /    A nd           | Copyright (C) 2011-2016 OpenFOAM Foundation
-     \\/     M anipulation  | Copyright (C) 2015-2017 OpenCFD Ltd.
+     \\/     M anipulation  | Copyright (C) 2015-2018 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -115,8 +115,8 @@ public:
 
     // Static data members
 
-        //- Default relative path to the directory structure
-        //- containing the functionObject dictionary files
+        //- Default relative path ("caseDicts/postProcessing") to the
+        //- directory structure containing functionObject dictionary files.
         static fileName functionObjectDictPath;
 
 
@@ -189,49 +189,38 @@ public:
         //- Find the ID of a given function object by name
         label findObjectID(const word& name) const;
 
-        //- Print a list of functionObject configuration files in
-        //- user/group/shipped directories.
-        //  The search scheme allows for version-specific and
-        //  version-independent files using the following hierarchy:
-        //  - \b user settings:
-        //    - ~/.OpenFOAM/\<VERSION\>/caseDicts/postProcessing
-        //    - ~/.OpenFOAM/caseDicts/postProcessing
-        //  - \b group (site) settings (when $WM_PROJECT_SITE is set):
-        //    - $WM_PROJECT_SITE/\<VERSION\>/caseDicts/postProcessing
-        //    - $WM_PROJECT_SITE/caseDicts/postProcessing
-        //  - \b group (site) settings (when $WM_PROJECT_SITE is not set):
-        //    - $WM_PROJECT_INST_DIR/site/\<VERSION\>/caseDicts/postProcessing
-        //    - $WM_PROJECT_INST_DIR/site/caseDicts/postProcessing
-        //  - \b other (shipped) settings:
-        //    - $WM_PROJECT_DIR/etc/caseDicts/postProcessing
+        //- Print a list of functionObject configuration files in the
+        //- directories located using
+        //- Foam::findEtcDirs("caseDicts/postProcessing")
+        //
+        //  -# \b user settings
+        //    - ~/.OpenFOAM/$WM_PROJECT_VERSION/"caseDicts/postProcessing"
+        //    - ~/.OpenFOAM/"caseDicts/postProcessing"
+        //  -# \b group settings
+        //    - $WM_PROJECT_SITE/$WM_PROJECT_VERSION/"caseDicts/postProcessing"
+        //    - $WM_PROJECT_SITE/"caseDicts/postProcessing"
+        //  -# \b other (shipped) settings
+        //    - $WM_PROJECT_DIR/etc/"caseDicts/postProcessing"
+        //
+        // See further notes in Foam::findEtcFiles()
         static void list();
 
-        //- Search for functionObject dictionary file in
-        //- user/group/shipped directories.
-        //  The search scheme allows for version-specific and
-        //  version-independent files using the following hierarchy:
-        //  - \b user settings:
-        //    - ~/.OpenFOAM/\<VERSION\>/caseDicts/postProcessing
-        //    - ~/.OpenFOAM/caseDicts/postProcessing
-        //  - \b group (site) settings (when $WM_PROJECT_SITE is set):
-        //    - $WM_PROJECT_SITE/\<VERSION\>/caseDicts/postProcessing
-        //    - $WM_PROJECT_SITE/caseDicts/postProcessing
-        //  - \b group (site) settings (when $WM_PROJECT_SITE is not set):
-        //    - $WM_PROJECT_INST_DIR/site/\<VERSION\>/caseDicts/postProcessing
-        //    - $WM_PROJECT_INST_DIR/site/caseDicts/postProcessing
-        //  - \b other (shipped) settings:
-        //    - $WM_PROJECT_DIR/etc/caseDicts/postProcessing
+        //- Find a functionObject dictionary file in the case
+        //- \<system\> directory or any directory located using
+        //- Foam::findEtcDirs("caseDicts/postProcessing")
         //
-        //  \return The path of the functionObject dictionary file if found
-        //  otherwise an empty path
+        //  \return The path of the functionObject dictionary file found
+        //     or an empty path
         static fileName findDict(const word& funcName);
 
         //- Read the specified functionObject configuration dictionary parsing
-        //  the optional arguments included in the name 'funcNameArgs0',
-        //  inserting 'field' or 'fields' entries as required and merging the
-        //  resulting functionObject dictionary into 'functionsDict'.  Any
-        //  fields required to execute the functionObject are added to
-        //  'requiredFields'
+        //- the optional arguments included in the name 'funcNameArgs0',
+        //- inserting 'field' or 'fields' entries as required and merging the
+        //- resulting functionObject dictionary into 'functionsDict'.  Any
+        //- fields required to execute the functionObject are added to
+        //- 'requiredFields'
+        //
+        //  Uses functionObjectList::findDict() for searching
         static bool readFunctionObject
         (
             const string& funcNameArgs0,

src/OpenFOAM/global/etcFiles/etcFiles.C

@@ -24,8 +24,9 @@ License
 \*---------------------------------------------------------------------------*/
 
 #include "etcFiles.H"
-#include "OSspecific.H"
 #include "foamVersion.H"
+#include "macros.H"
+#include "OSspecific.H"
 
 // * * * * * * * * * * * * * * Static Functions  * * * * * * * * * * * * * * //
 
@@ -64,7 +65,8 @@ static inline bool groupResourceDir(Foam::fileName& queried)
         return Foam::isDir(queried);
     }
 
-    // When WM_PROJECT_SITE is unset:
+    // Fallback when WM_PROJECT_SITE is unset
+
     queried = Foam::getEnv("WM_PROJECT_INST_DIR")/"site";
     return (queried.size() > 4 && Foam::isDir(queried));
 
@@ -96,13 +98,26 @@ Foam::fileNameList searchEtc
     bool (*accept)(const Foam::fileName&)
 )
 {
+    Foam::fileName version(Foam::getEnv("WM_PROJECT_VERSION"));
+
+    // Fallback when WM_PROJECT_VERSION is unset
+    if (version.empty())
+    {
+        #if OPENFOAM
+        version = STRING_QUOTE(OPENFOAM);
+        #else
+        version = foamVersion::version;
+        #endif
+    }
+
     Foam::fileNameList list;
     Foam::fileName dir, candidate;
 
+
     // User resource directories
     if (userResourceDir(dir))
     {
-        candidate = dir/foamVersion::version/name;
+        candidate = dir/version/name;
         if (accept(candidate))
         {
             list.append(std::move(candidate));
@@ -126,7 +141,7 @@ Foam::fileNameList searchEtc
     // Group resource directories
     if (groupResourceDir(dir))
     {
-        candidate = dir/foamVersion::version/name;
+        candidate = dir/version/name;
         if (accept(candidate))
         {
             list.append(std::move(candidate));
@@ -177,7 +192,7 @@ Foam::fileNameList Foam::findEtcDirs
         (
             name,
             findFirst,
-            [](const fileName& f){ return isDir(f); }
+            [](const fileName& f){ return Foam::isDir(f); }
         );
 }
 
@@ -198,7 +213,7 @@ Foam::fileNameList Foam::findEtcFiles
         (
             name,
             findFirst,
-            [](const fileName& f){ return isFile(f); }
+            [](const fileName& f){ return Foam::isFile(f); }
         );
     }
 

src/OpenFOAM/global/etcFiles/etcFiles.H

@@ -3,7 +3,7 @@
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     |
     \\  /    A nd           | Copyright (C) 2016 OpenFOAM Foundation
-     \\/     M anipulation  |
+     \\/     M anipulation  | Copyright (C) 2018 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -45,54 +45,53 @@ namespace Foam
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
 //- Search for directories from user/group/other directories.
-//
-// \note Uses search hierarchy as per findEtcFiles().
+//  Uses search hierarchy as per findEtcFiles().
 //
 //  \return The list of full paths of all the matching directories or
-//  an empty list if the name cannot be found.
-//  Optionally stop search after the first directory has been found.
+//      an empty list if the name cannot be found.
 fileNameList findEtcDirs
 (
-    const fileName& name = fileName::null,
-    const bool findFirst = false
+    const fileName& name=fileName::null, //!< the file to search for
+    const bool findFirst=false  //!< stop when the first file has been found
 );
 
 
 //- Search for files from user/group/other directories.
 //
-//  \note
-//  The following search hierarchy is also used by the foamEtcFile shell
-//  script, which allows for version-specific and version-independent files:
-//  - \b user settings:
-//    - ~/.OpenFOAM/\<VERSION\>
+//  The search hierarchy corresponds to that of the foamEtcFile script,
+//  which allows for version-specific and version-independent files:
+//  -# \b user settings
+//    - ~/.OpenFOAM/$WM_PROJECT_VERSION
 //    - ~/.OpenFOAM/
-//  - \b group settings (when $WM_PROJECT_SITE is set):
-//    - $WM_PROJECT_SITE/\<VERSION\>
-//    - $WM_PROJECT_SITE
-//  - \b group settings (when $WM_PROJECT_SITE is not set):
-//    - $WM_PROJECT_INST_DIR/site/\<VERSION\>
-//    - $WM_PROJECT_INST_DIR/site/
-//  - \b other (shipped) settings:
+//  -# \b group settings
+//    - $WM_PROJECT_SITE/$WM_PROJECT_VERSION
+//    - $WM_PROJECT_SITE/
+//  -# \b other (shipped) settings
 //    - $WM_PROJECT_DIR/etc/
 //
+//  \note Treatment of empty or undefined variables
+//  - \b \$WM_PROJECT_VERSION : Use compile-time value of OPENFOAM
+//  - \b \$WM_PROJECT_SITE : Use $WM_PROJECT_INST_DIR/site
+//
 //  \return The list of full paths of all the matching files or
-//  an empty list if the name cannot be found.
-//  Optionally abort if the file cannot be found.
-//  Optionally stop search after the first file has been found.
+//      an empty list if the name cannot be found.
 fileNameList findEtcFiles
 (
-    const fileName& name,
-    const bool mandatory = false,
-    const bool findFirst = false
+    const fileName& name,       //!< the file to search for
+    const bool mandatory=false, //!< abort if the file cannot be found
+    const bool findFirst=false  //!< stop when the first file has been found
 );
 
 
 //- Search for a single file using findEtcFiles().
 //
 //  \return The full path name of the first file found in the
-//  search hierarchy or an empty fileName if the name cannot be found.
-//  Optionally abort if the file cannot be found but is mandatory.
-fileName findEtcFile(const fileName& name, const bool mandatory=false);
+//      search hierarchy or an empty fileName if the name cannot be found.
+fileName findEtcFile
+(
+    const fileName& name,       //!< the file to search for
+    const bool mandatory=false  //!< abort if the file cannot be found
+);
 
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //