Diff of /doc/manual/jags_installation_manual.tex [1ca215] .. [d46227] Maximize Restore

  Switch to side-by-side view

--- a/doc/manual/jags_installation_manual.tex
+++ b/doc/manual/jags_installation_manual.tex
@@ -456,7 +456,7 @@
 \section{Windows}
 \label{section:windows}
 
-These instructions use MinGW, The Minimalist GNU system for Windows.
+These instructions use MinGW, the Minimalist GNU system for Windows.
 You need some familiarity with Unix in order to follow the build
 instructions but, once built, \JAGS\ can be installed on any PC
 running windows, where it can be run from the Windows command prompt.
@@ -465,27 +465,35 @@
 
 You need to install the following packages
 \begin{itemize}
-\item MinGW 
+\item The TDM-GCC compiler suite for Windows
 \item MSYS  
 \item NSIS, including the AccessControl plug-in  
 \end{itemize}
 
 MinGW (Minimalist GNU for Windows) is a build environment for Windows.
-There is an official release from \url{http://www.mingw.org}.
-However, we used the MinGW distribution that comes as part of the R
-tools for windows (\url{http://www.murdoch-sutherland.com/Rtools}),
-since the compilers in this distribution match the compilers used to
-build the binary distribution of R for windows, as well as the R
-packages distributed via CRAN (\url{http://cran.r-project.org}).
-We used version 2.12 of \verb+Rtools+.  
+There is an official release from \url{http://www.mingw.org}.  However,
+we used the TDM-GCC distribution (\url{http://tdm-gcc-tdragon.net}).
+This distribution, which also includes 64-bit compilers from the
+MinGW-w64 project, was chosen because it allows us to build a version of
+JAGS that is statically linked against the gcc runtime library.  This,
+in turn, is necessary to have a functional rjags package on windows.
+We also tried the official MinGW distribution, and version 212 of Rtools
+(\url{http://www.murdoch-sutherland.com/Rtools}). Although the resulting
+JAGS library is functional, it is not compatible with R: loading the
+rjags package causes R to crash on exit.
+
+TDM-GCC has a nice installer, available from sourceforge (follow the
+links on the main TDM-GCC web site). Select a ``Recommended C/C++''
+installation and customize it by selecting the fortran compiler, which
+is not installed by default. After installation, to force the compiler
+to use static linking, delete any import libraries (files ending in
+\verb+.dll.a+) in the TDM-GCC tree.
 
 MSYS (the Minimal SYStem) is part of the MinGW project. It provides a
 bash shell for you to build Unix software. These instructions were
-tested with MSYS 1.0.10, the last version of MSYS to be bundled with a
+tested with MSYS 1.0.11, the last version of MSYS to be bundled with a
 Windows installer.  The installer can be downloaded from
-\url{http://sourceforge.net/projects/mingw/files}.  At the end of the
-installation process, it will launch a post-install script that will
-allow you to use MSYS in conjunction with MinGW.
+\url{http://sourceforge.net/projects/mingw/files}.  
 
 MSYS creates a home directory for you in
 \verb+c:\msys\<version>\home\<username>+, where \texttt{<version>} is
@@ -496,18 +504,18 @@
 The Nullsoft Scriptable Install System
 (\url{http://nsis.sourceforge.net}) allows you to create a
 self-extracting executable that installs \JAGS\ on the target PC.
-These instructions were tested with NSIS 2.33.  You must also install
+These instructions were tested with NSIS 2.46.  You must also install
 the AccessControl plug-in for NSIS, which is available from
 \url{http://nsis.sourceforge.net/AccessControl_plug-in}.
 
 \subsubsection{Building LAPACK}
 
 Download the LAPACK source file from
-\url{http://www.netlib.org/lapack}. We used version 3.2.1, which is
+\url{http://www.netlib.org/lapack}. We used version 3.2.2, which is
 packaged as \verb+lapack.tgz+. Unpack the file in your home directory.
 \begin{verbatim}
 tar xfvz lapack.tgz
-cd lapack-3.2.1
+cd lapack-3.2.2
 \end{verbatim}
 Copy the file \texttt{INSTALL/make.inc.gfortran} to \texttt{make.inc} in
 the top level source directory.  Then edit \texttt{make.inc},
@@ -545,8 +553,6 @@
 gcc -shared -o libblas.dll -Wl,--out-implib=libblas.dll.a \
 libblas.def blas_MinGW.a -lgfortran
 \end{verbatim}
-(If using gcc 3.4, the library should be linked with \verb+-lg2c+ 
-instead of \verb+-lgfortran+)
  
 Repeat the same steps for the LAPACK library, creating an import library
 (\verb+liblapack.dll.a+) and DLL (\verb+liblapack.dll+)
@@ -561,11 +567,11 @@
 Unpack the JAGS source
 \begin{verbatim}
 tar xfvz JAGS-2.2.0.tar.gz
-cd JAGS-2.0.0
+cd JAGS-2.2.0
 \end{verbatim}
 and configure JAGS
 \begin{verbatim}
-./configure LDFLAGS="-L/path/to/import/libs/" 
+./configure LDFLAGS="-L/path/to/import/libs/ -Wl,--enable-auto-import" 
 \end{verbatim}
 where \verb+/path/to/import/libs+ is a directory that contains the
 import libraries (\verb+libblas.dll.a+ and \verb+liblapack.dll.a+).
@@ -578,7 +584,7 @@
 with the distribution.
 
 Make sure that the file \verb+makensis.exe+, provided by NSIS, is in
-your PATH. For a typical installation of NSIS:
+your PATH. For a typical installation of NSIS, on 32-bit windows:
 \begin{verbatim}
 PATH=$PATH:/c/Program\ files/NSIS
 \end{verbatim}
@@ -586,7 +592,8 @@
 \begin{verbatim}
 make win32-installer
 \end{verbatim}
-The self extracting archive will be in the subdirectory \verb+win+.
+After the build process finishes, the self extracting archive will be
+in the subdirectory \verb+win+.
 
 Note that you must go straight from the configure step to \texttt{make
   win32-installer} without the usual step of typing \texttt{make} on
@@ -597,54 +604,29 @@
 \subsection{Building on 64-bit windows}
 
 The build instructions for 64-bit windows are similar
-to the instructions for 32-bit windows. Release 212 of
-Rtools includes 64-bit compilers from the MinGW-w64 project
+to the instructions for 32-bit windows.  The TDM-GCC distribution also
+includes 64-bit compilers from the MinGW-w64 project
 (\url{http://www.sourceforge.net/projects/mingw-w64}).  These are actually
 cross-compilers. They will run under MSYS -- which is still 32-bit --
 but will produce 64-bit code.
 
-If you use another distribution of MinGW-w64 you need to be careful about
-dynamic linking.  Most binary distributions of MinGW-w64 use dynamic
-linking to runtime libraries. This is inconvenient, as it means that the
-required runtime libraries must be distributed with JAGS. Failure to
-do so will either result in an installation that is either completely
-non-functional or will crash.  To force the compiler to use static
-linking, delete any import libraries (files ending in \verb+.dll.a+).
-Note that there is currently no way to avoid dynamic linking to the gcc
-runtime library (see below).
-
-In order to build the BLAS and LAPACK libraries, you need to append the
-prefix \verb+x86_64-w64-mingw32-+ to all the tools. This means you need
-to edit the entries FORTRAN, LOADER, ARCH, and RANLIB in the Makefile,
-as well as modifying the name of \verb+dlltool+ and \verb+gcc+ when
-building the DLLs for BLAS and LAPACK.\footnote{Although we are using
-a cross-compiler, you cannot cross-build 64-bit BLAS and LAPACK on a
-32-bit Windows system. This is because the build process includes compilation
-of test programs which must be run.}
-
-To build \JAGS\ you do not need to edit any makefiles. Just add the
-configure option
+The 64-bit compilers are prefixed with \verb+x86_64-w64-mingw32-+ to
+distinguish them from the 32-bit compilers. When building BLAS and LAPACK
+you need to use the 64-bit version of gfortran by setting the FORTRAN
+and ARCH variables accordingly in the Makefile, and also use
+the 64-bit version of gcc when building the DLLs for BLAS and
+LAPACK. \footnote{Although we are using a cross-compiler, you cannot
+cross-build 64-bit BLAS and LAPACK on a 32-bit Windows system. This is
+because the build process includes compilation of test programs which
+must be run.}
+
+To build 64-bit \JAGS\, just add the configure option
 \begin{verbatim}
 --host=x86_64-w64-mingw32
 \end{verbatim}
-to use the cross-compiler.  You may also wish to add the linker flag
-\begin{verbatim}
-LDFLAGS=-Wl,--enable-auto-import
-\end{verbatim}
-in order to suppress some warnings from the linker, although these
-seem to be harmless.
-
-The \JAGS\ binary built in this way will be dynamically linked to the
-C runtime library \verb+libgcc_s_sjlj-1.dll+, which is part of the
-MinGW-w64 distribution. You will find it in the \texttt{bin}
-directory. You should put a copy of this DLL in the
-\texttt{win/runtime} directory so that it is included in the
-installer.
-
-Finally, in order to build the NSIS installer, you should use the make
+
+Then, to build the NSIS installer, you should use the make
 target \verb+win64-installer+ instead of \verb+win32-installer+.
 
 \end{document}
 
-
-