INSTALL

This file describes the command line arguments which can be passed during 
installation of the RNetCDF package and gives some further hints.


Software Requirements
=====================

NetCDF library version 4.1.3 or greater.

UDUNITS library version 2.0.4 or greater (optional, for calendar functions).

On platforms that support both 32- and 64-bit executables, ensure that the 
above libraries and the R executable are compatible. Mixing 32-bit and 64-bit 
software will generally not work.


R CMD INSTALL Options
=====================

Libraries and include files are usually detected automatically by nc-config, 
which is part of most NetCDF4 installations. If this causes problems, you can 
disable nc-config using --without-nc-config.

Shared or static libraries can be requested from nc-config, based on configure 
option --with-nc-config-static. Default values of this setting vary by 
platform, with shared libraries typically used in Unix-alikes and static 
libraries on Windows and macOS.

The configure script can accept variables to define extra directories and
libraries:

CPPFLAGS='-I<incdir> [-I<incdir> ...]'  # extra directories of header files
LDFLAGS='-L<libdir> [-L<libdir> ...]'   # extra directories for libraries
LIBS='-l<libname> [-l<libname> ...]'    # extra libraries to link

Definitions for the above variables may be appended to the configure command 
line or passed through the environment.

The final set of directories and libraries is obtained by joining variables 
from nc-config (if enabled), the above variables, and settings used when 
building R, in that order. The directories are searched in left-to-right order 
for required header files or libraries. The libraries are searched in 
left-to-right order for functions.

Some R installations prepend the R library directory when linking the RNetCDF 
shared library, which may cause problems in rare cases when unwanted versions 
of other libraries are installed in the same directory. A possible solution 
involves passing the full pathname of the desired library through the LIBS 
variable, as explained below.

Note that libraries may be specified in LIBS in a few different ways. The most 
common way is '-l<libname>' as shown above, and the compiler will typically 
search for a library called lib<libname>.so and then lib<libname>.a. But you 
can also specify the full pathname of a library if necessary, perhaps to force 
the use of a particular NetCDF or udunits library on systems with multiple 
versions available.

MPI Support
===========

Message Passing Interface (MPI) is a standardised method for programs to 
communicate between multiple processes within a machine or across machines. The 
NetCDF library has optional support for MPI, which allows multiple processes to 
read and write a shared NetCDF dataset. This ensures that NetCDF metadata is 
consistent across processes, while allowing parallel processing of huge 
datasets.

Simple examples using RNetCDF with MPI are given in the demos directory of 
RNetCDF. These examples will be run as tests in R CMD check if NetCDF parallel
I/O support is detected, packages Rmpi or pbdMPI are installed, and option
--with-mpiexec is specified.

Most MPI installations provide a compiler driver (e.g. mpicc) that simplifies 
the building of MPI software. This involves setting paths to headers and 
libraries, as well as linking libraries, in ways that may depend on compiler 
flags. The configure script has an option --with-mpicc=..., which allows the 
MPI compiler command to be specified. The MPI compiler command should be the 
same as that used when building the NetCDF library, which can often be found by 
running the command 'nc-config --cc'.

Note that the NetCDF library supports several distinct file formats, and 
parallel I/O support is implemented separately for netcdf4 (hdf5) format and 
earlier formats. It is possible to build the NetCDF library with parallel I/O 
support for some, all, or none of the file formats. Installation of RNetCDF 
should succeed regardless, but RNetCDF will return errors when attempting to 
use parallel I/O on unsupported file formats.


R CMD INSTALL Example
=====================

R CMD INSTALL --configure-args="CPPFLAGS=-I/sw/include \
    LDFLAGS=-L/sw/lib LIBS=-lhdf5 --with-mpicc=mpicc --with-mpiexec=mpiexec" \
    RNetCDF_2.9-2.tar.gz


LD_LIBRARY_PATH
===============

If a runtime error occurs indicating that shared libraries cannot be found, you 
may need to set or modify the library search path to include directories where 
NetCDF, HDF5 and/or UDUNITS libraries are stored. This is sometimes necessary 
for custom installations of the libraries.

The library search path is typically influenced by the environment variable 
LD_LIBRARY_PATH (or DYLD_LIBRARY_PATH for Mac OSX). For example:

export LD_LIBRARY_PATH=/sw/lib:$LD_LIBRARY_PATH

On some systems, it is possible to build R packages so that dependencies are 
found automatically at runtime. For example, some linkers provide an option 
such as '-rpath', which embeds the library search path when creating an 
executable or shared library. It may also be possible to avoid runtime 
dependencies by building your R package against static libraries (*.a), but 
this will only work if the functions in the libraries were compiled as position 
independent code (e.g. using the -fPIC option of gcc).


R CMD check Example
===================

R CMD check --install-args="--configure-args='CPPFLAGS=-I/sw/include \
    LDFLAGS=-L/sw/lib'" RNetCDF_2.9-2.tar.gz


Time units
==========

Common udunits databases are distributed with RNetCDF, and these are used by 
default when RNetCDF is loaded by R. However, a different units database may be 
used by specifying the appropriate file in environment variable 
UDUNITS2_XML_PATH.