Installation instructions for the rjags package ----------------------------------------------- The rjags package is an interface to the JAGS library. In order to build a binary package, or install from source, you must have a matching installation of the JAGS library. Contents: 1 Windows 2 Unix/Linux: pkg-config 3 Unix/Linux: runtime linkage 4 Unix/Linux: legacy configuration 1 Windows --------- If you are compiling the rjags package from source on Windows then you must supply the location of JAGS using the make variable JAGS_ROOT, defining it in the file HOME/.R/Makevars.win, e.g. JAGS_ROOT=c:/Progra~1/JAGS/JAGS-4.0.0 where HOME is the default starting directory for an R session launched from the start menu (typically your Documents folder). If you are installing the Windows binary rjags package, then R will consult the Windows registry to find the location of JAGS. Alternatively, you can specify the location of JAGS by setting the environment variable JAGS_HOME. 2 Unix/Linux: pkg-config ------------------------ If you have pkg-config installed then the configure script will use it to detect the JAGS library and set the compiler and linker flags for rjags. You can test this capability in a unix shell by typing pkg-config --modversion jags If this does not detect your JAGS installation then it means that the file 'jags.pc' is not on the search path of pkg-config. In this case you should add it by setting the environment variable PKG_CONFIG_PATH. For example if the full path to 'jags.pc' is '/usr/local/lib64/pkgconfig/jags.pc', then set export PKG_CONFIG_PATH=/usr/local/lib64/pkgconfig before installing rjags. Recall that most Linux distributions divide software into `user' and `developer' versions, so if you are using a pre-built JAGS binary package for your Linux distribution then remember to install the developer version before attempting to install the rjags package. 3 Unix/Linux: runtime linkage ----------------------------- Although pkg-config helps to find the right flags for linking to the JAGS library at compile time, it does not help at runtime. In order to detect potential problems with runtime linkage, the configure script of the rjags package will compile and run a test program that links to the JAGS library. If this fails with the message "runtime link error" then you may take the following actions to fix the problem: If you have administrative privileges (sudo or root access): 1) Add the directory containing the JAGS library to the linker path, typically by editing the file /etc/ld.so.conf. 2) If the directory is already on the linker path then you may need to run /sbin/ldconfig as root to update the linker cache. If you do not have administrative privileges: 3) Set the environment variable LD_RUN_PATH to the directory containing the JAGS library before installing rjags, or 4) Use the --enable-rpath option when installing rjags, i.e. from the unix shell: R CMD INSTALL --configure-args='--enable-rpath' rjags or, within R > install.packages("rjags", configure.args="--enable-rpath") You may also consider: 5) Set the environment variable LD_LIBRARY_PATH to the directory containing the JAGS library. Unlike options 3) and 4) if you use LD_LIBRARY_PATH then it must be set every time you load the rjags package, not just at compile time. Thus it is best to set this in the file .bash_profile (or the equivalent file if you using another shell). 4 Unix/Linux: legacy configuration ---------------------------------- Legacy configuration is used whenever pkg-config is not installed or otherwise fails to detect the JAGS library. Legacy configuration is deprecated and will be removed in a future version. If you experience problems with installing rjags then it is strongly recommended that you try to get pkg-config working rather than use the options below. The configure script will try to guess the location of the JAGS library. It does this by querying the R and jags executables, so both of these need to be on your PATH for automatic detection to work properly. If you have installed JAGS in a non-standard place then you may need to supply hints to the configure script. This can be done by passing configure arguments or setting environment variables (see below). The options/environment variables correspond to options that were used when JAGS was installed. They are shown in the table below: JAGS configure rjags configure Environmnent default option option variable -------------- --------------- ------------ ------- --prefix --with-jags-prefix JAGS_PREFIX /usr/local --libdir --with-jags-libdir JAGS_LIBDIR ${prefix}/${LIBnn} --includedir --with-jags-includedir JAGS_INCLUDEDIR ${prefix}/include By default LIBnn is the value returned by `R CMD config LIBnn`. This can be overridden by setting the environment variable LIBnn. 4.1 Setting the prefix ---------------------- By default, all JAGS files are installed in subdirectories of /usr/local. This is the prefix of the installation, and it can be changed to any value by supplying the --prefix argument when installing JAGS. - The jags script goes in ${prefix}/bin - The jags executable launched by the script goes in ${prefix}/libexec - The libraries go in ${prefix}/lib - The modules go in ${prefix}/lib/JAGS - The headers go in ${prefix}/include/JAGS Suppose that when you installed JAGS, you used the configure argument '--prefix=/opt' to install JAGS in the directory /opt instead of the default /usr/local. If /opt/bin is on your PATH then the configure script should still automatically detect JAGS for you. Otherwise, you need to supply the configure argument '--with-jags-prefix=/opt' when installing rjags. Alternatively you can set the environment variable JAGS_PREFIX before building rjags: export JAGS_PREFIX=/opt 4.2 Setting the library directory --------------------------------- Suppose you are on a 64-bit system and installed the JAGS library in /usr/local/lib64 instead of the default /usr/local/lib. If R_HOME is /usr/lib64/R then the configure script should automatically look in the right place for the JAGS library. Otherwise, you need to supply the configure argument '--with-jags-libdir=/usr/local/lib64' when installing rjags. Alternatively you can set the environment variable JAGS_LIBDIR before building rjags: export JAGS_LIBDIR=/usr/local/lib64 If the library directory is in the right prefix, but just has a different name (e.g. ${prefix}/lib64 or ${prefix}/lib32 instead of the default ${prefix}/lib), then you can just set the environment variable LIBnn. export LIBnn=lib64 4.3 Setting the include directory --------------------------------- It is unlikely that you will need to set the include directory, as there is no good reason for changing the default. Nevertheless, this option is included for completeness. By default, the header files go into ${prefix}/include, in a sub-directory JAGS. If you have put this subdirectory somewhere other than ${prefix}/include by supplying the --includedir option to configure when you built JAGS, then the corresponding option for rjags is --with-jags-includedir. Alternatively, you may set the environment variable JAGS_INCLUDEDIR. 4.4 Passing configure arguments ------------------------------- Configure options for rjags are passed via the --configure-args argument to R CMD INSTALL: R CMD INSTALL --configure-args='--with-jags...' or, if you are using the install.packages() function from an R session, using the configure.args argument: install.packages("rjags", configure.args="--with-jags...") If configure arguments are set, they always override the corresponding environment variables.