docs: add and update build/testing documentation (#993)

Author: rem1776

libFMS/BUILD_SYSTEM.md AUTOTOOLS_INSTRUCTIONS.mdlibFMS/BUILD_SYSTEM.md renamed to AUTOTOOLS_INSTRUCTIONS.md

@@ -52,6 +52,9 @@ make install
 ### User configurable options:
 By default, FMS is built without `OpenMP` and in `single precision (r4)`
 
+The 64BIT and 32BIT precision options will build distinct libraries when enabled with the given default
+real size, libfms_r4 or libfms_r8.
+
 The following build options are available:
 ```
 -DOPENMP   "Build FMS with OpenMP support"        DEFAULT: OFF

CMAKE_INSTRUCTIONS.md

@@ -32,6 +32,18 @@ build libFMS without MPI support, pass to `configure` the `--disable-mpi` flag.
 
 ## Supported Build Systems
 
+The FMS repository has two build systems in place, GNU autotools and CMake.
+It is also compiled with the GFDL's internally-developed build tool, [mkmf](https://github.com/noaa-gfdl/mkmf)
+
+CMake and Autotools have some variation in options and the resulting build targets.
+
+Autotools will build with 64 bit real defaults unless configured with `--enable-mixed-mode` in
+which case it will default to 32 bit reals and add overloads to allow for both 32 bit and 64 bit
+operations. This results in one library with both 32 bit and 64 bit routines (defaulting to 32 bit reals).
+
+By default CMake will build the library with 32 bit reals. It also has an option for 64 bit defaults
+, and if enabled will build an additional library with 64 bit reals. This results in distinct 32 bit and 64 bit libraries (libfms_r4.a and libfms_r8.a)
+
 ### GNU Autoconf/Automake
 
 In many cases, running the shell command `./configure && make && make install`

INSTALL.md

@@ -0,0 +1,46 @@
+# Unit Testing
+
+FMS includes a suite of MPI unit tests using the testing infrastructure included in the GNU autotools build system
+in order to check the functionality of the library's modules.
+
+It consists of programs in the test_fms/ directory, with shell scripts to handle directory set up and input files.
+test_lib.sh.in and tap-driver.sh provide additional helper functions used in the scripts and manage output.
+
+### Running the Tests
+
+1. Configure with autotools
+```
+mkdir build # create a build directory in FMS
+autoreconf -if ../configure.ac
+../configure <configure options>
+```
+
+2. Build and run suite
+```
+make check
+```
+This will compile any code not already compiled and then proceed to run the test scripts.
+
+### Debugging Output and Test Options
+
+Setting the environment variable TEST_VERBOSE will direct output to stdout as the test runs, while setting VERBOSE will only output on failure.
+Logs are created for each test as well, with the name \<test script name\>.log in it's corresponding test_fms/ directory.
+
+To run an individual test:
+```
+make check -C test_fms/<test directory> TESTS=<test script name>
+```
+
+SKIP_TESTS can be set to in order to skip specific tests in a script. It uses the script name and test number, and takes ranges as well:
+```
+SKIP_TESTS="test_name.4 test_name.[1-3]"
+```
+
+Some options that effect the test suite can be set by passing options to the ./configure script that creates the makefiles
+for the build system:
+
+-    `--enable-code-coverage` allows for compilation with flags for coverage information.
+     If enabled a coverage report can be generated with `make check-code-coverage`
+-    `--enable-test-input=/path/to/input` turns on test scripts that require input netcdf files (interpolator, xgrid, data_override).
+     This option is mainly used internally and in automated testing since we do not host the input data publicly.
+-    `--with-yaml` compile with yaml input and enable it's associated tests