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 macOS

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

The configure script uses pkg-config 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 macOS
-----------------------------

Installation on macOS is similar to the case on Unix/Linux, although
the process is streamlined for compatibility with the official macOS
installer of JAGS. This allows rjags to be installed on macOS without
the need for any additional dependencies (other than pkg-config) or
setting any environmental variables (including PKG_CONFIG_PATH).
It also allows for switching between installations of different
major versions of rjags (e.g. between rjags_4-x and rjags_5-x)
without needing to re-install JAGS, assuming that an official macOS
binary of JAGS 4.x.y is present on your system.