README-INSTALL

PFUNIT VERSION 3.0.1 INSTALLATION AND BASIC USAGE GUIDE

VERSION 2014-0915 M. Rilee mike@rilee.net

TABLE OF CONTENTS

1. PREREQUISITES
2. OBTAINING PFUNIT
3. WHAT'S IN THE DIRECTORY?
4. CONFIGURATION
5. BUILDING PFUNIT
6. INSTALLATION
7. USAGE
8. DEVELOPMENT
9. FEEDBACK & SUPPORT
10. ACKNOWLEDGMENTS
11. KNOWN INSTALLATIONS/VERSIONS
12. NOTES
13. TODO


1. PREREQUISITES

The development work for pFUnit has mostly been carried out on a
mixture of systems, including high-end computers, Apple Mac OSX, and
linux-based systems.  A preliminary Windows/CYGWIN port has been
contributed by a user. Full use of the system depends on the following
being available.

Fortran 2003+ (Tested with Intel 13.1+, NAG 5.3, GCC 4.8.3, 4.9.0, IBM's XLF)
The Message Passing Interface (MPI)
OPENMP
GNU Make
Python

A CMake build process is also available.

Doxygen is used to generate documentation (see http://www.doxygen.org).

The system is routinely undergoes regression testing, including with GNU,
Intel, and NAG fortran compilers and OpenMPI.

pFUnit makes extensive use of leading edge Fortran language features,
which are generally best supported with by the latest compiler
versions.  The capacity to support older compilers is limited.

2. OBTAINING PFUNIT

The best way to obtain pFUnit is to clone the git repository from
SourceForge as follows.

# Read Only Access
git clone git://git.code.sf.net/p/pfunit/code pFUnit

This will create the directory pFUnit in the current working
directory.  

You may also visit the project page at SourceForge and
download the source tarfile "pFUnit.tar.gz" there.

http://sourceforge.net/projects/pfunit/

or

http://sourceforge.net/projects/pfunit/files/latest/download

Extracting this tarfile via a command like

$ tar zxf ./pFUnit.tar.gz

will place the pFUnit files into the current working directory.

For other ways to acquire the code visit

https://sourceforge.net/p/pfunit/code/ci/master/tree/

or contact the pFUnit team.

3. WHAT'S IN THE DIRECTORY?

In the top level of the pFUnit distribution you will see the following
files.

CMakeLists.txt - Initial support for cmake-based builds.

COPYRIGHT - Contains information pertaining to the use and
distribution of pFUnit.

Examples - Contains examples of how to use pFUnit once it is
installed.

GNUmakefile - The top level makefile for building and installing
pFUnit.

bin - Executables used to construct and perform unit tests.

documentation - Provides information about the pFUnit.

include - Files to be included into makefiles or source, including use
code.

LICENSE - The NASA Open Source Agreement for GSC-15,137-1 F-UNIT, also known as pFUnit.

README-INSTALL - This file.

source - Source code and scripts of the pFUnit library and framework.

tests - Source code for unit testing pFUnit itself.

tools - Tools used to help develop, build, and install pFUnit.

VERSION - Contains a string describing the current version of the framework.

4. CONFIGURATION

Little needs to be done to configure pFUnit for the build, however
there are several environment variables on which the package depends.

F90_VENDOR - is set to include the correct makefile in $(TOP_DIR)/include,
i.e. GNU, Intel, NAG, or PGI.  Case insensitive file systems may cause
some confusion from time-to-time.

F90 - is set to the Fortran compiler being used: e.g. ifort for Intel,
gfortran for GNU.

COMPILER - is set according to F90_VENDOR and is automatically set in
the top level makefile.

For MPI-based unit testing, your setup may require the following as well.

MPIF90
$ # e.g.
$ export MPIF90=mpif90

As a convenience for working with multiple MPI configurations, you may
also set the following.

MPIRUN
$ # e.g.
$ export MPIRUN=/some.path/mpirun

PFUNIT_MAX_RANK - controls the maximum size of the arrays asserts are
defined over.  If PFUNIT_MAX_RANK is not set, the default is 5 and pFUnit's
assertions will be able to handle arrays up to rank 5.

$ export PFUNIT_MAX_RANK=8

DOXYGEN - To generate documentation, set DOXYGEN to the desired
executable.  NOTE: Doxygen Version 1.8.5 does not respect CamelCase
names from Fortran source code by currently converting all to
lowercase.  It does this to get HTML links correct for references in
the source code that also do not respect the CamelCase convention.
The Fortran standard specifies case insensitivity.  Doxygen 1.7.x
seems to better respect CamelCase.
$ #.e.g.
$ export DOXYGEN=/opt/local/share/doxygen/doxygen-1.7.6/bin/doxygen

5.1 BUILDING PFUNIT FOR TESTING SERIAL CODES (Non-MPI)

1. Change to the directory into which pFUnit has been placed.
2. Set these environment variables (bash example):
$ export F90=gfortran-mp-4.8
$ export F90_VENDOR=GNU
3. To build pFUnit for unit testing of serial codes, execute make.
The unit tests for pFUnit itself will run automatically.
$ make tests
3.1 Occasionally on the first run through, one will get a spurious
(runtime) error, for example in the unix process component.
Re-execute "make tests" to check again.
4. At this point the pFUnit object library is in the source directory,
along with a large number of Fortran module files.

5.2 BUILDING PFUNIT FOR TESTING PARALLEL CODES (MPI)

To build pFUnit for unit testing MPI-based codes, be sure that the
environment is properly set up for the MPI implementation you are
using. Depending on your local environment, you may need execute the
build within a batch or other job queing system, e.g. an interactive
batch job under PBS. The steps for building pFUnit start out the same
as for the serial case above, but add MPI=YES to the environment to
switch on MPI support.  The MPI-based unit tests for pFUnit itself
will run automatically.  Again, occasionally a spurious (runtime)
error may appear on the first execution.

3. Execute make as follows.
$ make tests MPI=YES 

4. At this point an MPI-enabled pFUnit object library is in the source
directory, along with a large number of Fortran module files.

Also, one may get some harmless "no symbols" warnings when the pFUnit library is constructed.

5.3 BUILDING PFUNIT FOR TESTING PARALLEL CODES (OPENMP)

Initial (limited) support for OPENMP has been implemented.  At this
writing, a basic functionality is available.

The process for building pFUnit for testing OPENMP-based codes is
similar to that for other paradigms.

3. To compile for OPENMP support execute make as follows.
$ make tests OPENMP=YES 

4. At this point the OPENMP-enabled pFUnit is ready to be installed.

5.4 CLEANING

To clean the pFUnit build directory for the space or to rebuild there
are two options.

1. Make clean to remove object files and other intermediate products.
$ make clean

2. Make distclean to remove libraries and other more final products.
$ make distclean

3. Some directories support a "make src_clean" to remove intermediate
products in subdirectories.

5.5 BUILDING THE DOCUMENTATION

A start at documentation for pFUnit is in the documentation directory.
Doxygen is our primary documentation tool.  To make the documentation,
which will be generated in the documentation directory, please invoke
the following from the top level of the PFUNIT distribution.

$ make documentation

Or to make a reference manual:

$ make documentation/pFUnit2-ReferenceManual.pdf

To select a specific version of Doxygen, please set the DOXYGEN
environment variable as in the Configuration section above.  You 
may wish to do this if your code uses CamelCase names as current
versions of Doxygen (1.8.5) do not respect this convention for
Fortran.

5.6 BUILDING PFUNIT USING CMAKE

Initial support for CMAKE has been implemented.  At this
writing, a basic functionality is available.

3. The process for building pFUnit using cmake is as follows.  In the
top directory of the distribution make a new directory to support the
build, then change to that directory and run cmake (pointing back to
the source) to generate the required makefiles.

$ mkdir build
$ cd build
$ # e.g. cmake -DMPI=YES -DOPENMP=NO -DINSTALL_PATH=<A path> <path to source>
$ cmake -DMPI=NO ..
$ make tests

One may also set the environment variable PFUNIT instead of setting
INSTALL_PATH on the cmake command line as given above.

4. If the build is successful, then at this point make install should work.

6. INSTALLATION

Installations 6.1-6.5 are based on GNU make and the project makefiles.

6.1 INSTALLATION - SERIAL

To install pFUnit for regular use, set INSTALL_DIR to the location in
which to place pFUnit.  This can be done on the make command line.
For example, after compiling pFUnit for serial use (MPI absent or
MPI=NO), please try.

$ # In the top of the pFUnit build directory.
$ make install INSTALL_DIR=/opt/pfunit/pfunit-serial

Note: you may need special priveleges to install in some locations,
e.g. via sudo.

To test the installation set PFUNIT to INSTALL_DIR, then change the
working directory to Examples in pFUnit distribution and execute
"buildIt," which will run a number of examples.  These include some
expected failures.  

$ # In the top pFUnit build directory...
$ export PFUNIT=/opt/pfunit/pfunit-serial
$ cd Examples
$ ./buildIt

6.2 INSTALLATION - MPI

For installing an MPI-enabled pFUnit library, change to the top of the
distribution and execute make with MPI=YES.  You may need to "make
distclean" first.  After compilation and pFUnit passes its self-tests,
then installation proceeds as for the serial case above.

$ make install INSTALL_DIR=/opt/pfunit/pfunit-parallel

To test, set PFUNIT and go into Examples/MPI_Halo directory.

$ # In the top pFUnit build directory...
$ export PFUNIT=/opt/pfunit/pfunit-parallel
$ # The variable MPIF90 must be set to the appropriate build script.
$ export MPIF90=mpif90
$ cd Examples/MPI_Halo/
$ make

This will compile and run a set of parallel examples that includes
intentional failures.

6.3 INSTALLATION - OPENMP

At this time the OPENMP version of pFUnit can be installed in the same
way as for the serial or MPI-parallel codes.  OPENMP support, tests,
and examples are limited as of this writing.

6.4 INSTALLATION - DEFAULT DIRECTORY

If INSTALL_DIR is not set, "make install" will attempt to install
pFUnit into the top build directory.  This will create directories
such as lib and mod in the top level of the build directory and will
overwrite the include/base.mk with include/base-install.mk.  If this
is not desired, then "make develop" will put back the original
base.mk, which is the file to be used for development and building
pFUnit.  In general, we recommend installing to a directory that is not also the
build directory.

7.1 USAGE - CONFIGURATION

For regular use, after installation, the same compiler/MPI development
configuration that was used to build pFUnit should be used.  Once the
environment variables and paths associated with the environment are
set, to configure pFUnit, please set the following.

PFUNIT - set to the directory into which pFUnit was installed.
F90_VENDOR - set to Intel, GNU, NAG, or PGI accordingly.

7.2 USAGE - PREPROCESSOR - HELLO WORLD

An example of how to use the preprocessor can be found in
Examples/Simple.  The GNU makefile shows how to construct an F90 file
from a preprocessor input file.  For example, the GNU make rule can be:

# GNU makefile rule
%.F90: %.pf
       $(PFUNIT)/bin/pFUnitParser.py $< $@

The file testSuites.inc is included in the include/driver.F90 file
during the build process.  To include tests, one must add the test
suite module to testSuites.inc, as follows.

! Add a test suite to the build.
ADD_TESTS_SUITE(helloWorld_suite)

A preprocessor input file contains tests and is a 
Fortran free-format file with directives, for example:

! helloWorld.pf - with a successful test...
@test
subroutine testHelloWorld()
   use pfunit_mod
   implicit none
   @assertEqual("Hello World!","Hello World!")
end subroutine testHelloWorld

7.3 USAGE - Compiling and Executing the Tests (SERIAL)

An example of a GNU make rule for for the final step of compiling a test follows.

# This step presumes "include $(PFUNIT)/include/base.mk" earlier in the makefile.
tests.x: testSuites.inc myTests.pf
         $(F90) -o $@ -I$(PFUNIT)/mod -I$(PFUNIT)/include \
                $(PFUNIT)/include/driver.F90 \
                ./*$(OBJ_EXT) $(LIBS) $(FFLAGS)

To execute the tests, one invokes "./tests.x" with the appropriate command line options (see below).

7.3.1 USAGE - Compiling and Executing the Tests (MPI PARALLEL)

One invokes MPI-based parallel tests according to the MPI framework being used.  For example:

$ mpirun -np 4 tests.x


7.4 USAGE - Command Line Options

The executable test program provides several command line options,
when "include/driver.F90" is used, as it is automatically when using
the PFUNIT preprocessor.

-v or -verbose                  Verbose execution.
-d or -debug                    Provide debugging information.
-h                              Print help message.
-o <outputfile>                 Direct pFUnit messages to a file.
-robust                         Use the robust runner. Runs tests as processes so failures do not halt testing.
-skip <number of tests to skip> Use the subset runner, which runs a subset of the tests in a suite.

An example from Examples/Robust:

$ ./tests.x -robust

8. DEVELOPMENT

Generally pFUnit development is performed in the build directory
structure.  Care should be taken to make clean or distclean in between
configuration changes.  As stated above, it is best to set INSTALL_DIR
and "make install" pFUnit to another directory that can be placed in a
user's paths.  

9.1 FEEDBACK AND BUGS

9.2 SUPPORT

9.3 TIPS

1. Environment Modules - Though not strictly required, the Environment
Modules package can be a convenient way to package, maintain, and
switch between environments.  This can be particularly important for
pFUnit, which must be built using the same tool suite being used for
development, e.g. compilers, linkers, etc. [To do:  A sample pFUnit
modulefile is provided in the OTHER directory.] Environment Modules

2. Compile time errors like '"include [...]include/.mk" not found'
likely signify that you not executing make in the top level
directory during a build.  Alternatively, during regular usage after
installation, PFUNIT has not been set.

During building, if you wish to compile in a subdirectory of within the
pFUnit heriarchy, please try setting the COMPILER environment variable
on the make command line.  For example:

$ make all COMPILER=Intel

3. If you wish to see the intermediate files, use the target .PRECIOUS
in the makefile to keep them from being deleted. For example:

# In GNUmakefile
.PRECIOUS: %_cpp.F90

9.4 PLATFORM SPECIFIC NOTES

9.4.1 Mac OSX

The MacPorts package management system is a convenient way to install
and maintain many packages, including gcc which includes gfortran.

9.4.2 Windows/CYGWIN

User contributed code for Windows/CYGWIN has been added, but is
currently not tested and supported by the pFUnit team. At this
writing, 2013-1031, serial Examples and MPI are not known to be
supported.  Please contact us if you wish to either contribute or
otherwise discuss this port.

9.4.3 Intel Fortran Version 13:  -DINTEL_13

To make pFUnit work with Intel Fortran Version 13, please ensure that
"-DINTEL_13" is passed to the compiler when building or using
pFUnit. In the build process for pFUnit, this is added to the make
variables CPPFLAGS and FPPFLAGS.

10. ACKNOWLEDGMENTS

Thanks to the follwing for their review and comments: B. Van Aartsen, T. Clune.

Windows/CYGWIN contributions from E. Lezar.

Other acknowledgments:  S.P. Santos (NCAR), M. Hambley (UK Met Office), J. Krishna (ANL).

11. KNOWN INSTALLATIONS/VERSIONS (git cognizant from "sourceforge.net/projects/pfunit")

master - The current release.

development - The cutting edge of pFUnit development.

pfunit_2.1.0 - A feature freeze prior to a major upgrade of the preprocessor.

12. NOTES

* For modifications and feature requests please see "sourceforge.net/projects/pfunit".

TBD

13. --TODO--

- Make other directory.
- Make Environment Modules example in other directory.
- Other build systems, e.g. CMake.


14. REVISIONS TO THIS DOCUMENT

2014-0915 Minor updates for 3.0.1. MLR
2014-0404 Updated for release of 3.0. TLC
2014-0131, 2014-0205. Updated. MLR
2013-1107. Minor edits. MLR
2013-1031. Added user contributed code for Windows/CYGWIN & IBM's XLF. MLR
2013-0830-1359. Minor corrections and added MPIF90 to 6.2. MLR
2013-0806-1345. Corrected git reference. Was using old URL.  MLR
2013-0805. Initial draft. MLR