## Installing MIRA

### Bastien Chevreux

`<bach@chevreux.org>`

MIRA Version 4.9.6

Copyright © 2016 Bastien Chevreux

| “A problem can be found to almost every solution. ” |
| --Solomon Short

## 1. Where to fetch MIRA

SourceForge: http://sourceforge.net/projects/mira-assembler/

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`

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

1. Download the package, unpack it.

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

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

4. Test whether the binaries are installed ok via `mirabait -v` which should return with the current version you downloaded and installed.

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