Content
=======
1) How to compile MrBayes from source
2) Configuration options
3) Troubleshooting compilation problems
4) Further references


How to compile MrBayes from source
==================================

Pre-requirements:

You will need the following software to build MrBayes:
* gcc (or other C++ compiler) (version 4.6 or later)
* autotools (autoconf, automake, etc)
* Optional: MPI compiler and library
* Optional: Beagle library

Compilation: 
For instructions on how to compile MrBayes on a Mac, see below. To compile MrBayes
in other UNIX-like environments, first navigate to the folder containing the source
code. Then execute the following commands in your terminal:

> autoconf
> ./configure 
> make

The compilation will produce an executable in the source directory with the name
"mb". To start the program, simply type

> ./mb

For more convenient access to the program, you may want to install it in your
path, in which case you can invoke the program from any directory on your
computer by simply typing

> mb

If you wish to make the program available to all users in this way, you can use

> sudo make install

after having compiled the program.


Configuration options
=====================

1) BEAGLE

MrBayes 3.2 uses the BEAGLE library by default. You should either install the
BEAGLE library from http://code.google.com/p/beagle-lib/ or disable use of the
library by invoking the configure script with option "--with-beagle=no". i.e. 

> ./configure --with-beagle=no

Note: without beagle library MrBayes may run slower.


2) SSE code

All main-stream modern processors have support for SSE instructions 
which are utilized by default by MrBayes 3.2 in order to substantially speed up
execution. If you experience problems with the SSE code, you can disable the use of
SSE code by invoking the configure script with the option "--enable-sse=no", i.e.

> ./configure --enable-sse=no

If you use SSE code, you may encounter problems with older compilers. Specifically,
if you are getting errors about undefined references to "posix_memalign", you should
update your compiler. You should have libc library of at least version 2.1.91 for
the SSE code to compile.


3) MPI version

To make use of MPI code to parallelize MrBayes computations across several processors
or CPU cores, you should invoke the configure script with the option
"--enable-mpi=yes". The MPI code can be used both together with the Beagle library
and the SSE code. Your computer also needs to have an MPI implementation installed,
for instance OpenMPI or MPICH, and the environment needs to be set up to run MPI
programs. To install an MPI version of MrBayes using BEAGLE and SSE, use:

> autoconf
> ./configure --enable-mpi=yes
> make

The resulting program will be called mb. A typical run might be started with a
command like:

> mpirun -np 8 mb data.nex > output.txt &

This will run MrBayes on eight processors or cores (-np 8), using the data file
"data.nex" as input. The output will not be printed to screen but to the file
"output.txt" (> output.txt). The ampersand (&) causes the control to return
immediately to the console, while the job will continue running in the background.

To examine the most recent output from the run, you might e.g. use the tail command
of UNIX like this:

> tail -f output.txt

This will print the lines onto the screen as they get added to the file "output.txt".
To stop the output, simply press ctrl-C (this will stop the output from the tail
command, it will not stop the MrBayes run).


Compiling on a Mac
==================

The standard modified gcc version (llvm-gcc 4.2) shipping with the latest Xcode is
problematic to compile MrBayes (hangs on model.c). Also, Xcode no longer
ships with autotools, including autoconf that is used by MrBayes and most other
open-source Unix software packages.

To install these tools, we recommend using HomeBrew (http://brew.sh). Other options
include MacPorts (http://www.macports.org), GNU (http://www.gnu.org),
and Open MPI (http://open-mpi.org).

To install version 4.8 of gcc using HomeBrew, use the following commands after 
having installed HomeBrew:

> brew tap homebrew/versions
> brew install gcc48

Check the web for the latest version of gcc. HomeBrew does not allow you to just say
gcc, you need to specify the version number you want. After installation, you need
to redirect the symbolic gcc link in /usr/bin/ to the new version of gcc.
For instance, you can use the following commands:

> sudo mv -i /usr/bin/gcc /usr/bin/gcc-4.2
> sudo ln -s /usr/local/bin/gcc-4.8 /usr/bin/gcc

To install autoconf, use:

> brew install autoconf

To install the most recent version of openmpi, use:

> brew install openmpi --devel

# Use "--devel" flag to install openmpi 1.7, as 1.6 attempts to run llvm-gcc
# instead of clang, but MrBayes 4.2 hangs with llvm-gcc!
# Remove "--devel" when openmpi 1.7 becomes default in the formula

Now you can install the different versions of MrBayes and run the MPI version
of the program as in a standard Unix environment (see above).

Simply, you can even install MrBayes using HomeBrew:

> brew tap homebrew/science
> brew install mrbayes


Troubleshooting compilation problems
====================================

Problem: The compilation process hangs on model.c. For instance, this happens
when using the compiler that currently ships with Xcode (in the command line
tools).

Solution: Install a newer compiler. For instructions on how to install a newer
gcc version for Mac from HomeBrew, see above.


Further references
==================
See the manual for more compilation/installation instructions.
