chore: reorg dirs; rm dead code; document runtimes

This commit
1. Reorganizes and renames subdirectories to clarify the
   categories of code stored in each subdirectory.
2. Adds src/README.md to clarify that MPI is the only supported
   communication library and to explain the historical reasons
   for keeping the unsupported GASNet and OpenSHMEM runtimes.
3. Removes many of the unmaintained static Makefiles, including
   those that were used to build the unsupported runtimes.
4. Removes dead code in the opencoarrays.F90 module, retaining only
   the code that is useful for archival purposes because it is used
   in a publication at https://doi.org/10.1145/3144779.3169110.
5. Updates the build system where necessitateed by the above edits.

Author: rouson

CMakeLists.txt

@@ -697,7 +697,7 @@ add_custom_target( hash_installed
 #---------------------------------------------------------------------------------------
 # Define macro for adding CAF tests, and ensuring proper flags are passed to MPI runtime
 #---------------------------------------------------------------------------------------
-# Test for OpenMPI moved to src/mpi/CMakeLists.txt and passed back up through set(... PARENT_SCOPE)
+# Test for OpenMPI moved to src/runtime-libraries/mpi/CMakeLists.txt and passed back up through set(... PARENT_SCOPE)
 function(add_caf_test name num_caf_img test_target)
   # Function to add MPI tests.
   if(TARGET ${test_target})

install.sh

@@ -81,7 +81,7 @@
 
 ### Start of boilerplate -- do not edit this block #######################
 export OPENCOARRAYS_SRC_DIR="${OPENCOARRAYS_SRC_DIR:-${PWD%/}}"
-if [[ ! -f "${OPENCOARRAYS_SRC_DIR}/src/libcaf.h" ]]; then
+if [[ ! -f "${OPENCOARRAYS_SRC_DIR}/src/runtime-libraries/mpi/mpi_caf.c" ]]; then
   echo "Please run this script inside the top-level OpenCoarrays source directory or "
   echo "set OPENCOARRAYS_SRC_DIR to the OpenCoarrays source directory path."
   exit 1
@@ -332,6 +332,7 @@ elif [[ "${arg_p:-}" == "opencoarrays" ]]; then
     fi
   fi
 
+
 elif [[ "${arg_p:-}" == "ofp" ]]; then
 
   # Install Xcode command line tools (CLT) if on macOS and if needed

prerequisites/build.sh

@@ -32,7 +32,7 @@
 
 export OPENCOARRAYS_SRC_DIR="${OPENCOARRAYS_SRC_DIR:-${PWD%prerequisites*}}"
 export __usage=${OPENCOARRAYS_SRC_DIR}/prerequisites/build.sh-usage
-if [[ ! -f "${OPENCOARRAYS_SRC_DIR}/src/libcaf.h" ]]; then
+if [[ ! -f "${OPENCOARRAYS_SRC_DIR}/src/runtime-libraries/mpi/mpi_caf.c" ]]; then
   echo "Please run this script inside the OpenCoarrays source \"prerequisites\" subdirectory"
   echo "or set OPENCOARRAYS_SRC_DIR to the top-level OpenCoarrays source directory path."
   exit 1

src/CMakeLists.txt

@@ -1,15 +1,10 @@
-set(directories_to_build mpi tests)
-foreach(directory ${directories_to_build})
-  add_subdirectory(${directory})
-endforeach()
+add_subdirectory(application-binary-interface )
+add_subdirectory(runtime-libraries )
+add_subdirectory(tests)
 
 set(N_CPU ${N_CPU} PARENT_SCOPE)
 set(HOST_NAME ${HOST_NAME} PARENT_SCOPE)
 
 if(openmpi)
   set(openmpi ${openmpi} PARENT_SCOPE)
 endif()
-
-install( FILES libcaf.h libcaf-gfortran-descriptor.h libcaf-version-def.h
-  DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
-)

src/README.md

@@ -0,0 +1,21 @@
+OpenCoarrays Runtime Libraries
+==============================
+
+One original goal of the OpenCoarrays project was to provide a transparent application binary interface (ABI) supported by interchangeable parallel runtime libraries based on a range of communication libraries.  The following header files in this directory define that ABI:
+
+* libcaf.h
+* libcaf-gfortran-descriptor.h
+* libcaf-version-def.h: 
+
+where the above files are in dependency order: each file depends on the file(s) listed below it.  The [runtime-libraries](./runtime-libraries) subdirectory contains runtimes based on the following communication libraries:
+
+* Message Passing Interface (MPI)
+* OpenSHMEM
+* GASNet
+
+We currently maintain, build, and test only the MPI runtime.  The GASNet and OpenSHMEM runtime library source code serve only to provide detailed, open-source documentation of the research described by [Fanfarillo et al. (2014)] and [Rouson et al. (2017)].  For a Fortran 2018 parallel runtime library based on the more recent GASNet-EX exascale networking middleware described by [Bonachea and Hargrove (2018)], please see the [Caffeine] repository.
+
+[Fanfarillo et al. (2014)]: http://dx.doi.org/10.1145/2676870.2676876
+[Rouson et al. (2017)]: https://doi.org/10.1145/3144779.3169104
+[Bonachea and Hargrove (2018)]: https://doi.org/10.1007/978-3-030-34627-0_11
+[Caffeine]: https://go.lbl.gov/caffeine

src/application-binary-interface/CMakeLists.txt

@@ -0,0 +1,3 @@
+install( FILES libcaf.h libcaf-gfortran-descriptor.h libcaf-version-def.h
+  DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
+)