Bastien
Chevreux
bach@chevreux.org

> Solomon Short

> A problem can be found to almost every solution.

# Installing MIRA

## Where to fetch MIRA

SourceForge:

There you will normally find a couple of precompiled binaries -- usually for Linux and 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`

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

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

## Compiling MIRA yourself

### 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 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 for more information on the BOOST library.

  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 for more information regarding zlib.
- GNU make. Should your system not have gmake installed or available as simple installation package, please see 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 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 and 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 .

  Note that Google perftools itself needs libunwind:

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

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

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

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

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

#### 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)

  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

## Installation walkthroughs

### (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

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

### 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

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

### 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

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

### 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

### 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

## Compilation hints for other platforms.

### Mac OS X

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

1. Download and install a current XCode
2. Download and compile a current GCC (≥ 4.8.2). Do NOT use a GCC from MacPorts, it lacks a vitally important library (`libstdc++.a`)
3. Download, compile with GCC and install a current BOOST library
4. Download, compile with GCC and install all libraries MIRA needs (flex, etc.pp). Follow the directions given in and
5. Download the MIRA source package and unpack it

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

7. Run `./configure --enable-mirastatic ...` where "..." stands for additional configure parameters needed and then run `make`.

   Oh, and then pray.

As of now (Feb. 2014), if you are on OSX 10.9 (Mavericks) and are using GCC ≤ 4.8.2, the steps described above (including the prayer) 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

A checkout from git needs some packages from MacPorts:

    $ port install autoconf automake libtool

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.

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