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 [-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. 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' 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. 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.