
If you have any question, suggestion or bug report regarding compilation of
the MIRA package, please subscribe to the MIRA talk mailing list (see
http://www.chevreux.org/mira_mailinglists.html) and send your question to:
mira_talk@freelists.org

Contents:

I    Prerequisites in short:
II   Prerequisites for compiling
III  Compiling & installing
IV   Building documentation
V    Example: how to compile on (K)Ubuntu 9.04 / 9.10
VI   Example: how to compile on NetBSD 5 (i386)
VII  Example: how to compile on Mac OSX 10.6 (Snow Leopard)
VIII Basic Installation (from the generic GNU autoconf documentation)


IMPORTANT NOTICE for compiling on non Linux systems
===================================================

Your FEEDBACK is needed!

MIRA started as project in 1997 using an SGI machine (Origin 2000 if memory
serves well) and the SGI C++ compiler. I regularly built and tested the
package using GCC (2.95.x at that time) also on SunOS and Linux in those
days. Infrequent compilation runs on HP-UX and DEC alpha were also successful.

However, between 2000 and 2006, I've had no other system than GCC with
different Linux kernels on x86 and x86-64 CPUs (and occasionally an older SUN
Solaris system). I fear that the first compilation attempts now will uncover a
number of problems, although I expect/hope that these should be quickly and
easily fixed.

Tested configurations for compiling and running MIRA3 as of May 2010 ([ok]
means a working binary has been reported):


Working out-of-the-box (once needed libraries and programs are installed):
--------------------------------------------------------------------------
[ok] Linux: (K)Ubuntu 8.04, 8.10, 9.04 and 10.04 with x86, x86_64 and Atom
[ok] Linux: OpenSUSE 10.x, 11.1 with x86 and x86_64
[ok} Linux: Debian 4.0r0, Itanium ia64
[ok] Linux: Debian lenny with x86_64.
[ok] Linux: Fedora Redhat 12 with x86
[ok] MacOS X 10.6.1 and 10.5.8


Some care needed:
-----------------
[ok] Linux: OpenSUSE 11.0 on x86_64: you might need
     --with-boost-libdir=/usr/lib64
[ok] OpenSolaris: must have built BOOST with the GNU toolchain, must give
     ./configure the "--enable-64" flag
[ok] Netbsd 5 (i386). See "Example: how to compile on NetBSD 5 (i386)"
[ok] CentOS: you might need to configure like this:
     LDFLAGS="$LDFLAGS -L/usr/lib64" LIBS="-lexpat" ./configure


Untested, but should be working at least with GNU GCC and GNU make:
-------------------------------------------------------------------
[??] Solaris 10 (sparc) (it worked for versions without boost) 
[??] Solaris 9 (sparc) (it worked for versions without boost)
[??] HP-UX (it worked in 2000, but not tested lately)
[??] SGI (last compiled in 2000 on Origin 2000)
[??] DEC alpha (MIRA last compiled on these in 2000)
[??] FreeBSD 6.2 (i386)
     This used to work prior to inclusion of BOOST libraries. Must be
     re-tested.
     The "make" utility of FreeBSD doesn't like some rules used. Please use
     the GNU make. 
     If you can, please submit a rule patch so that both FreeBSD make and GNU
     work.


Unknown:
--------
[??] Linux for PPC processors


Known to fail:
[nok] HP-UX (B.11.31, ia64) with aCC
      Does not build with aCC and STL delivered with aCC (lacks hash_map and
      slist). This could perhaps work with an installed version of
      the STL-Port project, untested.


I would be glad to hear back on successes (or failures) on other systems,
patches in case of failure are even more welcome :-)


-------------------------------------------------------------------------------

I) Prerequisites in short:
==========================

Compiling MIRA: 
- GCC 4.1.2, but higher version is recommended
  libstc++6 Or whichever version is current for your system. This should be
    installed on many system by default, on others installing gcc will
    automatically trigger the installation of that lib. If not, you have to
    install it by hand.
- BOOST library >= 1.35 (lower versions might work, but untested. You would
    need to change the checking in the configure script for this to run
    through)
    DO NOT use a staged library, only a fully installed library will work at
    the moment
- zlib library
- GNU make, 
- GNU flex >=2.5.33, 
- perl,
- Expat library
- recommended: the TCmalloc library from the Google perftools, version 1.5 or
  higher (lower might work, but untested)

Compiling MIRA from CVS checkout: as above + GNU autoconf / automake
Building documentation: DocBook (for HTML: xsltproc + docbook-xsl;
                                 additionally for PDF: dblatex)

Please read on to see what is used where, there are examples for specific
systems at the end of this file.

-------------------------------------------------------------------------------

II) Prerequisites for compiling
===============================

These prerequisites are for compiling only, not for running a compiled program
version.

1) MIRA uses the excellent Expat library to parse XML files. Should your
   system not have the Expat library and header files already installed, you
   will need to download and install a version. Please see
   http://www.libexpat.org/ and http://sourceforge.net/projects/expat/ for
   information on how to do this.

2) MIRA needs the GNU 'flex' lexical analyser. Version 2.5.33 (or later) is
   needed. Please see
   http://flex.sourceforge.net/ for more information regarding flex.

3) Any GNU C/C++ compiler >= 4.1.2 should work fine. Please note that the GNU
   2.x and 3.x C/C++ compiler do NOT work for MIRA anymore. Please refer to
   http://gcc.gnu.org/ for more information on the GNU compiler collection.

4) Since version 2.9.28x6, MIRA uses functions of the BOOST C++ library (at
   the time of this writing the thread and bind libraries). Currently, only
   version 1.36 and above have been tested, Versions >= 1.35 should work,
   versions below ... unsure, must be tested (adapt the version check in the
   configure.in file if you want to test).  You MUST have a fully installed
   version (but that can live anywhere in your file system, even your HOME),
   staged libraries confuse the configure program and apparently won't be
   recognised correctly.  
   It's probable that the library must be compiled with the gcc toolchain
   option, this has been at least reported to be the case for Solaris where a
   BOOST compiled with CC did not link.

5) A working perl needs to be in your path for compiling.
   REMARK: it's needed in the src/progs directory to transform 
   text files into something which is directly includable by a C/C++
   compiler. Perhaps this could be solved differently?

6) When working from a CVS checkout, you need to have the GNU autoconf and
   automake on your system. Type "sh ./runme-first" in the top-level of the
   directory tree (where this file is located), then you can go on with the
   normal "./configure" routine (see below).

7) It is totally, absolutely, most highly recommended to have MIRA linked to
   the tcmalloc_minimal library. MIRA will also work without, but memory
   requirements may then be a *lot* higher (40% and more).

   Installing is easy. Get the current version (1.5 or higher) from 
     http://code.google.com/p/google-perftools/downloads/list
   and put it into a temporary directory.

   Unpack it, perform a basic configure of the minimal package, and install
   that normally with this:

     tar xvzf google-perftools-1.5.tar.gz
     cd google-perftools-1.5
     ./configure --enable-minimal
     make
     make install

   The last command needs root rights. Use 'sudo' ("sudo make install") or ask
   a system administrator to do that. You can also install the library
   somewhere else, but then the MIRA configure will need to know the location
   (see below).


-------------------------------------------------------------------------------

III) Compiling & installing
===========================

MIRA uses the GNU autoconf/automake tools, please read the section "Basic
Installation" for more generic information on how to invoke them.

The short version: simply type "./configure"; then "make"; then "make
install". This should install the following programs: 
- mira 
- convert_project
- fastatool  
- scftool 
- uncover_at

Should the "./configure" step fail for some reason or another, you should get
a message telling you at which step this happens and be able to install
missing packages.

Although this should not be needed if you are compiling from a source
distribution, you can rebuild the configure script for your system when having
GNU autoconf and automake tools installed. Just run "sh runme.first" script
(may take a while) in the top directory and you should be good to go.


Configure switches for MIRA:
----------------------------

MIRA understands all standard autoconf configure switches like --prefix=
etc. Please consult the chapter "Basic installation" further below, which is
taken from configure manual.


BOOST configure switches for MIRA:
----------------------------------

If a simple "./configure" and then "make" fails at the linker stage, you might
need to perform the "./configure" with additional flags telling it where the
version of BOOST that you want to use is installed. Those flags would be
"--with-boost[=DIR]", "--with-boost-libdir=LIB_DIR" or
"--with-boost-thread[=special-lib]". On how to use these flags, please consult
the help given by "./configure --help" or the documentation of BOOST
(http://www.boost.org).


TCmalloc configure switches for MIRA:
-------------------------------------

If you installed ther perftools library in standard locations you won't need
any special switches, the MIRA-configure will link to it automatically. If you
installed these libraries at a special location (I do not recommend that), you
can use

--with-tcmalloc-dir=LIB_DIR

where LIB_DIR is the directory where libtcmalloc.a resides

You can switch off linking MIRA with TCmalloc completely with

--with-tcmalloc=no

but I *strongly* recommend not to do this. MIRA will work, though memory
requirements will then be much higher (40% and more)


EMBOSS configure switches when compiling MIRA:
----------------------------------------------

MIRA honours the following EMBOSS switches (all others will simply have no
effect)

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


--enable-warnings

  Enables compiler warnings, however a lot more switches are used for GCC
  compared to the EMBOSS defaults.


--enable-debug
--enable-purify

  Both these switches keep the same meaning as for EMBOSS.



Special configure switches for MIRA:
------------------------------------

There are currently a number of switches to configure that are specific to
MIRA:

--enable-mirastatic

  Builds static binaries which are easier to distribute. Some platforms (like
  OpenSolaris) might not like this, you 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=yes/no to have mira assemble quietly; default=yes

  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


--enable-extendedbugtracking

  When set to "yes", this compiles in extra checks into mira that look for
  sanity within some functions. Contrary to the other checks above, this
  extended bugtracking *is* costly and impacts runtime noticeably, use only
  for bughunting on core dumps or similar. Note that I haven't had MIRA core
  dumping on me in the last 4 years or so ... it really isn't needed in normal
  production environments.


--enable-functrace

  When enabled, traces every function call and function exit on stdout during
  assembly. Setting function trace to "yes" is *highly* discouraged except for
  toy projects, you'll quickly get gigabytes of output.



Issues when doing "make install"
--------------------------------

- docs are currently not build as I doubt many people have LaTeX2man as
  tool. I need to find out how to remediate this problem by distributing
  pre-made help files.
- I've had a report that on some platforms, a "chmod +x install-sh "prior to
  make install is needed. To be checked.



-------------------------------------------------------------------------------

IV) Building documentation
==========================

DocBook

For building HTML, install:

  sudo apt-get install xsltproc docbook-xsl

For building PDF, install

  sudo apt-get install dblatex


-------------------------------------------------------------------------------

Building a precompiled binary distribution package
==================================================

A package containing precompiled binaries, documentation and some demo
projects can be built with "make distrib". When built from the top-level
directory, binaries are compiled (if needed) and documentation is built (also
if needed) before packaging.

The resulting package can be found in the "distribution" directory.

-------------------------------------------------------------------------------

Building a source package distribution package
==============================================

To build a slimmed down, self-contained source package (in .tar.gz and
.tar.bz2 format) that leaves out CVS files/directories as well as a number of
test files and directories, use the standard automake 'make dist' command from
the top-level directory.


-------------------------------------------------------------------------------

V) Example: how to compile on (K)Ubuntu 9.04 / 9.10
===================================================

Before compiling, make sure you have everything you need to compile MIRA. The
following commands will install the needed packages (BOOST, expat and flex)
for you if they're not yet installed.

For (K)Ubuntu 9.04:
-------------------
Install the Google perftools library like explained in section III

Then:
  sudo apt-get install libboost-doc libboost.*1.37-dev libboost.*1.37.0
  sudo apt-get install libexpat1-dev flex zlib1g-dev

For (K)Ubuntu 9.10:
-------------------
Like 9.04. Just change:
  sudo apt-get install libboost-doc libboost.*1.37-dev libboost.*1.37.0
to:
  sudo apt-get install libboost-doc libboost.*1.38-dev libboost.*1.38.0
The three remaining sudo lines should be typed without change.


Now, this example assumes you donwloaded the source package
"mira-3.0.6.tar.bz2" (you might have another version, but that's ok), then the
following steps that are guaranteed to give you a binary (32 bit on 32 bit
systems, 64 bit on 64 bit systems):

  tar xvjf mira-3.0.6.tar.bz2
  cd mira-3.0.6
  ./configure
  make

The binaries will then be in src/progs. If you want to install them system
wide, simply type:

  sudo make install

That's all.


For CVS checkouts:
------------------
In case you are running a CVS checkout, you will need to install a few
packages in addition to BOOST, expat and flex (see above) to be able to run
the "runme.first" script:

  sudo apt-get install automake libtool xutils-dev

Now, go into the CVS checkout directory and run the "runme.first" script

  sh runme.first

Then

  ./configure
  make

That's it.




VI) Example: how to compile on NetBSD 5 (i386)
==============================================

Install the Google perftools library like explained in section III. Then:

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, textproc/expat and lang/perl.  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.



VII) Example: how to compile on Mac OSX 10.6 (Snow Leopard)
===========================================================

This has been tested on OSX 10.6.4. You will need XCode (from Apple) and some
packages from MacPorts. Note that I used XCode 3.2.5 and MacPorts 1.9.2
(downloading BOOST 1.45). Lower versions of all of the above *might* work, but
not necessarily so.

1. Download and install a current XCode
   
2. Install BOOST from MacPorts
   a) if you haven't already done so, install MacPorts
      Basically, just a couple of easy steps, see
        http://www.macports.org/install.php
   b) Install BOOST: in a terminal, type
        sudo port install boost

      Note 1: for universal builds (e.g. for distributing MIRA with universal
      binaries) rather do
        sudo port install boost +universal

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

3. Download the MIRA source package and unpack it

4. ./configure
   make

5. Done :-)




VIII) Basic Installation
========================

-------------------------------------------------------------------------------
The following is taken straight out of the GNU configure documentation
-------------------------------------------------------------------------------

Basic Installation
==================

   These are generic installation instructions.

   The `configure' shell script attempts to guess correct values for
various system-dependent variables used during compilation.  It uses
those values to create a `Makefile' in each directory of the package.
It may also create one or more `.h' files containing system-dependent
definitions.  Finally, it creates a shell script `config.status' that
you can run in the future to recreate the current configuration, a file
`config.cache' that saves the results of its tests to speed up
reconfiguring, and a file `config.log' containing compiler output
(useful mainly for debugging `configure').

   If you need to do unusual things to compile the package, please try
to figure out how `configure' could check whether to do them, and mail
diffs or instructions to the address given in the `README' so they can
be considered for the next release.  If at some point `config.cache'
contains results you don't want to keep, you may remove or edit it.

   The file `configure.in' is used to create `configure' by a program
called `autoconf'.  You only need `configure.in' if you want to change
it or regenerate `configure' using a newer version of `autoconf'.

The simplest way to compile this package is:

  1. `cd' to the directory containing the package's source code and type
     `./configure' to configure the package for your system.  If you're
     using `csh' on an old version of System V, you might need to type
     `sh ./configure' instead to prevent `csh' from trying to execute
     `configure' itself.

     Running `configure' takes awhile.  While running, it prints some
     messages telling which features it is checking for.

  2. Type `make' to compile the package.

  3. Optionally, type `make check' to run any self-tests that come with
     the package.

  4. Type `make install' to install the programs and any data files and
     documentation.

  5. You can remove the program binaries and object files from the
     source code directory by typing `make clean'.  To also remove the
     files that `configure' created (so you can compile the package for
     a different kind of computer), type `make distclean'.  There is
     also a `make maintainer-clean' target, but that is intended mainly
     for the package's developers.  If you use it, you may have to get
     all sorts of other programs in order to regenerate files that came
     with the distribution.

Compilers and Options
=====================

   Some systems require unusual options for compilation or linking that
the `configure' script does not know about.  You can give `configure'
initial values for variables by setting them in the environment.  Using
a Bourne-compatible shell, you can do that on the command line like
this:
     CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure

Or on systems that have the `env' program, you can do it like this:
     env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure

Compiling For Multiple Architectures
====================================

   You can compile the package for more than one kind of computer at the
same time, by placing the object files for each architecture in their
own directory.  To do this, you must use a version of `make' that
supports the `VPATH' variable, such as GNU `make'.  `cd' to the
directory where you want the object files and executables to go and run
the `configure' script.  `configure' automatically checks for the
source code in the directory that `configure' is in and in `..'.

   If you have to use a `make' that does not supports the `VPATH'
variable, you have to compile the package for one architecture at a time
in the source code directory.  After you have installed the package for
one architecture, use `make distclean' before reconfiguring for another
architecture.

Installation Names
==================

   By default, `make install' will install the package's files in
`/usr/local/bin', `/usr/local/man', etc.  You can specify an
installation prefix other than `/usr/local' by giving `configure' the
option `--prefix=PATH'.

   You can specify separate installation prefixes for
architecture-specific files and architecture-independent files.  If you
give `configure' the option `--exec-prefix=PATH', the package will use
PATH as the prefix for installing programs and libraries.
Documentation and other data files will still use the regular prefix.

   In addition, if you use an unusual directory layout you can give
options like `--bindir=PATH' to specify different values for particular
kinds of files.  Run `configure --help' for a list of the directories
you can set and what kinds of files go in them.

   If the package supports it, you can cause programs to be installed
with an extra prefix or suffix on their names by giving `configure' the
option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.

Optional Features
=================

   Some packages pay attention to `--enable-FEATURE' options to
`configure', where FEATURE indicates an optional part of the package.
They may also pay attention to `--with-PACKAGE' options, where PACKAGE
is something like `gnu-as' or `x' (for the X Window System).  The
`README' should mention any `--enable-' and `--with-' options that the
package recognizes.

   For packages that use the X Window System, `configure' can usually
find the X include and library files automatically, but if it doesn't,
you can use the `configure' options `--x-includes=DIR' and
`--x-libraries=DIR' to specify their locations.

Specifying the System Type
==========================

   There may be some features `configure' can not figure out
automatically, but needs to determine by the type of host the package
will run on.  Usually `configure' can figure that out, but if it prints
a message saying it can not guess the host type, give it the
`--host=TYPE' option.  TYPE can either be a short name for the system
type, such as `sun4', or a canonical name with three fields:
     CPU-COMPANY-SYSTEM

See the file `config.sub' for the possible values of each field.  If
`config.sub' isn't included in this package, then this package doesn't
need to know the host type.

   If you are building compiler tools for cross-compiling, you can also
use the `--target=TYPE' option to select the type of system they will
produce code for and the `--build=TYPE' option to select the type of
system on which you are compiling the package.

Sharing Defaults
================

   If you want to set default values for `configure' scripts to share,
you can create a site shell script called `config.site' that gives
default values for variables like `CC', `cache_file', and `prefix'.
`configure' looks for `PREFIX/share/config.site' if it exists, then
`PREFIX/etc/config.site' if it exists.  Or, you can set the
`CONFIG_SITE' environment variable to the location of the site script.
A warning: not all `configure' scripts look for a site script.

Operation Controls
==================

   `configure' recognizes the following options to control how it
operates.

`--cache-file=FILE'
     Use and save the results of the tests in FILE instead of
     `./config.cache'.  Set FILE to `/dev/null' to disable caching, for
     debugging `configure'.

`--help'
     Print a summary of the options to `configure', and exit.

`--quiet'
`--silent'
`-q'
     Do not print messages saying which checks are being made.  To
     suppress all normal output, redirect it to `/dev/null' (any error
     messages will still be shown).

`--srcdir=DIR'
     Look for the package's source code in directory DIR.  Usually
     `configure' can determine that directory automatically.

`--version'
     Print the version of Autoconf used to generate the `configure'
     script, and exit.

`configure' also accepts some other, not widely useful, options.

