MrBayes 3.2.7a This document describes how to install the most recent release of MrBayes using Homebrew on macOS, Linux, or on Window subsystem for Linux (WSL). It also describes how to build the development sources of MrBayes from the GitHub repository sources. ======================================================================== Installing MrBayes on macOS using Homebrew ------------------------------------------------------------------------ MrBayes is available for macOS through the Homebrew package manager. See https://brew.sh/ for general information about Homebrew and for Homebrew installation instructions. On a macOS system with Homebrew, MrBayes may be installed through the following two commands in a terminal: brew tap brewsci/bio brew install mrbayes The first command adds the "brewsci/bio" repository to your Homebrew system. This is a Homebrew repository that contains various software related to bioinformatics. Once the repository is available, you install MrBayes with the second command above. This will install MrBayes with support for the Beagle library. If you need additional MPI support, use brew install mrbayes --with-open-mpi This will likely download the neccesary Homebrew packages for building MrBayes with MPI support and then proceed to automatically build and install it on your macOS system (this may take a bit of time). ======================================================================== Installing MrBayes on Linux or WSL using Homebrew ("Linuxbrew") ------------------------------------------------------------------------ The instructions for installing MrBayes on Linux systems are identical to those for installing MrBayes on macOS. It relies on Homebrow being available on the Linux system where it's being installed. Installing Homebrew on Linux is a matter of following the instructions at https://docs.brew.sh/Homebrew-on-Linux We have found that the pre-compiled binaries may not work on all systems and that you may get an "Illegal instruction (core dumped)" error when you try starting MrBayes. In that case, install the MrBayes package from sources instead. This can still be done through Homebrew like this: brew reinstall -s mrbayes Likewise, you may possibly want to compile the Beagle library locally, brew reinstall -s beagle ======================================================================== Installing MrBayes from the GitHub sources on Unix ------------------------------------------------------------------------ Make a shallow clone of the MrBayes repository: git clone --depth=1 https://github.com/NBISweden/MrBayes.git (a shallow clone requires about 27 MB of disk space, a full clone requires about 77 MB) Building MrBayes using the supplied "configure" script: ------------------------------------------------------------------------ To build MrBayes, you will need a C compiler (gcc or clang works well), the "make" utility, and optionally the "pkg-config" utility. MrBayes may also be compiled with support for the Beagle library and for parallelization using MPI. The code in the MrBayes Git repository comes with a standard GNU "configure" script. On any Unix system, these are the steps required to compile and optionally install MrBayes: * Run "configure" in the top-level directory to create "Makefile" (see "./configure --help" for info about enabling and disabling features of MrBayes, or how to install in non-standard locations etc., and also read further down in this document): ./configure * Make (i.e. compile) the project: make Note that if "pdflatex" or "bibtex" could not be found by the "configure" script, the PDF documentation in doc/manual will not be rebuilt, even if the PDF documents are outdated or missing. * Install it on the system (optional). This will install the executable "mb" in /usr/local/bin, the documentation in /usr/local/share/doc/mrbayes, and the example files in /usr/local/share/examples/mrbayes unless the default installation prefix ("/usr/local") is changed with the "--prefix" option when running "configure". make install * We also support configuring and building the project away from the checked out source repository. This avoids littering the source repository checkout with temporary files. This is done through the following steps: 1. Create and enter a build directory somewhere (its name and location is arbitrary) mkdir build cd build 2. Call the "configure" script location-of-MrBayes-checkout/configure 3. Build and optionally install the project make make install Building MrBayes using the GNU autotools (Autoconf and Automake): ------------------------------------------------------------------------ MrBayes uses the GNU autotools, i.e. Automake and Autoconf, for its configuration and build system. If you tinker with "configure.ac" and/or any of the "Makefile.am" files and then want to regenerate the "configure" script and associated files, there are some prerequisites that need to be in place: * Make sure Automake 1.15 (http://www.gnu.org/software/automake/) is installed. * Make sure Autoconf 2.69 (http://www.gnu.org/software/autoconf/) is installed. The "configure.ac" script uses the "pkg-config" tool for detection of external libraries (Beagle) and also uses m4 macros from the autoconf-archive collection for detection of MPI, Readline, and some architecture-dependent compiler flags. Therefore, * Make sure pkg-config (https://www.freedesktop.org/wiki/Software/pkg-config/) is installed. * Make sure autoconf-archive 2016.03.20 (or later) (http://www.gnu.org/software/autoconf-archive/) is installed. * On some systems that uses metaauto for wrapping multiple versions of the GNU autotools (OpenBSD for example): export AUTOCONF_VERSION=2.69 export AUTOMAKE_VERSION=1.15 * On Ubuntu Linux, installing the following packages installs all of the above prerequisites: 1. automake 2. autoconf 3. pkg-config 4. autoconf-archive These may be installed through sudo apt install automake autoconf pkg-config autoconf-archive When all the prerequisites are in place: * Run "autoreconf" to generate the "configure" script: autoreconf -i * Then continue as outlined earlier in this document. Disabling the SSE, AVX and FMA code paths ------------------------------------------------------------------------ MrBayes will use SSE, AVX and FMA instructions to speed up computations on CPUs that support these instruction sets, if the compiler and build architecture supports it. These code paths are however optional, and if you suspect a bug in part of this code, you may use "--disable-sse", "--disable-avx" and/or "--disable-fma" to disable it when running the "configure" script. Note that disabling SSE will also disable AVX and FMA, and disabling AVX will also disable FMA. Picking up the Beagle library: ------------------------------------------------------------------------ MrBayes uses the Beagle library (https://github.com/beagle-dev/beagle-lib) if it is available. It will make use of release 3.1.2 of Beagle but should also work with release 2.1.3 of the library. Assuming Beagle was compiled and installed in a standard location, it will be picked up by the "configure" script automatically. If it isn't found, or the "configure" script is run with "--without-beagle", Beagle will not be used. If Beagle is installed in a non-default location, there are three ways of telling the "configure" script how to find it: * Use the flag "--with-beagle=PATH" where "PATH" is the prefix path where the Beagle headers and libraries may be found. For example "$HOME/local", "/opt" etc. The paths "/usr/local" and "/usr" are tested if no path is specified. * Point the "PKG_CONFIG_PATH" environment variable to the "pkgconfig" directory that Beagle installed its "hmsbeagle-1.pc" file into. This file is installed if Beagle was compiled from sources, and may be found in the installation's "lib" directory. The detection of Beagle will fall back on using "pkg-config" which picks up this file. * As a last resort, it's also possible to set the "BEAGLE_CFLAGS" and "BEAGLE_LIBS" environment variables prior to running "configure" (the example shows how to use these variables when Beagle was installed under the path "$HOME/local"): env BEAGLE_CFLAGS="-I$HOME/local/include/hmsbeagle-1" \ BEAGLE_LIBS="-L$HOME/local/lib -Wl,-rpath=$HOME/local/lib -lhmsbeagle" \ ./configure Building the Beagle library for MrBayes ------------------------------------------------------------------------ Ideally, you would use a pre-built distribution of the Beagle library, as setting up the required prerequisites for things like OpenCL etc. is a bit cumbersome to say the least. If you none the less want to try building and installing it, this is the executive summary for how to do this on a Unix system, not including installation of prerequisites (since these will differ between systems). It's assumed that the Beagle library is being installed in the default location, under "/usr/local". Note that the Beagle Java library is not needed by MrBayes. git clone --branch=v3.1.2 --depth=1 \ 'https://github.com/beagle-dev/beagle-lib.git' cd beagle-lib ./autogen.sh ./configure --without-jdk LDFLAGS=-Wl,-rpath=/usr/local/lib make sudo make install See also the "INSTALL" document supplied with the Beagle library's source distribution. Picking up and using MPI: ------------------------------------------------------------------------ The "configure" script will find any available MPI C compiler or compiler wrapper and use it (for example the one provided by OpenMPI (https://www.open-mpi.org/) or MPICH (https://www.mpich.org/)) if the "--with-mpi" flag is used. If this flag is not used, or if "--without-mpi" is used, MrBayes will be compiled without support for MPI parallelization. You may set the "MPICC" environment variable to the name or path of a specific MPI C compiler, if you have many to choose from: env MPICC="/usr/local/bin/mpicc" ./configure --with-mpi About support for the GNU Readline library: ------------------------------------------------------------------------ MrBayes will be compiled with support for the GNU Readline Library (https://cnswww.cns.cwru.edu/php/chet/readline/rltop.html) (which allows for command line history within an interactive session, and command completion through pressing the "tab" key) if the Readline library and its associated header files are available. However, it seems as if the Readline library doesn't work well together with common MPI implementations, such as OpenMPI (https://www.open-mpi.org/) and MPICH (https://www.mpich.org/), so if MrBayes is configured with support for MPI parallelization, Readline support will be automatically disabled. A possible workaround is to use a "Readline wrapper", such as "rlwrap" (https://github.com/hanslub42/rlwrap), which gives you persistent command line history between sessions, but no command tab-completion. To use rlwrap with an MPI-enabled MrBayes, simply start MrBayes like this: rlwrap mb # vim: filetype=text