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

Download the package, unpack it. Inside, there is -- beside other directories -- a bin. Copy or move the files and soft-links inside this directory to a directory in your $PATH variable.

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

The MIRA 3.x series works with quite old systems, the upcoming 4.x series will need a C++11 compatible tool chain, i.e., systems starting from the later half of 2011 should be OK. The requisites for compiling MIRA are:

gcc ≥ 4.6.2, 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.46. 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, only a fully installed library will work at the moment
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.
TCmalloc library ≥ 1.6. Not a prerequisite per se, but highly recommended: MIRA will also work without, but memory requirements may then be a lot higher (40% and more).
TCmalloc is part of the Google perftools library, version 1.6 or higher, lower might work, but untested. Should your system not have the perftools library and header files already installed or available as simple installation package, you will need to download and install a yourself. Please see http://code.google.com/p/google-perftools/.
Note that Google perftools itself needs libunwind: http://www.nongnu.org/libunwind/

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

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

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-4.0.0$ ./configure
arcadia:/path/to/mira-4.0.0$ make
arcadia:/path/to/mira-4.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 libgoogle-perftools-dev
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-4.0.0.tar.bz2
cd mira-4.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 google-perftools-devel zlib-devel

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

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

For a statically linked version you will need to compile and install the Google perftools library yourself as the package delivered by Fedora contains only dynamic libraries.

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 google-perftools-devel vim-common zlib-devel

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

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

For a statically linked version you will need to compile and install the Google perftools library yourself as the package delivered by Fedora contains only dynamic libraries.

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. 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 ≥ 4.6.2. 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

## libunwind and google-perftools
cd /home/gls/SvenTemp/install
tar zxvf libunwind-0.99-beta.tar.gz
cd libunwind-0.99-beta
./configure --prefix=/home/gls/SvenTemp/libunwind
make && make install

cd /home/gls/SvenTemp/install
tar zxvf google-perftools-1.9.1.tar.gz
cd google-perftools-1.9.1
export LDFLAGS="-L/home/gls/SvenTemp/libunwind/lib"
export CPPFLAGS="-I/home/gls/SvenTemp/libunwind/include"
./configure --prefix=/home/gls/SvenTemp/google-perftools
make && make 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 \
--with-tcmalloc-dir=/home/gls/SvenTemp/google-perftools/lib \
--enable-mirastatic
make && make install

5.5. 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 \
           --with-tcmalloc=yes \
           --with-tcmalloc-dir=$prefix/lib
make
make install

6. Compilation hints for other platforms.

6.1. Mac OS X

This has been tested on OSX 10.6.4. You will need XCode (from Apple) and some packages from MacPorts.

Download and install a current XCode
Download and compile a current GCC (≥ 4.8.2). Do NOT use a GCC from MacPorts, it lacks a vitally important library (libstdc++.a)
Download, compile with GCC and install a current BOOST library
Download, compile with GCC and install all libraries MIRA needs (flex, etc.pp). Follow the directions given in Section 5.4: “ Compile everything from scratch ” and Section 5.4, “ Compile everything from scratch ”
Download the MIRA source package and unpack it
In the unpacked MIRA directory, create a directory called OSXstatlibs. Into this directory, you need to softlink all needed static libraries from GCC, BOOST, flex, etc.pp.
E.g., I have GCC installed in /opt/localwgcc48/ and therefore I need to use the following to link GCC static libraries:
```
$ ln -s /opt/localwgcc48/lib/*a .
```
I have all the other libraries (BOOST, flex, etc.pp) installed in /opt/biosw/, therefore I also need to link these libraries:
```
$ ln -s /opt/biosw/lib/*a .
```
Run ./configure --enable-mirastatic ... where "..." stands for additional configure parameters needed and then run make.

	Note
	As of now (April 2014), if you are on OSX 10.9 (Mavericks) and are using GCC ≤ 4.8.2, the steps described above may not be enough. If an error occurs at the linking stage very late in the MIRA building process, you need to patch a system file as described in http://trac.macports.org/ticket/41033

	Note
	A checkout from git needs some packages from MacPorts: `$` `port install autoconf automake libtool`

Note

Building documentation needs the packages 'libxslt' and 'dblatex' from MacPorts.

$ port install dblatex libxslt

(Feb 2014) The above may fail while installing the one or other dependency (for me it was while installing 'urw-fonts'). If that is the case, repeat a couple of times and normally it should work.

6.2. 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.

	Warning
	Do NOT use a so called staged BOOST library, only a fully installed library will work at the moment