INSTALL
=======

                                 EXACUS
           Efficient and Exact Algorithms for Curves and Surfaces
         Max-Planck-Institut für Informatik in Saarbrücken, Germany
               http://www.mpi-inf.mpg.de/projects/EXACUS/

This document describes the installation process of EXACUS. Generic
installation instructions for autoconf based projects can be found in
INSTALL.generic.


Table of contents
=================

1. Prerequisites
1.1. Files
1.2. Platforms
1.3. Tools
1.4. Compiler
1.5. Libraries
1.5.1. Boost
1.5.2. LEDA
1.5.3. CGAL
1.5.4. Qt
1.5.5. GMP
1.5.6. CORE
1.5.7. BMTools
2. Building EXACUS
2.1. Configuring
2.2. Building



1. Prerequisites
================


1.1. Files
==========

EXACUS consists of three tarballs, namely

  - exacus-<version>.tar.{gz,bz2}
  - exacus-as-<version>.tar.{gz,bz2}
  - exacus-doc-<version>.tar.{gz,bz2}

The first two archives are mandatory and comprise the complete source code
of EXACUS. The files have been split into two archives due to different
licenses (see file LICENSE for details).

The last archive is optional and contains the documentation in HTML format.
The documentation can also be generated during the build process (see below).
You will need GNU tar to extract the contents of this archive, tar
implementations of other vendors might not work (see also section 1.3 Tools).

Both (all three) archives should be extracted from the same directory such
that their contents together form the complete source tree.


1.2. Platforms
==============

EXACUS has been tested under Linux, in particular Debian Sarge and Debian
Etch. Other Unix platforms are currently not supported, but might probably
work. Earlier versions of EXACUS worked fine on Solaris 9, but we were not
able to verify that for this release. Windows is not supported and there are
no plans to do so.


1.3. Tools
==========

We use several GNU tools, such as make, sed, tar, and grep. All these tools
are available on Linux systems. If you use Solaris or another Unix platform, 
please make sure that the GNU versions of these tools are used and not 
those provided by the operating system.


1.4. Compiler
=============

EXACUS has been successfully tested with g++ 3.3 and g++ 4.1. It should also
work fine with g++ 3.4 and g++ 4.0.

Note that the ABI format was changed with g++ 3.4. Depending on your platform,
it might not be possible to link object code compiled for different ABI
formats. Thus it is highly recommended to compile EXACUS with the same
compiler as all C++ libraries used with EXACUS.


1.5. Libraries
==============

EXACUS makes use of various other libraries, mainly for number types and
visualization. Most of these libraries are optional and not required. Some
functionality of EXACUS might be missing if an optional library is not 
present.


1.5.1. Boost
------------

URL: http://www.boost.org/
Version: >= 1.32.0 
Importance: required
Configure option: --with-boost=...

The Boost library is used for its interval data types.

There is no need to compile Boost, since EXACUS make only use of code 
located in header files of Boost.


1.5.2. LEDA
-----------

URL: http://www.algorithmic-solutions.com/enleda.htm
Version: >= 4.4.1 (5.x is recommended)
Importance: optional, recommended
Configure option: --with-leda=...

For number types use LEDA or CORE.
LEDA is also needed for the internal data structures of the sweep line 
algorithm in SweepX and for the visualization in demo programs of ConiX .

Note: g++ 3.4 and later require LEDA >= 5.0.

Building shared libraries is recommended.


1.5.3. CGAL
-----------

URL: http://www.cgal.org/
Version: >= 3.2
Importance: optional
Configure option: --with-cgal-makefile=...

SweepX offers a valid traits class for CGAL::Arrangement_2.

If LEDA is available, it is mandatory to enable LEDA support in CGAL.


1.5.4. Qt
---------

URL: http://www.trolltech.com/products/qt/
Version: >= 3.3, < 4.0
Importance: optional, minor importance
Configure option: --with-qt=...

The Qt library is our future choice for the visualization in demo programs,
but is not really used in this release.

Ensure that your Qt installation was configured with support for OpenGL
(Qt configure option -enable-opengl). Support for threading is recommended, 
but not necessary (Qt configure option -thread). 


1.5.5. GMP
----------

URL: http://www.swox.com/gmp/
Version: >= 4.1.2, < 4.2
Importance: optional
Configure option: --with-gmp=...

GMP is needed for CORE, and GMP support has been added to EXACUS as a 
matter of completeness.

Ensure that your GMP installation was configured with support for MPFR 
and C++ (GMP configure options --enable-mpfr and --enable-cxx).


1.5.6. CORE
-----------

URL: http://cs.nyu.edu/exact/core/
Version: >= 1.7
Importance: optional
Configure option: --with-core=...

CORE is a freely available alternative for the LEDA number types, including
CORE::Expr as an alternative to leda::real.

It is recommended to build optimized and shared libraries. See the CORE
documentation for details.


1.5.7. BMTools
--------------

URL: http://www.mpi-inf.mpg.de/projects/exacus/
Version: any
Importance: optional
Configure option: --with-bmtools=...

BMTools offers an standardized interface for reading benchmark data files
of curved objects.

It is needed for benchmarking conic and conic arc instances by
ConiX/demos/benchmarkCnX and ConiX/demos/sweepCnX.



2. Building EXACUS
==================


2.1 Configuring
===============

EXACUS uses autoconf to provide a configure script. Important options are:

  --prefix=PREFIX            install files in PREFIX  [/usr/local]
  --enable-debug             enable debugging  [off]
  --enable-optimize          enable extra optimization  [off]  (see below)
  --with-boost=DIR           Boost is installed in DIR  [$EXACUS_BOOST]
  --with-leda=DIR            LEDA is installed in DIR  [$EXACUS_LEDA]
  --with-cgal-makefile=FILE  CGAL makefile that should be used
                               [$EXACUS_CGAL_MAKEFILE]
  --with-qt=DIR              Qt is installed in DIR  [$EXACUS_QT]
  --with-gmp=DIR             GMP is installed in DIR  [$EXACUS_GMP]
  --with-core=DIR            CORE is installed in DIR  [$EXACUS_CORE]
  --with-bmtools=DIR         BMTools is installed in DIR  [$EXACUS_BMTOOLS]

For a full list of options, type "configure --help". Defaults are given in
brackets. The environment variables LEDAROOT, CGAL_MAKEFILE and QTDIR are
used as defaults if the respective variables with prefix EXACUS are empty.

Enabling optimization may result in very long compilation runs (up to
4 hours on a Pentium IV). Compilation of some tests is known to need about
15 minutes if optimization is enabled.

The long compilation runs are mainly due to the amount of inlining. The extent
of inlining can be controlled with the compiler flag -finline-limit which
defaults to 600 for current versions of gcc. The lower the value, the lesser
inlining is performed and the faster is the compilation.

Experiments have shown that setting this parameter to a value of 400 reduces
the compilation time to one third while the running time of the resulting
binaries increases only by 2%. We strongly recommend setting

  export CXXFLAGS="-finline-limit=400"

when --enable-optimize is used.


2.2 Building
============

The following make targets are supported:

  make                 build libraries and demos
  make check           build tests and benchmarks
  make install         install libraries and demos
  make doc             build documentation
  make doc-install     install documentation

Building the documentation requires doxygen; we enabled the support of the 
graphviz package in doxygen to obtain nice dependency graph diagrams. We 
also need LaTeX for typesetting formulas with doxygen.

Documentation generated by doxygen differs much depending on the doxygen 
version. Best results have been achieved with version 1.4.2. We also offer 
a separate archive that contains all the documentation.