
Content
=======

1) How to compile MrBayes from source
2) Configuration options
3) Troubleshooting for Mac
4) Tips for Windows
5) Further references


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

Pre-requirements:
* gcc (or other C compiler)
* autotools (autoconf, automake, etc)
* optional: MPI compiler and library
* optional: BEAGLE library

Compilation: 
To compile MrBayes in UNIX-like environments, first navigate to the folder containing
the source code, then execute the following commands in your terminal (without '>'):

> 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 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 install the library from 
"https://code.google.com/p/beagle-lib", or disable the use of the library with option
"--with-beagle=no", i.e. 

> ./configure --with-beagle=no

Note: without BEAGLE library MrBayes may run slower. For more instructions, please see
https://code.google.com/p/beagle-lib/

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 with 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 option "--enable-mpi=yes".
The MPI code can be used 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 with 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).

4) Debugging
For testing or developing purpose, you may need to compile a debugging version by 
invoking the configure script with the option "--enable-debug=yes", i.e.

> ./configure --enable-debug=yes


Troubleshooting for Mac
=======================

Problem: > autoconf: command not found

Solution: Xcode 4.5 or later 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, see below.

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

Solution: Install newer command line tools (e.g., in Xcode 5 or higher), or install a 
different gcc version for Mac using HomeBrew, see below.

-----------------------
To install missed Unix tools, we recommend using HomeBrew (http://brew.sh). Follow the
instructions on HomeBrew's homepage to install it on Mac.
Other options include MacPorts (http://www.macports.org), GNU (http://www.gnu.org),
and Open MPI (http://open-mpi.org).

To install autoconf and automake after having installed HomeBrew, use:

> brew install autoconf
> brew install automake

To install the most recent version of openmpi, use:

> brew install openmpi

Simply, you can directly install MrBayes using HomeBrew:

> brew tap homebrew/science
> brew install mrbayes

The dependent formulas will be installed simultaneously. To enable MPI and BEAGLE, use:

> brew install mrbayes --with-beagle --with-mpi

To uninstall mrbayes, use:

> brew uninstall mrbayes

To install an alternative gcc (not recommended), use the following commands:

> brew install gcc

After installation, you might 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-old
> sudo ln -s /usr/local/bin/gcc-4.9 /usr/bin/gcc


Tips for Windows
================
To compile MrBayes in Windows is relatively not straightforward. You can use Microsoft 
Visual Studio to open and build one of the projects in the "projects" folder, after
downloading all the files from SourceForge (e.g., Download Snapshot).
http://sourceforge.net/p/mrbayes/code/HEAD/tree/

Here we introduce another way to compile using MinGW (http://www.mingw.org/). You need
to download the installer "mingw-get-setup.exe" and install it in Windows. Then open 
"MinGW Installation Manager" you just installed. Click the square before "mingw32-base" 
under "Basic Setup" and choose "Mark for Installation", then choose "Apply Changes" from
the "Installation" menu. 

Additionally, add "C:\MinGW\bin" (path to your MinGW installation) to your system path
in setting "Environment Variables" (please Google :))

Open Command Prompt (cmd.exe), "cd" to the src folder you just downloaded, e.g., 

> cd Downloads\MrBayes\trunk\src

and use the following command to compile:

> gcc -O3 -DNDEBUG -o mb bayes.c command.c model.c mcmc.c likelihood.c proposal.c sumpt.c utils.c best.c mbbeagle.c -lm

An executable named "mb.exe" will be generated in the same folder, if everything
goes smoothly. You may want to edit the fist few lines in bayes.h to define/undef
some macros (SSE_ENABLED, etc).


Further references
==================

See the manual for more compilation/installation instructions.
