Diff of /README [599ce0] .. [c6d5fb] Maximize Restore

  Switch to side-by-side view

--- a/README
+++ b/README
@@ -1,60 +1,146 @@
+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, so both
+of these need to be on your PATH for automatic detection to work
+properly.
 
-- <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.
+2.1 Setting the prefix
+----------------------
 
-Alternatively, you can use the configure options
+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.
 
---with-jags-include=/path/to/jags/headers 
-                    (default /usr/local/include/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
 
---with-jags-lib=/path/to/jags/library
-                (default /usr/local/[lib|lib64])
+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.
 
-These options are onto the rjags configure script with:
-"R CMD INSTALL --configure-args='--with-jags...'
+Alternatively you can set the environment variable JAGS_PREFIX
+before building rjags:
 
-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
+export JAGS_PREFIX=/opt
 
---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
+2.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
+
+2.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.
 
 
+2.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.
+
+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
+
+export LD_LIBRARY_PATH=/opt/lib:$LD_LIBRARY_PATH