Installing MIRA

For miraversion, the stable versions of MIRA with the general public as audience usually have a version number in three parts, like 3.0.5, sometimes also followed by some postfix like in 3.2.0rc1 to denote release candidate 1 of the 3.2.0 version of MIRA. On very rare occasions, stable versions of MIRA can have four part like in, e.g., 3.4.0.1: these versions create identical binaries to their parent version (3.4.0) and just contains fixes to the source build machinery.
The version string sometimes can have a different format: sometext-0-gsomehexnumber like in, e.g., ft_fastercontig-0-g4a27c91. These versions of MIRA are snapshots from the development tree of MIRA and usually contain new functionality which may not be as well tested as the rest of MIRA, hence contains more checks and more debugging output to catch potential errors
OS-and-binarytype finally defines for which operating system and which processor class the package is destined. E.g., linux-gnu_x86_64_static contains static binaries for Linux running a 64 bit processor.

Source packages are usually named

mira-miraversion.tar.bz2

Examples for packages at SourceForge:

mira_3.0.5_prod_linux-gnu_x86_64_static.tar.bz2
mira_3.0.5_prod_linux-gnu_i686_32_static.tar.bz2
mira_3.0.5_prod_OSX_snowleopard_x86_64_static.tar.bz2
mira-3.0.5.tar.bz2

2. Installing from a precompiled binary package

The distributable package follows the one-directory-which-contains-everything-which-is-needed philosophy, but after unpacking and moving the package to its final destination, you need to run a script which will create some data files.

Download the package, unpack it.
Move the directory somewhere to your disk. Either to one of the "standard" places like, e.g., /opt/mira, /usr/local/mira or somewhere in your home directory
Softlink the binaries which are in the 'bin' directory into a directory which is in your shell PATH. Then have the shell reload the location of PATH binaries (either hash -r for sh/bash or rehash for csh/tcsh.
Alternatively, add the bin directory of the MIRA package to your PATH variable.
Test whether the binaries are installed ok via mirabait -v which should return with the current version you downloaded and installed.

Now you need to run a script which will unpack and reformat some data needed by MIRA. That script is located in the dbdata directory of the package and should be called with the name of the SLS file present in the same diretory like this:

arcadia:/path/to/mirapkg$ cd dbdata
arcadia:/path/to/mirapkg/dbdata$ ls -l
drwxr-xr-x 3 bach bach     4096 2016-03-18 14:31 mira-createsls
-rwxr-xr-x 1 bach bach     2547 2015-12-14 04:33 mira-install-sls-rrna.sh
-rw-r--r-- 1 bach bach      337 2016-01-01 14:50 README.txt
lrwxrwxrwx 1 bach bach 10421035 2016-03-18 14:28 rfam_rrna-21-12.sls.gz
arcadia:/path/to/mirapkg/dbdata$ ./mira-install-sls-rrna.sh rfam_rrna-21-12.sls.gz

This will take a minute or so. Then you're done for MIRA.

Additional scripts for special purposes are in the scripts directory. You might or might not want to have them in your $PATH.

Scripts and programs for MIRA from other authors are in the 3rdparty directory. Here too, you may or may not want to have (some of them) in your $PATH.

3. Integration with third party programs (gap4, consed)

MIRA sets tags in the assemblies that can be read and interpreted by the Staden gap4 package or consed. These tags are extremely useful to efficiently find places of interest in an assembly (be it de-novo or mapping), but both gap4 and consed need to be told about these tags.

Data files for a correct integration are delivered in the support directory of the distribution. Please consult the README in that directory for more information on how to integrate this information in either of these packages.

4. Compiling MIRA yourself

4.1. Prerequisites

Compiling the 5.x series of MIRA needs a C++14 compatible tool chain, i.e., systems starting from 2013/2014 should be OK. The requisites for compiling MIRA are:

gcc ≥ 4.9.1, with libstdc++6. You really want to use a simple installation package pre-configured for your system, but in case you want or have to install gcc yourself, please refer to http://gcc.gnu.org/ for more information on the GNU compiler collection.
BOOST library ≥ 1.48. Lower versions might work, but untested. You would need to change the checking in the configure script for this to run through. You really want to use a simple installation package pre-configured for your system, but in case you want or have to install BOOST yourself, please refer to http://www.boost.org/ for more information on the BOOST library.
Warning
Do NOT use a so called staged BOOST library, that will not work.
zlib. Should your system not have zlib installed or available as simple installation package, please see http://www.zlib.net/ for more information regarding zlib.
GNU make. Should your system not have gmake installed or available as simple installation package, please see www.gnu.org/software/make/ for more information regarding GNU make.
GNU flex ≥ 2.5.33. Should your system not have flex installed or available as simple installation package, please see http://flex.sourceforge.net/ for more information regarding flex.
Expat library ≥ 2.0.1. Should your system not have the Expat library and header files already installed or available as simple installation package, you will need to download and install a yourself. Please see http://www.libexpat.org/ and http://sourceforge.net/projects/expat/ for information on how to do this.
xxd. A small utility from the vim package.

For building the documentation, additional prerequisites are from the DocBook tool chain:

xsltproc + docbook-xsl for HTML output
dblatex for PDF output

Warning

Previous versions of MIRA had a benefit by using the TCMalloc library. This is not the case anymore! Indeed, tests showed that when using TCMalloc, MIRA 4.9.x and above will probably need 20 to 30% more max memory and up to 80% more overall memory than without TCMalloc.

In short: do not use at the moment.

4.2. Compiling and installing

MIRA uses the GNU autoconf/automake tools, please read the section "Basic Installation" of the INSTALL file in the source package of MIRA for more generic information on how to invoke them.

The short version: simply type

arcadia:/path/to/mira-5.0.0$ ./configure
arcadia:/path/to/mira-5.0.0$ make
arcadia:/path/to/mira-5.0.0$ make install

This should install the following programs:

mira
miraconvert
mirabait
miramem

Should the ./configure step fail for some reason or another, you should get a message telling you at which step this happens and and either install missing packages or tell configure where it should search the packages it did not find, see also next section.

4.3. Configure switches for MIRA

MIRA understands all standard autoconf configure switches like --prefix= etc. Please consult the INSTALL file in the MIRA top level directory of the source package and also call ./configure --help to get a full list of currently supported switches.

4.3.1. BOOST configure switches for MIRA

BOOST is maybe the most tricky library to get right in case it does not come pre-configured for your system. The two main switches for helping to locate BOOST are probably --with-boost=[ARG] and --with-boost-libdir=LIB_DIR. Only if those two fail, try using the other --with-boost-*= switches you will see from the ./configure help text.

4.3.2. MIRA specific configure switches

MIRA honours the following switches:

--enable-64=yes/no

MIRA should happily build as 32 bit executable on 32 bit platforms and as 64 bit executable on 64 bit platforms. On 64 bit platforms, setting the switch to 'no' forces the compiler to produce 32 bit executables (if possible)

	Warning
	As of MIRA 3.9.0, support for 32 bit platforms is being slowly phased out. While MIRA should compile and also run fine on 32 bit platforms, I do not guarantee it anymore as I haven't used 32 bit systems in the last 5 years.

--enable-warnings

Enables compiler warnings, useful only for developers, not for users.

--enable-debug

Lets the MIRA binary contain C/C++ debug symbols.

--enable-mirastatic

Builds static binaries which are easier to distribute. Some platforms (like OpenSolaris) might not like this and you will get an error from the linker.

--enable-optimisations

Instructs the configure script to set optimisation switches for compiling (on by default). Switching optimisations off (warning, high impact on run-time) might be interesting only for, e.g, debugging with valgrind.

--enable-publicquietmira

Some parts of MIRA can dump additional debug information during assembly, setting this switch to "no" performs this. Warning: MIRA will be a bit chatty, using this is not recommended for public usage.

--enable-developmentversion

Using MIRA with enabled development mode may lead to extra output on stdout as well as some additional data in the results which should not appear in real world data

--enable-boundtracking

--enable-bugtracking

Both flags above compile in some basic checks into mira that look for sanity within some functions: Leaving this on "yes" (default) is encouraged, impact on run time is minimal

5. Installation walkthroughs

5.1. (K)Ubuntu 12.04

You will need to install a couple of tools and libraries before compiling MIRA. Here's the recipe:

sudo apt-get install make flex
sudo apt-get install libboost-doc libboost.*1.48-dev libboost.*1.48.0

Once this is done, you can unpack and compile MIRA. For a dynamically linked version, use:

tar xvjf mira-5.0.0.tar.bz2
cd mira-5.0.0
./configure
make && make install

For a statically linked version, just change the configure line from above into

./configure --enable-mirastatic

In case you also want to build documentation yourself, you will need this in addition:

sudo apt-get install xsltproc docbook-xsl dblatex

Note

People working on git checkouts of the MIRA source code will obviously need some more tools. Get them with this:

sudo apt-get install automake libtool xutils-dev

5.2. openSUSE 12.1

You will need to install a couple of tools and libraries before compiling MIRA. Here's the recipe:

sudo zypper install gcc-c++ boost-devel
sudo zypper install flex libexpat-devel zlib-devel

Once this is done, you can unpack and compile MIRA. For a dynamically linked version, use:

tar xvjf mira-5.0.0.tar.bz2
cd mira-5.0.0
./configure
make && make install

In case you also want to build documentation yourself, you will need this in addition:

sudo zypper install docbook-xsl-stylesheets dblatex

Note

People working on git checkouts of the MIRA source code will obviously need some more tools. Get them with this:

sudo zypper install automake libtool xutils-dev

5.3. Fedora 17

You will need to install a couple of tools and libraries before compiling MIRA. Here's the recipe:

sudo yum -y install gcc-c++ boost-devel
sudo yum install flex expat-devel vim-common zlib-devel

Once this is done, you can unpack and compile MIRA. For a dynamically linked version, use:

tar xvjf mira-5.0.0.tar.bz2
cd mira-5.0.0
./configure
make && make install

In case you also want to build documentation yourself, you will need this in addition:

sudo yum -y install docbook-xsl dblatex

Note

People working on git checkouts of the MIRA source code will obviously need some more tools. Get them with this:

sudo yum -y install automake libtool xorg-x1-util-devel

5.4. Mac OSX

These instructions are for OSX 10.11 (El Capitan) and use MacPorts. There are other ways to do this (e.g., see the "compile everything from scratch"), but they are definetly more painful.

If you do not already have it, install McPorts. See https://www.macports.org/install.php. Then have the port system fetch information of the newest ports (can take a while):

sudo port selfupdate

Then go on and install gcc (this is going to take a long time) and then switch to gcc5:

sudo port install m4 gcc5
sudo port select --set gcc mp-gcc5

Now, the libraries you need to download and compile need to be installed somewhere. You can take a path in your home directory or any other path in the system you have access to, for the sake of this walkthrough we'll continue with /opt/biosw/gccchain

Download and install a current flex. Use at least 2.6.0. If for some reason you need to use flex 2.5.38 or .39, take care to apply the patch described here: https://sourceforge.net/p/flex/bugs/182/. Configure flex to be installed into the directory you chose the step before:

tar xvf flex-2.6.0.tar.bz2
cd flex-2.6.0
./configure --prefix=/opt/biosw/gccchain
make
make install

That done, proceed with likewise with expat and zlib library:

tar xvf expat-2.1.0.tar.gz
cd expat-2.1.0
./configure --prefix=/opt/biosw/gccchain
make
make install
cd ..
tar xvf zlib-1.2.8.tar.gz
cd zlib-1.2.8
./configure --prefix=/opt/biosw/gccchain
make -j 4
make install

The bzip2 library needs a different installation command line:

tar xvf bzip2-1.0.6.tar.gz
cd bzip2-1.0.6
make -j 4
make install PREFIX=/opt/biosw/gccchain

Last library to be installed for the MIRA compilation is BOOST:

tar xvf boost_1_59_0.tar.bz2
cd boost_1_59_0
./bootstrap.sh --prefix=/opt/biosw/gccchain
./b2 -j 4
./b2 install

Now unpack MIRA, configure it and compile. Remember to give configure script the location of every package you just installed or else it might pick up a version installed by the system (and compiled with different compiler) which would invariably lead to errors in the linker stage of the compilation.

tar xvf mira-5.0.0.tar.bz2
cd mira-5.0.0
./configure --enable-debug
  --with-boost=/opt/biosw/gccchain
  --with-boost-libdir=/opt/biosw/gccchain/lib
  --with-expat=/opt/biosw/gccchain
  --with-zlib=/opt/biosw/gccchain
make -j 4

That's it for the dynamic version.

For building an almost static version, we need some trickery: after the configure (this time with the mirastatic argument), create a special directory OSXstatlibs in which we softlink all static libraries MIRA needs. This directory will be searched first by the build scripts generated by the libtool suite during the linking stage of MIRA.

./configure --enable-mirastatic --enable-debug
  --with-boost=/opt/biosw/gccchain
  --with-boost-libdir=/opt/biosw/gccchain/lib
  --with-expat=/opt/biosw/gccchain
  --with-zlib=/opt/biosw/gccchain
mkdir OSXstatlib
cd OSXstatlib
ln -s /opt/biosw/gccchain/lib/*a
ln -s /opt/local/lib/*a

Note that /opt/local is the standard installation path of the MacPorts programs. If you changed that, you need to adapt it here, too.

5.5. Compile everything from scratch

This lets you build a self-contained static MIRA binary. The only prerequisite here is that you have a working gcc with the minimum version described above. Please download all necessary files (expat, flex, etc.pp) and then simply follow the script below. The only things that you will want to change are the path used and, maybe, the name of some packages in case they were bumped up a version or revision.

Contributed by Sven Klages.

## whatever path is appropriate
cd /home/gls/SvenTemp/install

## expat
tar zxvf expat-2.0.1.tar.gz
cd expat-2.0.1
./configure --prefix=/home/gls/SvenTemp/expat
make && make install

## flex
cd /home/gls/SvenTemp/install
tar zxvf flex-2.5.35.tar.gz
cd flex-2.5.35
./configure --prefix=/home/gls/SvenTemp/flex
make && make install
cd /home/gls/SvenTemp/flex/bin
ln -s flex flex++
export PATH=/home/gls/SvenTemp/flex/bin:$PATH

## boost
cd /home/gls/SvenTemp/install
tar zxvf boost_1_48_0.tar.gz
cd boost_1_48_0
./bootstrap.sh --prefix=/home/gls/SvenTemp/boost
./b2 install

## mira itself
export CXXFLAGS="-I/home/gls/SvenTemp/flex/include"

cd /home/gls/SvenTemp/install
tar zxvf mira-3.4.0.1.tar.gz
cd mira-3.4.0.1
./configure --prefix=/home/gls/SvenTemp/mira \
--with-boost=/home/gls/SvenTemp/boost \
--with-expat=/home/gls/SvenTemp/expat \
--enable-mirastatic
make && make install

5.6. Dynamically linked MIRA

In case you do not want a static binary of MIRA, but a dynamically linked version, the following script by Robert Bruccoleri will give you an idea on how to do this.

Note that he, having root rights, puts all additional software in /usr/local, and in particular, he keeps updated versions of Boost and Flex there.

#!/bin/sh -x

make distclean
oze=`find . -name "*.o" -print`
if [[ -n "$oze" ]]
then
   echo "Not clean."
   exit 1

fi

export prefix=${BUILD_PREFIX:-/usr/local}
export LDFLAGS="-Wl,-rpath,$prefix/lib"

./configure --prefix=$prefix \
           --enable-debug=yes \
           --enable-mirastatic=no \
           --with-boost-libdir=$prefix/lib \
           --enable-optimisations \
           --enable-boundtracking=yes \
           --enable-bugtracking=yes \
           --enable-extendedbugtracking=no
make
make install

6. Compilation hints for other platforms.

6.1. NetBSD 5 (i386)

Contributed by Thomas Vaughan

The system flex (/usr/bin/flex) is too old, but the devel/flex package from a recent pkgsrc works fine. BSD make doesn't like one of the lines in src/progs/Makefile, so use GNU make instead (available from pkgsrc as devel/gmake). Other relevant pkgsrc packages: devel/boost-libs, devel/boost-headers and textproc/expat. The configure script has to be told about these pkgsrc prerequisites (they are usually rooted at /usr/pkg but other locations are possible):

FLEX=/usr/pkg/bin/flex ./configure --with-expat=/usr/pkg --with-boost=/usr/pkg

If attempting to build a pkgsrc package of MIRA, note that the LDFLAGS passed by the pkgsrc mk files don't remove the need for the --with-boost option. The configure script complains about flex being too old, but this is harmless because it honours the $FLEX variable when writing out makefiles.

7. Notes for distribution maintainers / system administrators

7.1. Additional data files

Depending on options/paramaters, the MIRA/mirabait binary may need to load some additional data during the run. By default this data will always be searched at this location: LOCATION_OF_BINARY/../share/mira/...

That is: If the binary is, e.g., /opt/mira5/bin/mira with a softlink pointing from /usr/local/bin/mira -> /opt/mira5/bin/mira (because, e.g., /usr/local/bin may be by default in your PATH variable), then the additional data will be searched in /opt/mira5/share/mira/... and NOT in /usr/local/share/mira/....

	Note
	In short: since MIRA 4.9.6, moving the binary is not enough anymore. Take care to have the <emph>share</emph> directory in the right place, i.e., adjacent to the directory the MIRA binary lives in.

	Warning
	Do NOT use a so called staged BOOST library, that will not work.