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
=====================

NetCDF libraries and include files are usually detected automatically during
installation of RNetCDF.

The configure script first tries nc-config, which is part of most NetCDF4
installations. If this causes problems, use option --without-nc-config.

If nc-config fails or is disabled, the configure script next tries pkg-config.
This can also be disabled if required using --without-pkg-config.

When nc-config or pkg-config are used, they are tested twice. The first
attempt uses libraries returned by the --libs option, and the second attempt
uses --static --libs. This approach means that RNetCDF finds shared libraries
if they are available, before falling back to static libraries.

If both nc-config and pkg-config fail or are disabled, the configure script
searches for libraries and header files in system-specific default paths.
Additional paths and libraries can be defined via the following variables:

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.

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

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. If an MPI compiler driver was used to install the NetCDF library,
this will often be reported by command "nc-config --cc".

Although nc-config is used by default in the RNetCDF configure script, the
compiler reported by nc-config may not be compatible with R headers, so it
cannot be used automatically when building RNetCDF. Users can specify an
alternative compiler (e.g. mpicc) using the configure script option
--with-cc. This option overrides the compiler used to build R, and users
are advised to check the installation log messages for warnings that indicate
incompatibilities with R headers or RNetCDF code.

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-cc=mpicc --with-mpiexec=mpiexec" \
    RNetCDF_2.11-1.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.11-1.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.

