Merge pull request #1 from PARALLELIO/master

Updating my fork

CMakeLists.txt

@@ -7,17 +7,34 @@ project (PIO C)
 
 #===== Library Options =====
 option (PIO_ENABLE_FORTRAN   "Enable the Fortran library builds"            ON)
-option (PIO_ENABLE_TIMING    "Enable GPTL timing"                           ON)
+option (PIO_ENABLE_TIMING    "Enable the use of the GPTL timing library"    ON)
 option (PIO_TEST_BIG_ENDIAN  "Enable test to see if machine is big endian"  ON)
-option (PIO_ENABLE_MPIIO     "Enable support for MPI-IO auto detect"        ON)
+option (PIO_USE_MPIIO        "Enable support for MPI-IO auto detect"        ON)
+option (WITH_PNETCDF         "Require the use of PnetCDF"                   ON)
 
-#===== Library Variables
+#===== Library Variables =====
 set (PIO_FILESYSTEM_HINTS IGNORE CACHE STRING "Filesystem hints (lustre or gpfs)")
 
 #===== Testing Options =====
 option (PIO_ENABLE_TESTS  "Enable the testing builds"                           ON)
 option (PIO_HDF5_LOGGING  "Enable hdf5 logging (requires instrumented netcdf4)" OFF)
 
+#==============================================================================
+#  BACKWARDS COMPATIBILITY
+#==============================================================================
+
+# Old NETCDF_DIR variable --> NetCDF_PATH
+if (DEFINED NETCDF_DIR)
+    set (NetCDF_PATH ${NETCDF_DIR}
+         CACHE STRING "Location of the NetCDF library installation")
+endif ()
+
+# Old PNETCDF_DIR variable --> PnetCDF_PATH
+if (DEFINED PNETCDF_DIR)
+    set (PnetCDF_PATH ${PNETCDF_DIR}
+         CACHE STRING "Location of the PnetCDF library installation")
+endif ()
+
 #==============================================================================
 #  APPEND TO CMAKE MODULE PATH
 #==============================================================================
@@ -26,25 +43,25 @@ option (PIO_HDF5_LOGGING  "Enable hdf5 logging (requires instrumented netcdf4)"
 list (APPEND CMAKE_MODULE_PATH ${CMAKE_SOURCE_DIR}/cmake)
 
 #===== External modules =====
-if (NOT DEFINED CMAKE_UTILS_PATH)
+if (NOT DEFINED USER_CMAKE_MODULE_PATH)
     message (STATUS "Importing CMake_Fortran_utils")
     execute_process(
         COMMAND git clone https://github.com/CESM-Development/CMake_Fortran_utils
         WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
         OUTPUT_QUIET
         ERROR_QUIET)
-    find_path (CMAKE_UTILS_PATH
+    find_path (USER_CMAKE_MODULE_PATH
                NAMES mpiexec.cmake
                HINTS ${CMAKE_BINARY_DIR}/CMake_Fortran_utils)
-    if (CMAKE_UTILS_PATH)
+    if (USER_CMAKE_MODULE_PATH)
         message (STATUS "Importing CMake_Fortran_utils - success")
     else ()
         message (FATAL_ERROR "Failed to import CMake_Fortran_utils")
     endif ()
 endif ()
-set (CMAKE_UTILS_PATH ${CMAKE_UTILS_PATH}
+set (USER_CMAKE_MODULE_PATH ${USER_CMAKE_MODULE_PATH}
      CACHE STRING "Location of the CMake_Fortran_utils")
-list (APPEND CMAKE_MODULE_PATH ${CMAKE_UTILS_PATH})
+list (APPEND CMAKE_MODULE_PATH ${USER_CMAKE_MODULE_PATH})
 
 #==============================================================================
 #  INCLUDE SOURCE DIRECTORIES

README.md

@@ -0,0 +1,131 @@
+# ParallelIO
+
+A high-level Parallel I/O Library for structured grid applications
+
+## Dependencies
+
+PIO can use NetCDF (version 4.3.3+) and/or PnetCDF (version 1.6.0+) for I/O.
+Ideally, the NetCDF version should be built with MPI, which requires that it
+be linked with an MPI-enabled version of HDF5.  Optionally, NetCDF can be 
+built with DAP support, which introduces a dependency on CURL.  Additionally,
+HDF5, itself, introduces dependencies on LIBZ and (optionally) SZIP.
+
+## Configuring with CMake
+
+To configure the build, PIO requires CMake version 2.8.12+.  The typical
+configuration with CMake can be done as follows:
+
+```
+CC=mpicc FC=mpif90 cmake [-DOPTION1=value1 -DOPTION2=value2 ...] /path/to/pio/source
+```
+
+where `mpicc` and `mpif90` are the appropriate MPI-enabled compiler wrappers
+for your system.
+
+The `OPTIONS` section typically should consist of pointers to the install
+locations for various dependencies, assuming these dependencies are not 
+located in *canonical* search locations.  
+
+For each dependency `XXX`, one can specify the location of its 
+installation path with the CMake variable `XXX_PATH`.  If the `C` and
+`Fortran` libraries for the dependency are installed in different locations
+(such as can be done with NetCDF), then you can specify individually
+`XXX_C_PATH` and `XXX_Fortran_PATH`.  Hence, you can specify the locations
+of both NetCDF-C and NetCDF-Fortran, as well as PnetCDF, with the following
+CMake configuration line:
+
+```
+CC=mpicc FC=mpif90 cmake -DNetCDF_C_PATH=/path/to/netcdf-c \
+                         -DNetCDF_Fortran_PATH=/path/to/netcdf-fortran \
+                         -DPnetCDF_PATH=/path/to/pnetcdf \
+                         /path/to/pio/source
+```
+
+This works for the dependencies: `NetCDF`, `PnetCDF`, `HDF5`, `LIBZ`, `SZIP`.
+
+### Additional CMake Options
+
+Additional configuration options can be specified on the command line.
+
+The `PIO_ENABLE_TIMING` option can be set to `ON` or `OFF` to enable or
+disable the use of GPTL timing in the PIO libraries.  This feature requires
+the GPTL C library for the PIO `C` library and the GPTL Fortran library with
+the `perf_mod.mod` and `perf_utils.mod` interface modules.  If these GPTL
+libraries are already installed on the system, the user can point PIO to the
+location of these libraries with the `GPTL_PATH` variable (or, individually,
+`GPTL_C_PATH` and `GPTL_Fortran_Perf_PATH` variables).  However, if these
+GPTL libraries are not installed on the system, and GPTL cannot be found,
+then PIO will build its own internal version of GPTL.  
+
+If PnetCDF is not installed on the system, the user can disable its use by
+setting `-DWITH_PNETCDF=OFF`.  This will disable the search for PnetCDF on the
+system and disable the use of PnetCDF from within PIO.
+
+If the user wishes to disable the PIO tests, then the user can set the
+variable `-DPIO_ENABLE_TESTS=OFF`.  This will entirely disable the CTest 
+testing suite, as well as remove all of the test build targets.
+
+If you wish to install PIO in a safe location for use later with other
+software, you may set the `CMAKE_INSTALL_PREFIX` variable to point to the
+desired install location.
+
+## Building
+
+Once you have successfully configured PIO with CMake in a build directory.
+From within the build directory, build PIO with:
+
+```
+make
+```
+
+This will build the `pioc` and `piof` libraries.
+
+## Testing
+
+If you desire to do testing, and `PIO_ENABLE_TESTS=ON` (which is the default
+setting), you may build the test executables with:
+
+```
+make tests
+```
+
+Once the tests have been built, you may run tests with:
+
+```
+ctest
+```
+
+If you have not run `make tests` before you run `ctest`, then you will see
+all of the tests fail.
+
+Alternatively, you may build the test executables and then run tests 
+immediately with:
+
+```
+make check
+```
+
+(similar to the typical `make check` Autotools target).
+
+**NOTE:** It is important to note that these tests are designed to run in parallel.
+If you are on one of the supported supercomputing platforms (i.e., NERSC, NWSC, ALCF, 
+etc.), then the `ctest` command will assume that the tests will be run in an appropriately
+configured and scheduled parallel job.  This can be done by requesting an interactive
+session from the login nodes and then running `ctest` from within the interactive
+terminal.  Alternatively, this can be done by running the `ctest` command from a
+job submission script.  It is important to understand, however, that `ctest` itself
+will preface all of the test executable commands with the appropriate `mpirun`/`mpiexec`/`runjob`/etc.
+Hence, you should not further preface the `ctest` command with these MPI launchers.
+
+## Installing
+
+Once you have built the PIO libraries, you may install them in the location
+specified by the `CMAKE_INSTALL_PREFIX`.  To do this, simply type:
+
+```
+make install
+```
+
+If the internal GPTL libraries were built (because GPTL could not be found
+and the `PIO_ENABLE_TIMING` variable is set to `ON`), then these libraries
+will be installed with PIO.

cmake/FindGPTL.cmake

@@ -0,0 +1,80 @@
+# - Try to find GPTL
+#
+# This can be controlled by setting the GPTL_DIR (or, equivalently, the 
+# GPTL environment variable), or GPTL_<lang>_DIR CMake variables, where
+# <lang> is the COMPONENT language one needs.
+#
+# Once done, this will define:
+#
+#   GPTL_<lang>_FOUND        (BOOL) - system has GPTL
+#   GPTL_<lang>_IS_SHARED    (BOOL) - whether library is shared/dynamic
+#   GPTL_<lang>_INCLUDE_DIR  (PATH) - Location of the C header file
+#   GPTL_<lang>_INCLUDE_DIRS (LIST) - the GPTL include directories
+#   GPTL_<lang>_LIBRARY      (FILE) - Path to the C library file
+#   GPTL_<lang>_LIBRARIES    (LIST) - link these to use GPTL
+#   GPTL_<lang>_DEFINITIONS  (LIST) - preprocessor macros to use with GPTL
+#   GPTL_<lang>_OPTIONS      (LIST) - compiler options to use GPTL
+#
+# The available COMPONENTS are: C Fortran Perfmod
+# If no components are specified, it assumes only C
+include (LibFind)
+
+# Define GPTL C Component
+define_package_component (GPTL DEFAULT
+                          COMPONENT C
+                          INCLUDE_NAMES gptl.h
+                          LIBRARY_NAMES gptl)
+
+# Define GPTL Fortran Component
+define_package_component (GPTL
+                          COMPONENT Fortran
+                          INCLUDE_NAMES gptl.mod
+                          LIBRARY_NAMES gptl)
+
+# Define GPTL Fortran_Perf Component
+define_package_component (GPTL
+                          COMPONENT Fortran_Perf
+                          INCLUDE_NAMES perf_mod.mod
+                          LIBRARY_NAMES gptl)
+
+# Search for list of valid components requested
+find_valid_components (GPTL)
+
+#==============================================================================
+# SEARCH FOR VALIDATED COMPONENTS
+foreach (GPTL_comp IN LISTS GPTL_FIND_VALID_COMPONENTS)
+
+    # If not found already, search...
+    if (NOT GPTL_${GPTL_comp}_FOUND)
+
+        # Manually add the MPI include and library dirs to search paths
+        if (GPTL_comp STREQUAL C OR GPTL_comp STREQUAL HL)
+            if (MPI_C_FOUND)
+                set (GPTL_${GPTL_comp}_INCLUDE_HINTS ${MPI_C_INCLUDE_PATH})
+                set (GPTL_${GPTL_comp}_LIBRARY_HINTS)
+                foreach (lib IN LISTS MPI_C_LIBRARIES)
+                    get_filename_component (libdir ${lib} PATH)
+                    list (APPEND GPTL_${GPTL_comp}_LIBRARY_HINTS ${libdir})
+                    unset (libdir)
+                endforeach ()
+            endif ()
+        else ()
+            if (MPI_Fortran_FOUND)
+                set (GPTL_${GPTL_comp}_INCLUDE_HINTS ${MPI_Fortran_INCLUDE_PATH})
+                set (GPTL_${GPTL_comp}_LIBRARY_HINTS)
+                foreach (lib IN LISTS MPI_Fortran_LIBRARIES)
+                    get_filename_component (libdir ${lib} PATH)
+                    list (APPEND GPTL_${GPTL_comp}_LIBRARY_HINTS ${libdir})
+                    unset (libdir)
+                endforeach ()
+            endif ()
+        endif ()
+
+        # Search for the package component
+        find_package_component(GPTL COMPONENT ${GPTL_comp}
+                               INCLUDE_HINTS ${GPTL_${GPTL_comp}_INCLUDE_HINTS}
+                               LIBRARY_HINTS ${GPTL_${GPTL_comp}_LIBRARY_HINTS})
+
+    endif ()
+
+endforeach ()

cmake/FindNetCDF.cmake

@@ -1,7 +1,7 @@
 # - Try to find NetCDF
 #
-# This can be controlled by setting the NetCDF_DIR (or, equivalently, the 
-# NETCDF environment variable), or NetCDF_<lang>_DIR CMake variables, where
+# This can be controlled by setting the NetCDF_PATH (or, equivalently, the 
+# NETCDF environment variable), or NetCDF_<lang>_PATH CMake variables, where
 # <lang> is the COMPONENT language one needs.
 #
 # Once done, this will define:

cmake/FindPnetCDF.cmake

@@ -1,7 +1,7 @@
 # - Try to find PnetCDF
 #
-# This can be controlled by setting the PnetCDF_DIR (or, equivalently, the 
-# PNETCDF environment variable), or PnetCDF_<lang>_DIR CMake variables, where
+# This can be controlled by setting the PnetCDF_PATH (or, equivalently, the 
+# PNETCDF environment variable), or PnetCDF_<lang>_PATH CMake variables, where
 # <lang> is the COMPONENT language one needs.
 #
 # Once done, this will define:

cmake/LibFind.cmake

@@ -150,6 +150,14 @@ function (find_package_component PKG)
     string (TOUPPER ${PKG} PKGUP)
     string (TOUPPER ${PKGCOMP} PKGCOMPUP)
 
+    # Handle QUIET and REQUIRED arguments
+    if (${${PKG}_FIND_QUIETLY})
+        set (${PKGCOMP}_FIND_QUIETLY TRUE)
+    endif ()
+    if (${${PKG}_FIND_REQUIRED})
+        set (${PKGCOMP}_FIND_REQUIRED TRUE)
+    endif ()
+
     # Determine include dir search order
     set (INCLUDE_HINTS)
     if (${PKG}_INCLUDE_HINTS)

doc/source/Installing.txt

@@ -25,9 +25,9 @@
 
 Before running cmake, you will need to know the location of some supporting libraries. 
 
-- Set the NETCDF_DIR environment variable to the netcdf install directory.
+- Set the NETCDF_PATH environment variable to the netcdf install directory.
 
-- Set the PNETCDF_DIR environment variable to the pnetcdf install directory, This will enable support
+- Set the PNETCDF_PATH environment variable to the pnetcdf install directory, This will enable support
 for parallel-netcdf
 
 - Set the CC, FC, MPICC, and MPIFC environment variables to the serial and parallel C and Fortran 90 compiler names.

src/CMakeLists.txt

@@ -15,10 +15,25 @@ else ()
   set (PIO_BIG_ENDIAN OFF CACHE BOOL "Whether machine is big endian")
 endif ()
 
+# Look for GPTL
+if (PIO_ENABLE_TIMING)
+    find_package (GPTL COMPONENTS C QUIET)
+    find_package (GPTL COMPONENTS Fortran_Perf QUIET)
+endif ()
+
 #==============================================================================
 #  INCLUDE SOURCE DIRECTORIES
 #==============================================================================
 
-add_subdirectory (gptl)
+# Build GPTL only if necessary
+if (PIO_ENABLE_TIMING)
+    if (NOT GPTL_C_FOUND OR NOT GPTL_Fortran_Perf_FOUND)
+        add_subdirectory (gptl)
+    endif ()
+endif ()
+
+# Build the C library
 add_subdirectory (clib)
+
+# Build the Fortran library
 add_subdirectory (flib)