Installing MIRA

There you will normally find a couple of precompiled binaries -- usually for Linux, sometimes also for Mac OSX -- or the source package for compiling yourself.

Precompiled binary packages are named in the following way:

mira_miraversion_OS-and-binarytype.tar.bz2

where

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 upcomming 4.x series will need a C++11 compatible toolchain, 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 preconfigured 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 preconfigured 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 prereqisite 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 toolchain:

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
convert_project

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 preconfigured 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 plattforms is being slowly phased out. While MIRA should compile and also run fine on 32 bit plattforms, 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-3.9.1.tar.bz2
cd mira-3.9.1
./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-3.9.1.tar.bz2
cd mira-3.9.1
./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-3.9.1.tar.bz2
cd mira-3.9.1
./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
Install BOOST from MacPorts. If you haven't already done so, install MacPorts Basically, just a couple of easy steps, see http://www.macports.org/install.php
Install BOOST: in a terminal, type
```
sudo port install boost
```
Note
for universal builds (e.g. for distributing MIRA with universal binaries) rather do
sudo port install boost +universal
Note
This will take a while! It took ~1 hour on my MacAir with a 1.86 GHz dual core processor, even without universal. MacPros and server will be somehwat faster I suppose.
Download the MIRA source package and unpack it
Run ./configure and make.

	If compiling or linking fails at first
	Depending on how and where all the different packages were installed, the most useful `./configure` parameters will probably be `--enable-mirastatic`, `--with-boost=...` and maybe also `--with-boost-libdir=...`.

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

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

	Note
	This will take a while! It took ~1 hour on my MacAir with a 1.86 GHz dual core processor, even without universal. MacPros and server will be somehwat faster I suppose.