/*! \page install Installing PIO


## Getting the Release ##

The PIO code is currently stored on github at
<https://github.com/PARALLELIO/ParallelIO>. For questions about
downloading or developing this code, consult the [CIME Git
Wiki](https://github.com/CESM-Development/cime/wiki/CIME-Git-Workflow)
or email <mailto:jedwards@ucar.edu>.

Download the latest release from the GitHub releases page. Download
the release tarball, which will be named something like
pio-2.4.3.tar.gz.

## Dependencies ##

PIO can use NetCDF (version 4.6.1+) and/or PnetCDF (version 1.9.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.

@image html PIO_Library_Architecture1.jpg "PIO Library Architecture"

## Building PIO C and Fortran Libraries ##

Unpack the tarball and build with:

<pre>
./configure --enable-fortran
make
make check
make install
</pre>

Environment flags CC and FC should be set to MPI C and Fortran
compilers. CPPFLAGS may be set to a list of directories which have the
include files for netCDF and pnetcdf. LDFLAGS may be set to a list of
directories where libraries may be found.

A complete example:

<pre>
export CPPFLAGS='-I/usr/local/pnetcdf-1.11.0_shared/include -I/usr/local/netcdf-c-4.7.0_hdf5-1.10.5_mpich-3.2/include -I/usr/local/netcdf-fortran-4.4.5_c_4.6.3_mpich-3.2/include'
export LDFLAGS='-L/usr/local/pnetcdf-1.11.0_shared/lib  -L/usr/local/netcdf-c-4.7.0_hdf5-1.10.5_mpich-3.2/lib'
export CC=mpicc
export FC=mpifort
export CFLAGS='-g -Wall'
./configure --enable-fortran
make check
make install
</pre>

### Testing with MPI ###

The tests are run as a bash script with called mpiexec to launch
programs. If this will not work for the install system, use the
--disable-test-runs option to configure. This will cause the tests to
be built, but not run. The tests may be run them manually.

### Optional GPTL Use ###

PIO may optionally be built with the General Purpose Timing Library
(GPTL). This is necessary for the performance testing program pioperf,
but optional for the rest of the library and tests. To build with
GPTL, include a path to its include and lib directories in the
CPPFLAGS/LDFLAGS flags before running configure.

### PIO Library Logging ###

If built with --enable-logging, the PIO libraries will output logging
statements to files (one per task) and stdout. Use the
PIOc_set_log_level() function to turn on logging. This will have a
negative impact on performance, when used, but helps with debugging.

## Building with CMake ##

A CMake build system is also avaible for the PIO C and Fortran
libraries. User may prefer to use a CMake build instead of the
autotools build.

 - @ref mach_walkthrough

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`.

For specific instructions to install on various commonly used super computers, please read the [walk-through guide to PIO Installation](@ref mach_walkthrough). 

### 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 with CMake ###

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 with CMake ###

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


_Note: 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).

*ANOTHER NOTE:* 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.

 - @ref test

### Installing with CMake ###

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 Build Examples ###

From within the build directory, build the PIO examples with:


    > make examples


This will build the C and Fortran examples in under the examples
subdirectory.


*/
