Diff of /README [85cf30] .. [9e9fb5]  Maximize  Restore

Switch to side-by-side view

--- a/README
+++ b/README
@@ -1,60 +1,117 @@
+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.
 
-Windows
--------
+1 Windows
+---------
 
-At compile time, there is no way for Windows to guess where the JAGS
-library is installed, so you must supply the location yourself using
-the make variable JAGS_ROOT, defining it in the file HOME/.R/Makevars.win
+If you are installing the Windows binary rjags package, then R will
+consult the Windows registry to find the location of JAGS.
 
-JAGS_ROOT=c:\Program Files\JAGS\JAGS-3.1.0
+If you are compiling the rjags package from source then you must
+supply the location of JAGS yourself using the make variable
+JAGS_ROOT, defining it in the file HOME/.R/Makevars.win, e.g.
 
-Unix
-----
+JAGS_ROOT=c:\Program Files\JAGS\JAGS-3.3.0
+
+2 Unix/Linux
+------------
 
 The configure script will try to guess the location of the JAGS
-library installation. It will look in /<prefix>/<lib>, where
+library. It does this by querying the R and jags executables, and
+should work if both are on your PATH.
 
-- <prefix> is the determined from the location of the jags
-  script that launches the command line interface.
+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.
 
-  For example, if this is "/usr/local/bin/jags", then prefix will
-  be "/usr/local"
+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).
 
-- <lib> is derived from the value of "LIBnn", returned by 
-  "R CMD config LIBnn".
+The options/environment variables correspond to options that were
+used when JAGS was installed. They are shown in the table below:
 
-  This is particularly important on 64-bit unix, where R is 
-  installed by default in /usr/local/lib64 and LIBnn is "lib64"
+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
 
-The configure script will also look for JAGS headers in
-/<prefix>/include/JAGS
+By default LIBnn is the value returned by `R CMD config LIBnn`.
+This can be overridden by setting the environment variable LIBnn.
 
-If the configure script fails to find the JAGS headers or library,
-you can set the environment variables JAGS_INCLUDE and JAGS_LIB
-to point to the correct directory.
+Example 1
+---------
 
-Alternatively, you can use the configure options
+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.
 
---with-jags-include=/path/to/jags/headers 
-                    (default /usr/local/include/JAGS)
+Alternatively you can set the environment variable JAGS_PREFIX
+before building rjags:
 
---with-jags-lib=/path/to/jags/library
-                (default /usr/local/[lib|lib64])
+export JAGS_PREFIX=/opt
 
-These options are onto the rjags configure script with:
-"R CMD INSTALL --configure-args='--with-jags...'
+Example 2
+---------
 
-Exceptionally, you may need to set the location of the JAGS modules.
-But this will only be necessary if you reset moddir when installing
-JAGS. This can be done by setting the environment variabel JAGS_MODULES
-or by using the configure option
+Suppose you are on a 64-bit system and installed the JAGS library in
+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.
 
---with-jags-modules=/path/to/jags/modules
-                    (default /usr/local/[lib|lib64]/JAGS/modules-w.y.z)
-                     where w.y.z is the version number of JAGS
+Alternatively you can set the environment variable JAGS_LIBDIR
+before building rjags:
 
+export JAGS_LIBDIR=/usr/local/lib64
 
+or set the variable LIBnn
 
+export LIBnn=lib64
+
+2.1 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, using the install.packages() function from within R, using
+the configure.args argument:
+
+  install.packages("rjags", configure.args="--with-jags...")
+
+If configure arguments are set, they always override the corresponding
+environment variables.
+
+2.2 Failure to load 
+-------------------
+
+Even with the above options, the rjags package may compile and install
+correctly, but then fail with the message "ERROR:loading failed".
+
+On some systems it is possible to hard-code the location of the JAGS
+library at compile time so that the linker knows where to look. This
+can be done by adding the configure argument --enable-rpath, e.g.
+
+R CMD INSTALL --configure-args="--prefix=/opt --enable-rpath" rjags
+
+However, please note that this is not portable and may not work on
+your system. In this case you need to set the environment variable
+LD_LIBRARY_PATH to include the directory containing the jags libraries
+before starting R, e.g
+
+LD_LIBRARY_PATH=/opt/lib:$LD_LIBRARY_PATH
+export LD_LIBRARY_PATH