ParmParse: Prefix to FILE (AMReX-Codes#4126)

## Summary

For CI/CD workflows and out-of-source tests we often want to include
dependent inputs files via `FILE = <filename>`. For development, we
prefer to run in temporary run directories but want to avoid having to
copy over the latest inputs file from a source directory (mostly to
avoid confusion between source and copy and to enable rapid development
cycles).

Now, the environment variable `AMREX_INPUTS_FILE_PREFIX` can be set to
prefix every `FILE = <filename>` with a custom path. We will use this in
the CTests integration of WarpX.

## Additional background

CC @EZoni
ECP-WarpX/WarpX#5068

Src/Base/AMReX_ParmParse.H

@@ -60,6 +60,9 @@ class RealVect;
 // '\n's. The "FILE = <filename>" definition is special.  Rather than just
 // adding this entry to the database, it reads the contents of <filename>
 // into the database.
+// For CI/CD workflows and out-of-source tests, the environment variable
+// AMREX_INPUTS_FILE_PREFIX can be set to prefix every FILE = <filename>
+// with a custom path.
 //
 // ParmParse stores all entries in a static table which is built the
 // first time a ParmParse object is constructed (usually in main()).

Src/Base/AMReX_ParmParse.cpp

@@ -9,6 +9,7 @@
 
 #include <algorithm>
 #include <cctype>
+#include <cstdlib>
 #include <iostream>
 #include <limits>
 #include <numeric>
@@ -407,6 +408,19 @@ read_file (const char* fname, ParmParse::Table& tab)
     //
     if ( fname != nullptr && fname[0] != 0 )
     {
+        std::string filename = fname;
+
+        // optional prefix to search files in
+        char const *amrex_inputs_file_prefix_c = std::getenv("AMREX_INPUTS_FILE_PREFIX");
+        if (amrex_inputs_file_prefix_c != nullptr) {
+            // we expect a directory path as the prefix: append a trailing "/" if missing
+            auto amrex_inputs_file_prefix = std::string(amrex_inputs_file_prefix_c);
+            if (amrex_inputs_file_prefix.back() != '/') {
+                amrex_inputs_file_prefix += "/";
+            }
+            filename = amrex_inputs_file_prefix + filename;
+        }
+
 #ifdef AMREX_USE_MPI
         if (ParallelDescriptor::Communicator() == MPI_COMM_NULL)
         {
@@ -415,7 +429,6 @@ read_file (const char* fname, ParmParse::Table& tab)
 #endif
 
         Vector<char> fileCharPtr;
-        std::string filename = fname;
         ParallelDescriptor::ReadAndBcastFile(filename, fileCharPtr);
 
         std::istringstream is(fileCharPtr.data());