
If you have any question, suggestion or bug report regarding compilation of
the MIRA package, please contact bach@chevreux.org

Contents:

I   Prerequisites in short:
II  Prerequisites for compiling
III Compiling & installing
IV  Building documentation
V   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. However, 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, since 2000, 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.

A few things that I noticed over the years on different systems are noted in
the "INSTALL" file.

Tested confugurations for compiling and running MIRA2 as of July 2007 ([ok]
means a working binary has been reported):

Working out-of-the-box::
[ok] Linux (OpenSUSE 10.x, AMD Athlon with x86 and x86_64)
[ok} Linux (Debian 4.0r0, Itanium ia64)

Some care needed:
[ok] FreeBSD 6.2 (i386)
     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.
[ok] MacOS X / Darwin. 
     Please make sure to have flex 2.5.33 installed.

Untested, but should be working at least with GNU GCC and GNU make:
[??] Solaris (last compiled in 2003 on an UltraSparc processor)
[??] OpenSolaris (not reported yet)
[??] NetBSD (not reported yet)
[??] HP-UX (not reported yet)
[??] SGI (last compiled in 2000 on Origin 2000)
[??] DEC alpha (MIRA last compiled on these in 2000)

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


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

Prerequisites in short:
=======================

Compiling MIRA: GNU make, GNU flex >=2.5.33, GCC >= 3.3, perl, Expat library
Compiling MIRA from CVS checkout: as above + GNU autoconf / automake
Building documentation: perl, latex, latex2man

Please read on to see what is used where.

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

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 is
   needed. Please see
   http://flex.sourceforge.net/ for more information regarding flex.

   Some architectures (older Solaris) have broken flex implementations. Either
   install a current version or change in the system FlexLexer.H file:

   ++++++++++++++++++++++++++++++++++
   #include <iostream.h>

   to:

   #include <iostream>
   #include <istream>
   #include <ostream>

   using std::istream;
   using std::ostream;
   ++++++++++++++++++++++++++++++++++

   A third possibility is to use a hack in "Makefile.am" in the directories
     ./src/io/
     ./src/caf/
     ./src/EdIt/
     ./src/mira/
   There is a working rule for flex and an uncommented one. Just comment the
   current rule and uncomment the commented one.

3) Any GNU C/C++ compiler >= 3.3 (eventually also 3.1, but not sure?) should
   work fine, the current version 4.1 (or later) is highly recommended
   though. Please note that the GNU 2.x C/C++ compiler does NOT work for MIRA
   anymore (for a few years now). Please refer to http://gcc.gnu.org/ for more
   information on the GNU compiler collection.

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

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

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

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.


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

MIRA honours the following 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-static

  Builds static binaries which are easier to distribute.


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


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



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.


Know issues / bugs
------------------

MIRA probably has bugs in progress display while loading files >4GB. Loading
*should* be fine though (not verified as I never had that many sequences).

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

Building documentation
======================

The user documentation is currently written in LaTeX, using special package
commands from the 'latex2man' package (which in turn needs perl). This allows
building man pages, HTML pages and info pages as well as quite painlessly some
include files for LaTeX files.

For more information on latex2man see
http://ctan.tug.org/tex-archive/support/latex2man/latex2man.html

For building the documentation, make sure that latex2man is installed on your
system and then type "make docs". Then copy the files in ./doc/docs/man/,
./doc/docs/html/ or ./doc/docs/texinfo/ to any place convenient to you.

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

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.

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

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.
