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 [-I ...]' # extra directories of header files LDFLAGS='-L [-L ...]' # extra directories for libraries LIBS='-l [-l ...]' # 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' as shown above, and the compiler will typically search for a library called lib.so and then lib.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.