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.

The configure script can accept variables to define extra paths or 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> ...]'    libraries to link

Definitions for the above variables may be appended to the configure command line.

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.


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

R CMD INSTALL --configure-args="CPPFLAGS=-I/sw/include \
    LDFLAGS=-L/sw/lib LIBS=-lhdf5" RNetCDF_2.5-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.5-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.