<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd">
<chapter id="chap_installation">
  <chapterinfo>
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="versionfile"/>
    <author>
      <firstname>Bastien</firstname>
      <surname>Chevreux</surname>
      <email>bach@chevreux.org</email>
    </author>
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="copyrightfile"/>
  </chapterinfo>
  <blockquote>
    <attribution>Solomon Short</attribution>
    <para>
      <emphasis><quote>A problem can be found to almost every solution.
      </quote></emphasis>
    </para>
  </blockquote>

  <title>Installing MIRA</title>
  <sect1 id="sect_install_wheretofetch">
    <title>
      Where to fetch MIRA
    </title>
    <para>
      SourceForge: <ulink url="http://sourceforge.net/projects/mira-assembler/"/>
    </para>
    <para>
      There you will normally find a couple of precompiled binaries -- usually
      for Linux and Mac OSX -- or the source package for compiling yourself.
    </para>
    <para>
      Precompiled binary packages are named in the following way:
    </para>
    <para>
      <filename>mira_<replaceable>miraversion</replaceable>_<replaceable>OS-and-binarytype</replaceable>.tar.bz2</filename>
    </para>
    <para>
      where
    </para>
    <itemizedlist>
      <listitem>
	<para>
	  For <filename><replaceable>miraversion</replaceable></filename>, the
	  stable versions of MIRA with the general public as audience usually
	  have a version number in three parts, like
	  <filename>3.0.5</filename>, sometimes also followed by some postfix
	  like in <filename>3.2.0rc1</filename> 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.,
	  <filename>3.4.0.1</filename>: these versions create identical
	  binaries to their parent version (<filename>3.4.0</filename>) and
	  just contains fixes to the source build machinery.
	</para>
	<para>
	  The version string sometimes can have a different format:
	  <filename><emphasis>sometext</emphasis>-0-g<emphasis>somehexnumber</emphasis></filename>
	  like in, e.g.,
	  <filename>ft_fastercontig-0-g4a27c91</filename>. 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
	</para>
      </listitem>
      <listitem>
	<para>
	  <filename><replaceable>OS-and-binarytype</replaceable></filename>
	  finally defines for which operating system and which processor class
	  the package is destined. E.g.,
	  <filename>linux-gnu_x86_64_static</filename> contains static
	  binaries for Linux running a 64 bit processor.
	</para>
      </listitem>
    </itemizedlist>
    <para>
      Source packages are usually named
    </para>
    <para>
      <filename>mira-<replaceable>miraversion</replaceable>.tar.bz2</filename>
    </para>
    <para>
      Examples for packages at SourceForge:
    </para>
    <itemizedlist>
      <listitem>
	<filename>mira_3.0.5_prod_linux-gnu_x86_64_static.tar.bz2</filename>
      </listitem>
      <listitem>
	<filename>mira_3.0.5_prod_linux-gnu_i686_32_static.tar.bz2</filename>
      </listitem>
      <listitem>
	<filename>mira_3.0.5_prod_OSX_snowleopard_x86_64_static.tar.bz2</filename>
      </listitem>
      <listitem>
	<filename>mira-3.0.5.tar.bz2</filename>
      </listitem>
    </itemizedlist>
  </sect1>
  <sect1 id="sect_install_precompiledbinary">
    <title>
      Installing from a precompiled binary package
    </title>
    <para>
      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.
    </para>
    <orderedlist>
      <listitem>
	<para>
	  Download the package, unpack it.
	</para>
      </listitem>
      <listitem>
	<para>
	  Move the directory somewhere to your disk. Either to one of the
	  "standard" places like, e.g., <filename>/opt/mira</filename>,
	  <filename>/usr/local/mira</filename> or somewhere in your home
	  directory
	</para>
      </listitem>
      <listitem>
	<para>
	  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 <literal>hash -r</literal>
	  for sh/bash or <literal>rehash</literal> for csh/tcsh.
	</para>
	<para>
	  Alternatively, add the <filename>bin</filename> directory of the
	  MIRA package to your PATH variable.
	</para>
      </listitem>
      <listitem>
	<para>
	  Test whether the binaries are installed ok via <literal>mirabait
	  -v</literal> which should return with the current version you
	  downloaded and installed.
	</para>
      </listitem>
      <listitem>
	<para>
	  Now you need to run a script which will unpack and reformat some
	  data needed by MIRA. That script is located in the
	  <filename>dbdata</filename> directory of the package and should
	  be called with the name of the <emphasis>SLS</emphasis> file present
	  in the same diretory like this:
	</para>
	<screen>
<prompt>arcadia:/path/to/mirapkg$</prompt> <userinput>cd dbdata</userinput>
<prompt>arcadia:/path/to/mirapkg/dbdata$</prompt> <userinput>ls -l</userinput>
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
<prompt>arcadia:/path/to/mirapkg/dbdata$</prompt> <userinput>./mira-install-sls-rrna.sh rfam_rrna-21-12.sls.gz</userinput></screen>
        <para>
	  This will take a minute or so. Then you're done for MIRA.
        </para>
      </listitem>
    </orderedlist>
    <para>
      Additional scripts for special purposes are in the
      <filename>scripts</filename> directory. You might or might not want to
      have them in your $PATH.
    </para>
    <para>
      Scripts and programs for MIRA from other authors are in the
      <filename>3rdparty</filename> directory. Here too, you may or may not
      want to have (some of them) in your $PATH.
    </para>
  </sect1>
  <sect1 id="sect_install_third_party_integration">
    <title>
      Integration with third party programs (gap4, consed)
    </title>
    <para>
      MIRA sets tags in the assemblies that can be read and interpreted by the
      Staden <command>gap4</command> package or
      <command>consed</command>. These tags are extremely useful to
      efficiently find places of interest in an assembly (be it de-novo or
      mapping), but both <command>gap4</command> and <command>consed</command>
      need to be told about these tags.
    </para>
    <para>
      Data files for a correct integration are delivered in the
      <filename>support</filename> 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.
    </para>
  </sect1>
  <sect1 id="sect_install_compiling">
    <title>
      Compiling MIRA yourself
    </title>
    <sect2 id="sect_install_comp_prereq">
      <title>
	Prerequisites
      </title>
      <para>
	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 <emphasis>compiling</emphasis> MIRA are:
      </para>
      <itemizedlist>
	<listitem>
	  <para>
	    gcc &ge; 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 <ulink
	    url="http://gcc.gnu.org/"/> for more information on the GNU compiler
	    collection.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    BOOST library &ge; 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 <ulink
	    url="http://www.boost.org/"/> for more information on the BOOST
	    library.
	  </para>
	  <warning>
	    Do NOT use a so called <emphasis>staged</emphasis> BOOST library,
	    that will not work.
	  </warning>
	</listitem>
	<listitem>
	  zlib. Should your system not have zlib installed or available as
	  simple installation package, please see <ulink
	  url="http://www.zlib.net/"/> for more information regarding zlib.
	</listitem>
	<listitem>
	  GNU make. Should your system not have gmake installed or available
	  as simple installation package, please see <ulink
	  url="www.gnu.org/software/make/"/> for more information regarding
	  GNU make.
	</listitem>
	<listitem>
	  GNU flex &ge; 2.5.33. Should your system not have flex installed or
	  available as simple installation package, please see <ulink
	  url="http://flex.sourceforge.net/"/> for more information regarding
	  flex.
	</listitem>
	<listitem>
	  Expat library &ge; 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
	  <ulink url="http://www.libexpat.org/"/> and <ulink
	  url="http://sourceforge.net/projects/expat/"/> for information on how
	  to do this.
	</listitem>
	<listitem>
	  xxd. A small utility from the <command>vim</command> package.
	</listitem>
      </itemizedlist>
      <para>
	For <emphasis>building the documentation</emphasis>, additional
	prerequisites are from the DocBook tool chain:
      </para>
      <itemizedlist>
	<listitem>
	  xsltproc + docbook-xsl for HTML output
	</listitem>
	<listitem>
	  dblatex for PDF output
	</listitem>
      </itemizedlist>
      <warning>
	<para>
	  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% <emphasis>more</emphasis> max memory and up to 80% more overall
	  memory than without TCMalloc.
	</para>
	<para>
	  In short: do not use at the moment.
	</para>
      </warning>
    </sect2>
    <sect2 id="sect_install_comp_comp">
      <title>
	Compiling and installing
      </title>
      <para>
	MIRA uses the GNU autoconf/automake tools, please read the section
	"Basic Installation" of the <filename>INSTALL</filename> file in the
	source package of MIRA for more generic information on how to invoke
	them.
      </para>
      <para>
	The short version: simply type
      </para>
      <screen>
<prompt>arcadia:/path/to/mira-5.0.0$</prompt> <userinput>./configure</userinput>
<prompt>arcadia:/path/to/mira-5.0.0$</prompt> <userinput>make</userinput>
<prompt>arcadia:/path/to/mira-5.0.0$</prompt> <userinput>make install</userinput></screen>
      <para>
	This should install the following programs:
      </para>
      <itemizedlist>
	<listitem>
	  <command>mira</command>
	</listitem>
	<listitem>
	  <command>miraconvert</command>
	</listitem>
	<listitem>
	  <command>mirabait</command>
	</listitem>
	<listitem>
	  <command>miramem</command>
	</listitem>
      </itemizedlist>
      <para>
	Should the <literal>./configure</literal> 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
	<command>configure</command> where it should search the packages it
	did not find, see also next section.
      </para>
    </sect2>
    <sect2 id="sect_install_comp_conf">
      <title>
	Configure switches for MIRA
      </title>
      <para>
	MIRA understands all standard autoconf configure switches like <literal>--prefix=</literal>
	etc. Please consult the INSTALL file in the MIRA top level directory
	of the source package and also call <literal>./configure
	--help</literal> to get a full list of currently supported switches.
      </para>
      <sect3 id="sect_install_comp_conf_boost">
	<title>
	  BOOST configure switches for MIRA
	</title>
	<para>
	  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 <literal>--with-boost=[ARG]</literal>
	  and <literal>--with-boost-libdir=LIB_DIR</literal>. Only if those
	  two fail, try using the other <literal>--with-boost-*=</literal> switches
	  you will see from the ./configure help text.
	</para>
      </sect3>
      <sect3 id="sect_install_comp_conf_mira">
	<title>
	  MIRA specific configure switches
	</title>
	<para>
	  MIRA honours the following switches:
	</para>
	<variablelist>
	  <varlistentry>
	    <term>
	      --enable-64=yes/no
	    </term>
	    <listitem>
	      <para>
		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)
	      </para>
	      <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.
	      </warning>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      --enable-warnings
	    </term>
	    <listitem>
	      Enables compiler warnings, useful only for developers, not for users.
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      --enable-debug
	    </term>
	    <listitem>
	      Lets the MIRA binary contain C/C++ debug symbols.
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      --enable-mirastatic
	    </term>
	    <listitem>
	      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.
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      --enable-optimisations
	    </term>
	    <listitem>
	      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.
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      --enable-publicquietmira
	    </term>
	    <listitem>
	      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.
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      --enable-developmentversion
	    </term>
	    <listitem>
	      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
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      --enable-boundtracking
	    </term>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      --enable-bugtracking
	    </term>
	    <listitem>
	      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
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	    </term>
	    <listitem>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	    </term>
	    <listitem>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	    </term>
	    <listitem>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect3>
    </sect2>
  </sect1>
  <sect1 id="sect_install_walkthroughs">
    <title>
      Installation walkthroughs
    </title>
    <sect2 id="sect_install_walkthroughs_kubuntu">
      <title>
	(K)Ubuntu 12.04
      </title>
      <para>
	You will need to install a couple of tools and libraries before
	compiling MIRA. Here's the recipe:
      </para>
      <screen>
<userinput>sudo apt-get install make flex
sudo apt-get install libboost-doc libboost.*1.48-dev libboost.*1.48.0</userinput></screen>
<!--libexpat1-dev zlib1g-dev-->
      <para>
	Once this is done, you can unpack and compile MIRA. For a dynamically
	linked version, use:
      </para>
      <screen>
<userinput>tar xvjf <replaceable>mira-5.0.0.tar.bz2</replaceable>
cd <replaceable>mira-5.0.0</replaceable>
./configure
make &amp;&amp; make install</userinput></screen>
      <para>
	For a statically linked version, just change the configure line from
	above into
      </para>
      <screen>
<userinput>./configure <replaceable>--enable-mirastatic</replaceable></userinput></screen>
      <para>
	In case you also want to build documentation yourself, you will need
	this in addition:
      </para>
      <screen><userinput>sudo apt-get install xsltproc docbook-xsl dblatex</userinput></screen>
      <note>
	<para>
	  People working on git checkouts of the MIRA source code will
	  obviously need some more tools. Get them with this:
	</para>
	<screen><userinput>sudo apt-get install automake libtool xutils-dev</userinput></screen>
      </note>
    </sect2>
    <sect2 id="sect_install_walkthroughs_opensuse">
      <title>
	openSUSE 12.1
      </title>
      <para>
	You will need to install a couple of tools and libraries before
	compiling MIRA. Here's the recipe:
      </para>
      <screen>
<userinput>sudo zypper install gcc-c++ boost-devel
sudo zypper install flex libexpat-devel zlib-devel</userinput></screen>
<!--libexpat1-dev zlib1g-dev-->
      <para>
	Once this is done, you can unpack and compile MIRA. For a dynamically
	linked version, use:
      </para>
      <screen>
<userinput>tar xvjf <replaceable>mira-5.0.0.tar.bz2</replaceable>
cd <replaceable>mira-5.0.0</replaceable>
./configure
make &amp;&amp; make install</userinput></screen>
      <para>
	In case you also want to build documentation yourself, you will need
	this in addition:
      </para>
      <screen><userinput>sudo zypper install docbook-xsl-stylesheets dblatex</userinput></screen>
      <note>
	<para>
	  People working on git checkouts of the MIRA source code will
	  obviously need some more tools. Get them with this:
	</para>
	<screen><userinput>sudo zypper install automake libtool xutils-dev</userinput></screen>
      </note>
    </sect2>
    <sect2 id="sect_install_walkthroughs_fedora">
      <title>
	Fedora 17
      </title>
      <para>
	You will need to install a couple of tools and libraries before
	compiling MIRA. Here's the recipe:
      </para>
      <screen>
<userinput>sudo yum -y install gcc-c++ boost-devel
sudo yum install flex expat-devel vim-common zlib-devel</userinput></screen>
<!--libexpat1-dev zlib1g-dev-->
      <para>
	Once this is done, you can unpack and compile MIRA. For a dynamically
	linked version, use:
      </para>
      <screen>
<userinput>tar xvjf <replaceable>mira-5.0.0.tar.bz2</replaceable>
cd <replaceable>mira-5.0.0</replaceable>
./configure
make &amp;&amp; make install</userinput></screen>
      <para>
	In case you also want to build documentation yourself, you will need
	this in addition:
      </para>
      <screen><userinput>sudo yum -y install docbook-xsl dblatex</userinput></screen>
      <note>
	<para>
	  People working on git checkouts of the MIRA source code will
	  obviously need some more tools. Get them with this:
	</para>
	<screen><userinput>sudo yum -y install automake libtool xorg-x1-util-devel</userinput></screen>
      </note>
    </sect2>
    <sect2 id="sect_install_walkthroughs_osx">
      <title>
	Mac OSX
      </title>
      <para>
	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.
      </para>
      <para>
	If you do not already have it, install McPorts. See <ulink
	url="https://www.macports.org/install.php"/>. Then have the port
	system fetch information of the newest ports (can take a while):
      </para>
      <screen>
<userinput>sudo port selfupdate</userinput>
</screen>
      <para>
	Then go on and install gcc (this is going to take a long time) and
	then switch to gcc5:
      </para>
      <screen>
<userinput>sudo port install m4 gcc5</userinput>
<userinput>sudo port select --set gcc mp-gcc5</userinput>
</screen>
      <para>
	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
	<filename>/opt/biosw/gccchain</filename>
      </para>
      <para>
	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: <ulink
	url="https://sourceforge.net/p/flex/bugs/182/"/>. Configure flex to be
	installed into the directory you chose the step before:
      </para>
      <screen>
<userinput>tar xvf flex-2.6.0.tar.bz2</userinput>
<userinput>cd flex-2.6.0</userinput>
<userinput>./configure --prefix=<replaceable>/opt/biosw/gccchain</replaceable></userinput>
<userinput>make</userinput>
<userinput>make install</userinput>
</screen>
      <para>
	That done, proceed with likewise with expat and zlib library:
      </para>
      <screen>
<userinput>tar xvf expat-2.1.0.tar.gz</userinput>
<userinput>cd expat-2.1.0</userinput>
<userinput>./configure --prefix=<replaceable>/opt/biosw/gccchain</replaceable></userinput>
<userinput>make</userinput>
<userinput>make install</userinput>
<userinput>cd ..</userinput>
<userinput>tar xvf zlib-1.2.8.tar.gz</userinput>
<userinput>cd zlib-1.2.8</userinput>
<userinput>./configure --prefix=<replaceable>/opt/biosw/gccchain</replaceable></userinput>
<userinput>make -j 4</userinput>
<userinput>make install</userinput>
</screen>
      <para>
	The bzip2 library needs a different installation command line:
      </para>
<screen>
<userinput>tar xvf bzip2-1.0.6.tar.gz</userinput>
<userinput>cd bzip2-1.0.6</userinput>
<userinput>make -j 4</userinput>
<userinput>make install PREFIX=<replaceable>/opt/biosw/gccchain</replaceable></userinput>
</screen>
      <para>
	Last library to be installed for the MIRA compilation is BOOST:
      </para>
<screen>
<userinput>tar xvf boost_1_59_0.tar.bz2</userinput>
<userinput>cd boost_1_59_0</userinput>
<userinput>./bootstrap.sh --prefix=<replaceable>/opt/biosw/gccchain</replaceable></userinput>
<userinput>./b2 -j 4</userinput>
<userinput>./b2 install</userinput>
</screen>
      <para>
	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.
      </para>
<screen>
<userinput>tar xvf mira-5.0.0.tar.bz2</userinput>
<userinput>cd mira-5.0.0</userinput>
<userinput>./configure --enable-debug
  --with-boost=<replaceable>/opt/biosw/gccchain</replaceable>
  --with-boost-libdir=<replaceable>/opt/biosw/gccchain</replaceable>/lib
  --with-expat=<replaceable>/opt/biosw/gccchain</replaceable>
  --with-zlib=<replaceable>/opt/biosw/gccchain</replaceable></userinput>
<userinput>make -j 4</userinput>
</screen>
      <para>
	That's it for the dynamic version.
      </para>
      <para>
	For building an almost static version, we need some trickery: after
	the configure (this time with the mirastatic argument), create a
	special directory <filename>OSXstatlibs</filename> in which we
	softlink all static libraries MIRA needs. This directory will be
	searched first by the build scripts generated by the
	<command>libtool</command> suite during the linking stage of MIRA.
      </para>
<screen>
<userinput>./configure --enable-mirastatic --enable-debug
  --with-boost=<replaceable>/opt/biosw/gccchain</replaceable>
  --with-boost-libdir=<replaceable>/opt/biosw/gccchain</replaceable>/lib
  --with-expat=<replaceable>/opt/biosw/gccchain</replaceable>
  --with-zlib=<replaceable>/opt/biosw/gccchain</replaceable></userinput>
<userinput>mkdir OSXstatlib</userinput>
<userinput>cd OSXstatlib</userinput>
<userinput>ln -s /opt/biosw/gccchain/lib/*a</userinput>
<userinput>ln -s /opt/local/lib/*a</userinput>
</screen>
      <para>
	Note that <filename>/opt/local</filename> is the standard installation
	path of the MacPorts programs. If you changed that, you need to adapt
	it here, too.
      </para>
    </sect2>
    <sect2 id="sect_install_walkthroughs_allfromscratch">
      <title>
	Compile everything from scratch
      </title>
      <para>
	This lets you build a self-contained static MIRA binary. The only
	prerequisite here is that you have a working <command>gcc</command>
	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.
      </para>
      <para>
	Contributed by Sven Klages.
      </para>
      <screen>
## whatever path is appropriate
<userinput>cd <replaceable>/home/gls/SvenTemp/install</replaceable></userinput>

## expat
<userinput>tar zxvf <replaceable>expat-2.0.1.tar.gz</replaceable>
cd <replaceable>expat-2.0.1</replaceable>
./configure <replaceable>--prefix=/home/gls/SvenTemp/expat</replaceable>
make &amp;&amp; make install</userinput>

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

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

## mira itself
<userinput>export CXXFLAGS="-I<replaceable>/home/gls/SvenTemp/flex/include</replaceable>"

cd <replaceable>/home/gls/SvenTemp/install</replaceable>
tar zxvf <replaceable>mira-3.4.0.1.tar.gz</replaceable>
cd <replaceable>mira-3.4.0.1</replaceable>
./configure --prefix=<replaceable>/home/gls/SvenTemp/mira</replaceable> \
--with-boost=<replaceable>/home/gls/SvenTemp/boost</replaceable> \
--with-expat=<replaceable>/home/gls/SvenTemp/expat</replaceable> \
--enable-mirastatic
make &amp;&amp; make install</userinput></screen>
    </sect2>
    <sect2 id="sect_install_walkthroughs_dynamic">
      <title>
	Dynamically linked MIRA
      </title>
      <para>
	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.
      </para>
      <para>
	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.
      </para>
      <screen>
#!/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</screen>
    </sect2>
  </sect1>
  <sect1 id="sect_install_hintotherplatforms">
    <title>
      Compilation hints for other platforms.
    </title>
    <sect2 id="sect_install_hintnetbsd5">
      <title>
	NetBSD 5 (i386)
      </title>
      <para>
	Contributed by Thomas Vaughan
      </para>
      <para>
	The system flex <emphasis>(/usr/bin/flex)</emphasis> is too old, but the
	devel/flex package from a recent pkgsrc works fine. BSD make doesn't
	like one of the lines in <emphasis>src/progs/Makefile</emphasis>, so use GNU make instead
	(available from <emphasis>pkgsrc</emphasis> as <emphasis>devel/gmake</emphasis>). Other relevant pkgsrc packages:
	<emphasis>devel/boost-libs</emphasis>, <emphasis>devel/boost-headers</emphasis>
	and <emphasis>textproc/expat</emphasis>. The configure script has to
	be told about these pkgsrc prerequisites (they are usually rooted
	at <emphasis>/usr/pkg</emphasis> but other locations are possible):
      </para>
      <screen><userinput>FLEX=/usr/pkg/bin/flex ./configure --with-expat=/usr/pkg --with-boost=/usr/pkg</userinput></screen>
      <para>
	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 <emphasis>--with-boost</emphasis> option.  The configure script
	complains about flex being too old, but this is harmless because it
	honours the $FLEX variable when writing out makefiles.
      </para>
    </sect2>
  </sect1>
  <sect1 id="sect_install_notesformaintainers">
    <title>
      Notes for distribution maintainers / system administrators
    </title>
    <sect2 id="sect_install_additionaldatafiles">
      <title>
	Additional data files
      </title>
      <para>
	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:
	<filename>LOCATION_OF_BINARY/../share/mira/...</filename>
      </para>
      <para>
	That is: If the binary is, e.g.,
	<filename>/opt/mira5/bin/mira</filename> with a softlink pointing from
	<filename>/usr/local/bin/mira -> /opt/mira5/bin/mira</filename>
	(because, e.g., <filename>/usr/local/bin</filename> may be by default in your
	PATH variable), then the additional data will be searched in
	<filename>/opt/mira5/share/mira/...</filename> and NOT in
	<filename>/usr/local/share/mira/...</filename>.
      </para>
      <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.
      </note>
    </sect2>
  </sect1>
</chapter>
