[d69a19]: doc / manual / jags_installation_manual.tex Maximize Restore History

Download this file

jags_installation_manual.tex    672 lines (570 with data), 27.2 kB

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
\documentclass[11pt, a4paper, titlepage]{article}
\usepackage{amsmath}
\usepackage{a4wide}
\usepackage{url}
\usepackage{multirow}
\usepackage{amsfonts}
\newcommand{\release}{3.4.0}
\newcommand{\JAGS}{\textsf{JAGS}}
\newcommand{\BUGS}{\textsf{BUGS}}
\newcommand{\WinBUGS}{\textsf{WinBUGS}}
\newcommand{\R}{\textsf{R}}
\newcommand{\CODA}{\textsf{coda}}
\usepackage{verbatim}
\newcommand{\code}[1]{{\bgroup{\normalfont\ttfamily #1}\egroup}}
\newcommand{\samp}[1]{{`\bgroup\normalfont\texttt{#1}'\egroup}}
\newcommand{\file}[1]{{`\normalfont\textsf{#1}'}}
\let\command=\code
\let\option=\samp
\begin{document}
\title{JAGS Version \release\ installation manual}
\author{Martyn Plummer \and Bill Northcott}
\date{30 August 2013}
\maketitle
\JAGS\ is distributed in binary format for Microsoft Windows, Mac OS
X, and most Linux distributions. The following instructions are for
those who wish to build \JAGS\ from source. The manual is divided
into three sections with instructions for Linux/Unix, Mac OS X, and Windows.
\section{Linux and UNIX}
\JAGS\ follows the usual GNU convention of
\begin{verbatim}
./configure
make
make install
\end{verbatim}
which is described in more detail in the file \texttt{INSTALL} in
the top-level source directory. On some UNIX platforms, you may
be required to use GNU make (gmake) instead of the native make
command. On systems with multiple processors, you may use the option
\option{-j} to speed up compilation, {\em e.g.} for a quad-core PC you
may use:
\begin{verbatim}
make -j4
\end{verbatim}
\subsection{Configure options}
At configure time you also have the option of defining options such
as:
\begin{itemize}
\item The names of the C, C++, and Fortran compilers.
\item Optimization flags for the compilers. \JAGS\ is optimized by
default if the GNU compiler (gcc) is used. If you are using another
compiler then you may need to explicitly supply optimization flags.
\item Installation directories. \JAGS\ conforms to the GNU standards
for where files are installed. You can control the installation
directories in more detail using the flags that are listed when
you type \command{./configure --help}.
\end{itemize}
\subsubsection{Configuration for a 64-bit build}
By default, JAGS will install all libraries into
\file{/usr/local/lib}. If you are building a 64-bit version of \JAGS,
this may not be appropriate for your system. On Fedora and other
RPM-based distributions, for example, 64-bit libraries should be
installed in \file{lib64}, and on Solaris, 64-bit libraries are in a
subdirectory of \file{lib} ({\em e.g.} \file{lib/amd64} if you are
using a x86-64 processor), whereas on Debian, and other Linux
distributions that conform to the FHS, the correct installation
directory is \file{lib}.
To ensure that \JAGS\ libraries are installed in the correct
directory, you should supply the \option{--libdir} argument to the
configure script, {\em e.g.}:
\begin{verbatim}
./configure --libdir=/usr/local/lib64
\end{verbatim}
It is important to get the installation directory right when using the
\texttt{rjags} interface between R and \JAGS, otherwise the
\texttt{rjags} package will not be able to find the \JAGS\ library.
\subsubsection{Configuration for a private installation}
If you do not have administrative privileges, you may wish to install
\JAGS\ in your home directory. This can be done with the following
configuration options
\begin{verbatim}
export JAGS_HOME=$HOME/jags #or wherever you want it
./configure --prefix=$JAGS_HOME
\end{verbatim}
For more detailed control over the installation directories type
\begin{verbatim}
./configure --help
\end{verbatim}
and read the section ``Fine-tuning of the installation directories.''
With a private installation, you need to modify your PATH environment
variable to include \file{\$JAGS\_HOME/bin}. You may also need to set
\code{LD\_LIBRARY\_PATH} to include \file{\$JAGS\_HOME/lib} (On Linux this
is not necessary as the location of libjags and libjrmath is hard-coded
into the \JAGS\ binary).
\subsection{BLAS and LAPACK}
\label{section:blas:lapack}
BLAS (Basic Linear Algebra System) and LAPACK (Linear Algebra Pack)
are two libraries of routines for linear algebra. They are used by the
multivariate functions and distributions in the \texttt{bugs} module.
Most unix-like operating system vendors supply shared libraries that
provide the BLAS and LAPACK functions, although the libraries may not
literally be called ``blas'' and ``lapack''. During configuration, a
default list of these libraries will be checked. If \texttt{configure}
cannot find a suitable library, it will stop with an error message.
You may use alternative BLAS and LAPACK libraries using the configure
options \texttt{--with-blas} and \texttt{--with-lapack}
\begin{verbatim}
./configure --with-blas="-lmyblas" --with-lapack="-lmylapack"
\end{verbatim}
If the BLAS and LAPACK libraries are in a directory that is not on the
default linker path, you must set the \code{LDFLAGS} environment variable
to point to this directory at configure time:
\begin{verbatim}
LDFLAGS="-L/path/to/my/libs" ./configure ...
\end{verbatim}
At runtime, if you have linked \JAGS\ against BLAS or LAPACK in
a non-standard location, you must supply this location with the
environment variable \code{LD\_LIBRARY\_PATH}, {\em e.g.}
\begin{verbatim}
LD_LIBRARY_PATH="/path/to/my/libs:${LD_LIBRARY_PATH}"
\end{verbatim} %$
Alternatively, you may hard-code the paths to the blas and lapack
libraries at compile time. This is compiler and platform-specific,
but is typically achieved with
\begin{verbatim}
LDFLAGS="-L/path/to/my/libs -R/path/to/my/libs
\end{verbatim}
\subsubsection{Multithreaded BLAS and LAPACK}
\label{section:blas:multithreaded}
Some high-performance computing libraries offer multi-threaded
versions of the BLAS and LAPACK libraries. Although instructions for
linking against some of these libraries are given below, this should
not be taken as encouragement to use multithreaded BLAS. Testing
shows that using multiple threads in BLAS can lead to significantly
{\em worse} performance while using up substantially more computing
resources.
\subsection{GNU/Linux}
\label{section:gnulinux}
GNU/Linux is the development platform for \JAGS, and a variety of
different build options have been explored, including the use of
third-party compilers and linear algebra libraries.
\subsubsection{Fortran compiler}
The GNU FORTRAN compiler changed between gcc 3.x and gcc 4.x from
\code{g77} to \code{gfortran}. Code produced by the two compilers is
binary incompatible. If your BLAS and LAPACK libraries are linked
against \code{libgfortran}, then they were built with \code{gfortran}
and you must also use this to compile \JAGS.
Most recent GNU/Linux distributions have moved completely to gcc 4.x.
However, some older systems may have both compilers installed.
Unfortunately, if \code{g77} is on your path then the configure script
will find it first, and will attempt to use it to build \JAGS. This
results in a failure to recognize the installed BLAS and LAPACK
libraries. In this event, set the \code{F77} variable at configure time.
\begin{verbatim}
F77=gfortran ./configure
\end{verbatim}
\subsubsection{BLAS and LAPACK}
The {\bf BLAS} and {\bf LAPACK} libraries from Netlib
(\url{http://www.netlib.org}) should be provided as part of your Linux
distribution. If your Linux distribution splits packages into ``user''
and ``developer'' versions, then you must install the developer
package ({\em e.g.} \texttt{blas-devel} and \texttt{lapack-devel}).
{\bf Suse Linux Enterprise Server (SLES)} does not include BLAS and
LAPACK in the main distribution. They are included in the SLES SDK, on
a set of CD/DVD images which can be downloaded from the Novell web
site. See \url{http://developer.novell.com/wiki/index.php/SLES_SDK}
for more information.
\subsubsection{ATLAS}
On Fedora Linux, pre-compiled atlas libraries are available via the
\texttt{atlas} and \texttt{atlas-devel} RPMs. These RPMs install the
atlas libraries in the non-standard directory \texttt{/usr/lib/atlas}
(or \texttt{/usr/lib64/atlas} for 64-bit builds) to avoid conflicts
with the standard \texttt{blas} and \texttt{lapack} RPMs. To use the
atlas libraries, you must supply their location using the
\code{LDFLAGS} variable (see section \ref{section:blas:lapack})
\begin{verbatim}
./configure LDFLAGS="-L/usr/lib/atlas"
\end{verbatim}
Runtime linking to the correct libraries is ensured by the automatic
addition of \texttt{/usr/lib/atlas} to the linker path (see the directory
\texttt{/etc/ld.so.conf.d}), so you do not need to set the
environment variable \code{LD\_LIBRARY\_PATH} at run time.
\subsubsection{AMD Core Math Library}
\label{section:acml:linux}
The AMD Core Math Library (acml) provides optimized BLAS and LAPACK
routines for AMD processors. To link \JAGS\ with \texttt{acml}, you must
supply the \texttt{acml} library as the argument to \texttt{--with-blas}.
It is not necessary to set the \texttt{--with-lapack} argument
as \texttt{acml} provides both sets of functions. See also
section~\ref{section:blas:lapack} for run-time instructions.
For example, to link to the 64-bit acml using gcc 4.0+:
\begin{verbatim}
LDFLAGS="-L/opt/acml4.3.0/gfortran64/lib" \
./configure --with-blas="-lacml -lacml_mv"
\end{verbatim}
The \code{acmv\_mv} library is a vectorized math library that
exists only for the 64-bit version and is omitted when linking against
32-bit acml.
On multi-core systems, you may wish to use the threaded acml library
(See the warning in section \ref{section:blas:multithreaded} however).
To do this, link to \code{acml\_mp} and add the compiler flag
\option{-fopenmp}:
\begin{verbatim}
LDFLAGS="-L/opt/acml4.3.0/gfortran64_mp/lib" \
CXXFLAGS="-O2 -g -fopenmp" ./configure --with-blas="-lacml_mp -lacml_mv"
\end{verbatim}
The number of threads used by multi-threaded acml may be controlled
with the environment variable \code{OMP\_NUM\_THREADS}.
\subsubsection{Intel Math Kernel Library}
The Intel Math Kernel library (MKL) provides optimized BLAS and LAPACK
routines for Intel processors. MKL is designed to be linked to
executables, not shared libraries. This means that it can only be
linked to a static version of \JAGS, in which the \JAGS\ library and
modules are linked into the main executable. To build a static version
of \JAGS, use the configure option \option{--disable-shared}.
MKL version 10.0 and above uses a ``pure layered'' model for linking.
The layered model gives the user fine-grained control over four
different library layers: interface, threading, computation, and
run-time. Some examples of linking to MKL using this layered model are
given below. These examples are for GCC compilers on
\code{x86\_64}. The choice of interface layer is important on
\code{x86\_64} since the Intel Fortran compiler returns complex values
differently from the GNU Fortran compiler. You must therefore use the
interface layer that matches your compiler (\code{mkl\_intel*} or
\code{mkl\_gf*}).
For further guidance, consult the MKL Link Line advisor at
\url{http://software.intel.com/en-us/articles/intel-mkl-link-line-advisor}.
Recent versions of MKL include a shell script that sets up the
environment variables necessary to build an application with MKL.
\begin{verbatim}
source /opt/intel/composerxe-2011/mkl/bin/mklvars.sh intel64
\end{verbatim}
After calling this script, you can link \JAGS\ with a sequential
version of MKL as follows:
\begin{verbatim}
./configure --disable-shared \
--with-blas="-lmkl_gf_lp64 -lmkl_sequential -lmkl_core -lpthread"
\end{verbatim}
Note that \code{libpthread} is still required, even when linking
to sequential MKL.
Threaded MKL may be used with:
\begin{verbatim}
./configure --disable-shared \
--with-blas="-lmkl_gf_lp64 -lmkl_gnu_thread -lmkl_core -liomp5 -lpthread"
\end{verbatim}
The default number of threads will be chosen by the OpenMP software,
but can be controlled by setting \code{OMP\_NUM\_THREADS} or
\code{MKL\_NUM\_THREADS}. (See the warning in section
\ref{section:blas:multithreaded} however).
\subsubsection{Using Intel Compilers}
\JAGS\ has been successfully built with the Intel Composer XE
compilers. To set up the environment for using these compilers call
the \file{compilervars.sh} shell script, {\em e.g.}
\begin{verbatim}
source /opt/intel/composerxe-2011/bin/compilervars.sh intel64
\end{verbatim}
Then call the configure script with the Intel compilers:
\begin{verbatim}
CC=icc CXX=icpc F77=ifort ./configure
\end{verbatim}
\subsubsection{Using Clang}
\JAGS\ has been built with the clang compiler for C and C++ (version 3.1).
The configuration was
\begin{verbatim}
LD="llvm-ld" CC="clang" CXX="clang++" ./configure
\end{verbatim}
In this configuration, the gfortran compiler was used for Fortran and
the C++ code was linked to the GNU standard C++ library (libstdc++)
rather than the version supplied by the LLVM project (libc++).
\subsection{Solaris}
\JAGS\ has been successfully built and tested on the Intel x86
platform under Solaris 11 using the Sun Studio 12.3 compilers.
\begin{verbatim}
./configure CC=cc CXX=CC F77=f95 \
CFLAGS="-xO3 -xarch=sse2" \
FFLAGS="-xO3 -xarch=sse2" \
CXXFLAGS="-xO3 -xarch=sse2"
\end{verbatim}
The Sun Studio compiler is not optimized by default. Use the option
\option{-xO3} for optimization (NB This is the letter ``O'' not the
number 0) In order to use the optimization flag \option{-xO3} you
must specify the architecture with the \option{-xarch} flag. The options
above are for an Intel processor with SSE2 instructions. This must be
adapted to your own platform.
To compile a 64-bit version of JAGS, add the option \option{-m64} to
all the compiler flags.
Solaris provides two versions of the C++ standard library:
\texttt{libCstd}, which is the default, and \texttt{libstlport4},
which conforms more closely to the C++ standard. \JAGS\ may be linked
to the stlport4 library by adding the option
\option{-library=stlport4} to \code{CXXFLAGS}.
The configure script automatically detects the Sun Performance library,
which implements the BLAS/LAPACK functions.
\clearpage
\section{Mac OS X}
There have been big changes in Apple's developer tools in the last
couple of years. Currently (this may change at any time) the core
suite of tools are contained in Xcode. This is now a single app,
which contains the command line tools in
\file{Xcode.app/Contents/Developer/usr}, instead of installing them in
\file{/usr} as was the previous arrangement. The most recent version
of Xcode (4.5) can be downloaded free from the App Store. This
version will only run on Lion 10.7.x and Mountain Lion 10.8.x. If you
are trying to build on an earlier version of MacOS, you will need to
download an older version of Xcode from the Mac Dev Center at
\url{http://developer.apple.com}. This is no longer free. You will
need to sign up on the Mac Developer Program which costs \$99 per
year. The program gives you access to many more resources including
an Apple signed developer certificate which can be used to sign your
code. The instructions that follow assume you are using MacOS 10.7 or
10.8 and have the free Xcode from the App Store.
\subsection{Required tools}
If you wish to build from a released source package
i.e. \file{JAGS-\release.tar.gz}, you will need Xcode and the gfortran
package which you can find by following the ``tools directory'' link
on the ``R for Mac OS X'' page on CRAN. You will also need to install
the command line tools into /usr. This is done within Xcode from
Preferences $\rightarrow$ Downloads $\rightarrow$ Components. This
setup should be able to build the \JAGS\ sources and also source
packages in R. All the necessary libraries such as BLAS and LAPACK
are included in the standard MacOS install.
\subsection{Prepare the source code}
Move the downloaded \file{JAGS-X.X.X.tar.gz} package to some suitable
working space on your disk and double click the file. This will
decompress the package to give a folder called \file{JAGS-X.X.X},
where `X.X.X' is the version number. Open the Terminal app from
/Applications/Utilities. This gives you a UNIX shell know as bash.
In the Terminal window after the \$ prompt type 'cd' followed by a
space. In the Finder drag JAGS-X.X.X folder into the Terminal window
and hit return. If this worked for you, typing 'ls' followed by a
return will list the contents of the JAGS folder.
\subsection{Set up the environment}
Executable files on MacOS can contain code for more than one CPU
architecture: i386, x86\_64 or ppc. Executables with more than one
architecture are described as 'fat.' The instructions below will build
a fat binary of JAGS containing 32-bit i386 and 64-bit x86\_64 code
which will run on 10.6, 10.7 and 10.8. This is compatible with
current CRAN distributions of R and the rjags module.
In your Terminal window type the following instructions which set up
the environment for the build. (Note that there is no space after
'platform' and the '$\backslash$' must not be followed by any spaces)
\begin{verbatim}
export CC=/usr/bin/clang
export CXX=/usr/bin/clang++
export CFLAGS="-g -Os -mmacosx-version-min=10.6 -isysroot \
/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform\
/Developer/SDKs/MacOSX10.8.sdk \
-arch i386 -arch x86_64"
export CXXFLAGS="-g -Os -mmacosx-version-min=10.6 -isysroot \
/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform\
/Developer/SDKs/MacOSX10.8.sdk \
-arch i386 -arch x86_64"
export FFLAGS="-g -Os -mmacosx-version-min=10.6 -isysroot \
/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform\
/Developer/SDKs/MacOSX10.8.sdk -arch i386 -arch x86_64"
export LDFLAGS="-mmacosx-version-min=10.6 -arch i386 -arch x86_64"
\end{verbatim}
\subsection{Configuration}
To configure the package type:
\begin{verbatim}
../configure --disable-dependency-tracking --with-included-ltdl
\end{verbatim}
This instruction should complete without reporting an error.
\subsection{Compile}
To compile the code type:
\begin{verbatim}
make -j 8
\end{verbatim}
The number '8' indicates the number of build threads that should be
run. In general this is best as twice the number of CPU cores in the
computer. Most current Macs have four core CPUs. If your machine is
different, you may want to change the number in the instruction.
Again, this instruction should complete without errors.
\subsection{Install}
Finally to install \JAGS\ you need to be using an account with
administration privileges. Type:
\begin{verbatim}
sudo make install
\end{verbatim}
This will ask for your account password and install the code ready to
run as described in the User Manual.
You need to ensure \texttt{/usr/local/bin} is in your PATH in order
for `jags' to work from a shell prompt.
\subsection{Older versions of MacOS}
For instructions for building on Tiger or for older versions of
\R\ see previous versions of this manual.
\subsection{Tips for developers and advanced users}
\subsubsection{Compilers}
Older versions of Xcode used the gcc compiler suite. Apple abandoned
the gcc project when GPL3 was introduced. Current Apple compilers are
based on LLVM. They are invoked as clang and clang++. Although there
appear to be gcc and gxx, these are actually gcc-llvm with an out of
date gcc 4.2 front end on LLVM. These compilers are now deprecated.
While there are versions of current gcc available for MacOS, they do
not recognise the Apple specific -arch flag. This leads to a number
of problems.
\subsubsection{Developer tools}
Now that Apple do not use gcc, they have no use for many of the
auxiliary GNU tools required to build it. So the Xcode does not
contain any of the autotools (autoconf, automaker and libtool). If
you want to work on code from the \JAGS\ repository, you will need to
build and install these. Other GNU tools like bison and make are
available but may be very out of date because of the GPL3 issue.
Binaries of cvs, subversion and git are included in Xcode, Mercurial
needs to installed separately if required.
\clearpage
\section{Windows}
\label{section: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.
\subsection{Preparing the build environment}
You need to install the following packages
\begin{itemize}
\item The TDM-GCC compiler suite for Windows
\item MSYS
\item NSIS, including the AccessControl plug-in
\end{itemize}
We used the TDM-GCC compilers based on the MinGW-w64 project
(\url{http://tdm-gcc.tdragon.net}). This distribution 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
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). Ensure that you download the
MinGW-w64/sjlj version as this is capable of producing both 32-bit and
64-bit binaries.
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 \file{.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. Download the MinGW
installer from \url{http://www.mingw.org}. We used
\file{mingw-get-inst-20120426.exe}. Run the installer and select
``MSYS Basic System''. There is no need to install the ``MinGW
Developer Toolkit'' if you are working with a release tarball of
\JAGS. It is not necessary to install any of the compilers that come
with MinGW as we shall be using the TDM versions. To make MSYS use the
TDM-compilers, edit the file \file{c:/mingw/msys/1.0/etc/fstab}
to read
\begin{verbatim}
c:\MinGW64\ /mingw
\end{verbatim}
MSYS creates a home directory for you in
\file{c:/mingw/msys/1.0/home/username}, where \code{username} is
your user name under Windows. You will need to copy and paste the
source files for LAPACK and JAGS into this directory.
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.46. You must also install
the AccessControl plug-in for NSIS, which is available from
\url{http://nsis.sourceforge.net/AccessControl_plug-in}. The plug-in
is distributed as a zip file which is unpacked into the installation
directory of NSIS.
\subsubsection{Building LAPACK}
Download the LAPACK source file from
\url{http://www.netlib.org/lapack} to your MSYS home directory. We
used version 3.4.1.
You need to build LAPACK twice: once for 32-bit \JAGS\ and once for
64-bit \JAGS. The instructions below are for 32-bit \JAGS. To build
64-bit versions, repeat the instructions with the flag \option{-m32}
replaced by \option{-m64} and start in a clean build directory. Note
that you cannot cross-build 64-bit BLAS and LAPACK on a 32-bit Windows
system. This is because the build process must run some 64-bit test
programs.
Launch MSYS, labelled as ``MinGW shell'' on the Windows Start Menu,
and unpack the tarball.
\begin{verbatim}
tar xfvz lapack-3.4.1.tgz
cd lapack-3.4.1
\end{verbatim}
Copy the file \file{INSTALL/make.inc.gfortran} to \file{make.inc} in
the top level source directory. Then edit \file{make.inc} replacing
the following lines:
\begin{verbatim}
FORTRAN = gfortran -m32
LOADER = gfortran -m32
\end{verbatim}
Type
\begin{verbatim}
make blaslib
make lapacklib
\end{verbatim}
The compilation process is slow. Eventually, it will create two static
libraries \file{librefblas.a} and \file{liblapack.a}. These are
insufficient for building \JAGS: you need to create dynamic link
library (DLL) for each one.
First create a definition file \file{libblas.def} that exports all the
symbols from the BLAS library
\begin{verbatim}
dlltool -z libblas.def --export-all-symbols librefblas.a
\end{verbatim}
Then link this with the static library to create a DLL
(\file{libblas.dll}) and an import library (\file{libblas.dll.a})
\begin{verbatim}
gcc -m32 -shared -o libblas.dll -Wl,--out-implib=libblas.dll.a \
libblas.def librefblas.a -lgfortran
\end{verbatim}
Repeat the same steps for the LAPACK library, creating an import library
(\file{liblapack.dll.a}) and DLL (\file{liblapack.dll})
\begin{verbatim}
dlltool -z liblapack.def --export-all-symbols liblapack.a
gcc -m32 -shared -o liblapack.dll -Wl,--out-implib=liblapack.dll.a \
liblapack.def liblapack.a -L./ -lblas -lgfortran
\end{verbatim}
\subsection{Compiling \JAGS}
Unpack the JAGS source
\begin{verbatim}
tar xfvz JAGS-3.3.0.tar.gz
cd JAGS-3.3.0
\end{verbatim}
and configure JAGS for a 32-bit build
\begin{verbatim}
CC="gcc -m32" CXX="g++ -m32" F77="gfortran -m32" \
./configure LDFLAGS="-L/path/to/import/libs/ -Wl,--enable-auto-import"
\end{verbatim}
where \file{/path/to/import/libs} is a directory that contains the
32-bit import libraries (\file{libblas.dll.a} and
\file{liblapack.dll.a}). This must be an {\em absolute} path name,
and not relative to the JAGS build directory.
After the configure step, type
\begin{verbatim}
make win32-install
\end{verbatim}
This will install JAGS into the subdirectory \file{win/inst32}.
Note that you must go straight from the configure step to \texttt{make
win32-install} without the usual step of typing \texttt{make} on
its own. The \texttt{win32-install} target resets the installation
prefix, and this will cause an error if the source is already
compiled.
To install the 64-bit version, clean the build directory
\begin{verbatim}
make clean
\end{verbatim}
reconfigure JAGS for a 64-bit build:
\begin{verbatim}
CC="gcc -m64" CXX="g++ -m64" F77="gfortran -m64" \
./configure LDFLAGS="-L/path/to/import/libs/ -Wl,--enable-auto-import"
\end{verbatim}
Then type
\begin{verbatim}
make win64-install
\end{verbatim}
This will install JAGS into the subdirectory \file{win/inst64}.
With both 32-bit and 64-bit installations in place you can create the
installer. Normally you will want to distribute the blas and lapack
libraries with JAGS. In this case, put the 32-bit DLLs and import
libraries in the sub-directory \file{win/runtime32} and the 64-bit
DLLs and import libraries in the sub-directory
\file{win/runtime64}. They will be detected and included with the
distribution.
Make sure that the file \file{makensis.exe}, provided by
NSIS, is in your PATH. For a typical installation of NSIS, on 64-bit
windows:
\begin{verbatim}
PATH=$PATH:/c/Program\ files\ \(x86\)/NSIS
\end{verbatim}
Then type
\begin{verbatim}
make installer
\end{verbatim}
After the build process finishes, the self extracting archive will be
in the subdirectory \file{win}.
\end{document}