tools/README.testing				May/23/2011

There is automated testing for all of the tools and scripts under this tools directory.
The tests are in the test/tools directory and are any of the scripts
that have "tools" in the name. There are several assumptions made in order for the 
testing to work.


1.) Executable name is the same as the directory name

The name of the executable program is the same as the directory name of the tool.

2.) Build works the same for any Fortran tools

The build for any Fortran tools should work the same way, with the same options
and required files for it. The files: Makefile, Mkdepends, Filepath and Srcfile
are expected to exist in the tool "src" sub-directory. To make maintaining these files easier
in general the Makefile and Mkdepends files should be kept identical other than
default settings for OPT and SMP and the output executable name.

Options to the Makefile:

 LIB_NETCDF --- Library directory location of NetCDF. (defaults to /usr/local/lib)
 INC_NETCDF --- Include directory location of NetCDF. (defaults to /usr/local/include)
 MOD_NETCDF --- Module directory location of NetCDF.  (defaults to $LIB_NETCDF)
 USER_FC ------ Allow user to override the default Fortran compiler specified in Makefile.
 USER_FCTYP --- Allow user to override the default type of Fortran compiler 
                (Linux and USER_FC=ftn only).
 USER_CC ------ Allow user to override the default C compiler specified in Makefile
                (Linux only).
 USER_LINKER -- Allow user to override the default linker specified in Makefile.
 SMP ---------- Shared memory Multi-processing (TRUE or FALSE) [default is FALSE]
 OPT ---------- Use optimized options. (TRUE or FALSE)

3.) Successful completion of the tool ends with "Successfully ..."

After the tool completes it should have an unique string telling of the 
successful completion of the file that is searchable in the log file starting
with "Successfully ". If this string isn't found in the log file, it
will be assumed by the test setup that the test failed.

4.) NetCDF files are created or modified

It is assumed that NetCDF files are created and/or modified by the process. And if
NetCDF files are NOT created -- something went wrong. For some scripts that copy files
to other locations this means an "-nomv" option needs to be invoked (and one provided)
so that it leaves the files created in the current directory.

5.) Namelist examples exist <toolname>.* namelist files

To specify options for the running of the tool, sample namelist files
are provided or a sample run options file. These files can EITHER be in the 
tool directory OR the ../../test/tools/nl_files directory.

6.) Specific tests for run scripts

For tools that have scripts to create namelists and run the tool for you, there
are customized tests to run these tools.
