gecoder-with-gecode 0.7.1

data/ext/gecode-1.3.1/doxygen.hh.in

@@ -0,0 +1,877 @@
+/*
+ *  Main authors:
+ *     Christian Schulte <schulte@gecode.org>
+ *     Guido Tack <tack@gecode.org>
+ *
+ *  Copyright:
+ *     Christian Schulte, 2005
+ *     Guido Tack, 2005
+ *
+ *  Last modified:
+ *     $Date: 2006-10-24 23:25:59 +0200 (Tue, 24 Oct 2006) $ by $Author: tack $
+ *     $Revision: 3782 $
+ *
+ *  This file is part of Gecode, the generic constraint
+ *  development environment:
+ *     http://www.gecode.org
+ *
+ *  See the file "LICENSE" for information on usage and
+ *  redistribution of this file, and for a
+ *     DISCLAIMER OF ALL WARRANTIES.
+ *
+ */
+
+/*
+ * No code, just contains the group definitions of the
+ * Doxygen-generated documentation
+ */
+
+
+/**
+ * \defgroup Task Functionality by programming task
+ */
+
+/**
+ * \defgroup TaskInt Interfacing to Gecode
+ * \ingroup Task
+ */
+
+/**
+ * \defgroup TaskIntScript Setting up scripts
+ *
+ * Scripts (or models) are programmed by inheriting from the class
+ * Gecode::Space. For many examples see \ref Example.
+ *
+ * \ingroup TaskInt
+ */
+
+/**
+ * \defgroup TaskIntInt Using finite domain integers
+ * \ingroup TaskInt
+ */
+
+/**
+ * \defgroup TaskIntIntVars Integer variables
+ * \ingroup TaskIntInt
+ */
+
+/**
+ * \defgroup TaskIntSearch Search engines
+ *
+ * Defines search engines. All search engines (but Gecode::LDS, where
+ * it is not needed) support recomputation. The behaviour of recomputation
+ * can be controlled by two parameters:
+ *  - \a c_d as minimal recomputation distance: this guarantees that
+ *    a path between two nodes in the search tree for which copies are
+ *    stored has at least length \a c_d. That is, in order to recompute
+ *    a node in the search tree, \a c_d recomputation steps are needed.
+ *    The minimal recomputation distance yields a guarantee on saving
+ *    memory compared to full copying: it stores \a c_d times less nodes
+ *    than full copying.
+ *  - \a a_d as adaptive recomputation distance: when a node needs to be
+ *    recomputed and the path is longer than \a a_d, an intermediate copy
+ *    is created (approximately in the middle of the path) to speed up
+ *    future recomputation. Note that small values of \a a_d can increase
+ *    the memory consumption considerably.
+ *
+ * Full copying corresponds to a maximal recomputation distance \a c_d of 1.
+ *
+ * All recomputation performed is based on batch recomputation: batch
+ * recomputation performs propagation only once for an entire path
+ * used in recomputation.
+ *
+ * Requires \code #include "gecode/search.hh" \endcode
+ * \ingroup TaskInt
+ */
+
+/**
+ * \defgroup TaskIntSet Using finite integer sets
+ * \ingroup TaskInt
+ */
+
+/**
+ * \defgroup TaskIntSetVars Set variables
+ * \ingroup TaskIntSet
+ */
+
+/**
+ * \defgroup TaskMiniModel Direct modelling
+ * \ingroup Task
+ */
+
+/**
+ * \defgroup TaskSearch Programming search engines
+ * \ingroup Task
+ */
+
+/**
+ * \defgroup TaskActor Programming actors
+ * \ingroup Task
+ */
+
+/**
+ * \defgroup TaskActorInt Programming integer actors
+ * \ingroup TaskActor
+ */
+
+/**
+ * \defgroup TaskActorSet Programming set actors
+ * \ingroup TaskActor
+ */
+
+/**
+ * \defgroup TaskVar Programming variables
+ * \ingroup Task
+ */
+
+/**
+ * \defgroup TaskVarView Programming views for variables
+ * \ingroup TaskVar
+ */
+
+/**
+ * \defgroup Func Common functionality
+ */
+
+/**
+ * \defgroup FuncMem Memory management
+ * \ingroup Func
+ */  
+
+/**
+ * \defgroup FuncThrow Gecode exceptions
+ * \ingroup Func
+ */
+
+/**
+ * \defgroup FuncSupport Support algorithms and datastructures
+ *
+ * These are some common datastructures used in the implementation of
+ * %Gecode. Maybe they can be also useful to others.
+ *
+ * In order to use them, one needs to include the appropriate header-file
+ * as described in the class and function documentation.
+ * \ingroup Func
+ */  
+
+/**
+ * \defgroup FuncIter Range and value iterators
+ *
+ * Both range and value iterators have a rather simple interface
+ * for controlling iteration (which deviates from what you might be
+ * used to from other iterators).
+ *
+ * The application operator (if \c i is an iterator, it is invoked by \c i() )
+ * tests whether an iterator has not yet reached
+ * its end (in this case, \c true is returned). The prefix
+ * increment operator (if \c i is an iterator, this is invoked as \c ++i)
+ * moves the iterator to the next element (either next value or next range).
+ *
+ * Value iterators provide access to the value by the member function
+ * \c val(). Range iterators provide access to the smallest, largest, and
+ * width of the current range by \c min(), \c max(), and \c width()
+ * respectively.
+ * 
+ * Requires \code #include "gecode/iter.hh" \endcode
+ * \ingroup Func
+ */
+
+/**
+ * \defgroup FuncIterRanges Range iterators
+ *
+ * A range iterator provides incremental access to a sequence of increasing
+ * ranges.
+ *
+ * Requires \code #include "gecode/iter.hh" \endcode
+ * \ingroup FuncIter
+ */
+
+/**
+ * \defgroup FuncIterRangesVirt Range iterators with virtual member functions
+ *
+ * A range iterator provides incremental access to a sequence of increasing
+ * ranges. Iterators with virtual member functions have to be used when
+ * they are combined dynamically, and the actual types hence cannot be
+ * specified as template arguments.
+ *
+ * Requires \code #include "gecode/iter.hh" \endcode
+ * \ingroup FuncIterRanges
+ */
+
+/**
+ * \defgroup FuncIterValues Value iterators
+ *
+ * A value iterator provides incremental access to a sequence of increasing
+ * values. 
+ *
+ * Requires \code #include "gecode/iter.hh" \endcode
+ * \ingroup FuncIter
+ */
+
+/**
+ * \defgroup FuncIterValuesVirt Value iterators with virtual member functions
+ *
+ * A value iterator provides incremental access to a sequence of increasing
+ * values. Iterators with virtual member functions have to be used when
+ * they are combined dynamically, and the actual types hence cannot be
+ * specified as template arguments.
+ *
+ * Requires \code #include "gecode/iter.hh" \endcode
+ * \ingroup FuncIterValues
+ */
+
+/**
+ * \defgroup Other Other available functionality
+ *
+ */
+
+/**
+ * \defgroup FuncIntProp Integer propagators
+ *
+ * This module contains a description of all predefined integer 
+ * propagators. They can be reused, for example, for rewriting
+ * newly defined integer propagators into already available
+ * propagators.
+ * \ingroup Other
+ */
+
+/**
+ * \defgroup FuncIntSelView Integer view selection for branching
+ *
+ * Contains a description of view selection strategies on integer
+ * views that can be used together with the generic view/value
+ * branching class Gecode::ViewValBranching (argument \a ViewSel).
+ *
+ * All view selection classes require 
+ * \code #include "gecode/int/branch.hh" \endcode
+ * \ingroup Other
+ */
+
+/**
+ * \defgroup FuncIntSelVal Integer value selection for branching
+ *
+ * Contains a description of value selection strategies on integer
+ * views that can be used together with the generic view/value
+ * branching class Gecode::ViewValBranching (argument \a ValSel).
+ *
+ * All value selection classes require 
+ * \code #include "gecode/int/branch.hh" \endcode
+ * \ingroup Other
+ */
+
+/**
+ * \defgroup FuncSetProp Set propagators
+ *
+ * This module contains a description of all predefined finite set
+ * propagators. They can be reused, for example, for rewriting
+ * newly defined finite set propagators into already available
+ * propagators.
+ * \ingroup Other
+ */
+
+/**
+ * \defgroup FuncSetSelView Set view selection for branching
+ *
+ * Contains a description of view selection strategies on set
+ * views that can be used together with the generic view/value
+ * branching class Gecode::ViewValBranching (argument \a ViewSel).
+ *
+ * All view selection classes require 
+ * \code #include "gecode/set/branch.hh" \endcode
+ * \ingroup Other
+ */
+
+/**
+ * \defgroup FuncSetSelVal Set value selection for branching
+ *
+ * Contains a description of value selection strategies on set
+ * views that can be used together with the generic view/value
+ * branching class Gecode::ViewValBranching (argument \a ValSel).
+ *
+ * All value selection classes require 
+ * \code #include "gecode/set/branch.hh" \endcode
+ * \ingroup Other
+ */
+
+/**
+ * \defgroup Example Example scripts (models)
+ *
+ * All scripts are compiled into simple standalone programs. These
+ * programs understand the following options given on the 
+ * commandline:
+ *  - <code>-mode (solution, time, stat)</code>
+ *    - <code>solution</code>: print solutions.
+ *    - <code>time</code>: measure time.
+ *    - <code>stat</code>: print statistics.
+ *  - <code>-naive</code>, <code>-smart</code>: if there is a naive and
+ *    a smart model of the problem, select which to use
+ *  - <code>-solutions</code>: give the maximum number of solutions after which
+ *    the search stops. 0 means all solutions.
+ *  - <code>-icl (def, val, bnd, dom)</code>: give the consistency level of
+ *    integer constraints such as <code>distinct</code>.
+ *  - <code>-c_d</code>, <code>-a_c</code>: copying and adaptive recomputation
+ *    distance to be used by the search engine.
+ *  - <code>-samples</code>, <code>-iterations</code>: how many samples and
+ *    iterations per sample to compute in time mode.
+ *  - <code>-help</code>: print usage information and default values for
+ *    all options.
+ *
+ * Many scripts can be given the problem size as an extra argument.
+ */
+
+/*
+ * Collect some definitions for which no reasonable place exists
+ *
+ */
+
+/**
+ * \namespace Gecode::Support 
+ * \brief %Support algorithms and datastructures
+ */
+
+/**
+ * \mainpage Gecode Reference Documentation
+ *
+ * This document provides reference information about
+ * <A HREF="http://www.gecode.org">%Gecode</A>.
+ * The documentation is structured into three major groups: 
+ * common programming tasks, common functionality, and other 
+ * available functionality.
+ *
+ * This document corresponds to %Gecode version @VERSION@.
+ *
+ * \section SecByTask Programming tasks
+ *
+ * Documentation is available for the following tasks:
+ *  - \ref TaskInt
+ *  - \ref TaskMiniModel
+ *  - \ref TaskSearch
+ *  - \ref TaskActor "Programming propagators and branchings"
+ *  - \ref TaskVar
+ *
+ * \section SecByFunc Common functionality
+ *
+ * The most important functionality is:
+ *  - \ref FuncMem
+ *  - \ref FuncThrow
+ *
+ * The complete functionality can be found \ref Func "here".
+ *
+ * \section SecByOther Other available functionality
+ *
+ * The part \ref Other documents existing propagators, variable 
+ * implementations, and so on which serves as documentation of examples.
+ *
+ * \section SecStart Getting started
+ *
+ * For your first steps with %Gecode, the following pages may be of interest:
+ *  - \ref PageNotation
+ *  - \ref PageGlossary
+ *  - \ref PageComp
+ *  - \ref PageUsage
+ *
+ * \section SecMore More content
+ *
+ * Additionally, the documentation also features the following parts:
+ *  - \ref PageLic
+ *  - \ref PageChange
+ *
+ * \section SecIndex List and index content
+ *
+ * The following lists and indices are available
+ *  - \ref PageCodeStat
+ *  - <a class="el" href="modules.html">List of all modules</a> 
+ *  - <a class="el" href="annotated.html">List of all classes including brief documentation</a>
+ *  - <a class="el" href="namespaces.html">List of all namespaces including brief documentation</a>
+ *  - <a class="el" href="files.html">List of all files</a>
+ *  - <a class="el" href="hierarchy.html">Class hierarchy</a>
+ *  - <a class="el" href="classes.html">Alphabetical class index</a>
+ *  - <a class="el" href="namespacemembers.html">Namespace members</a>
+ *  - <a class="el" href="functions.html">Class members</a>
+ *  - <a class="el" href="globals.html">File members</a>
+ */
+
+/**
+ * \page PageNotation Notational conventions
+ *
+ * Throughout this reference documentation we use some notational conventions
+ * designed to keep the documentation concise yet understandable. Please
+ * read the following carefully.
+ *
+ * \section NotationArray Array notation
+ *
+ * We allow ourselves to refer to the \f$i\f$-th element of an array \f$x\f$ 
+ * by \f$x_i\f$. The size of an array \f$x\f$ (either provided by a member 
+ * function \c %size() or clear from context) is denoted \f$|x|\f$.
+ *
+ * \section NotationHome The home space
+ *
+ * Many functions and member functions take an argument \a home of 
+ * type \c Space*. The home space serves as manager to many
+ * operations used by variables, views, propagators, spaces, and so
+ * on. It provides
+ * services such as failure management, propagation control, 
+ * memory management, and so on. To keep the documentation concise
+ * the home space is not documented for functions
+ * and member functions.
+ *
+ * \section NotationShare Sharing in update and copy
+ *
+ * In member functions that either copy or update an object during
+ * cloning, an argument \a share of type \c bool is available. This
+ * Boolean value controls whether during cloning the data structure at
+ * hand will be shared among the newly created cloned space and the original
+ * or whether two independent copies are created. Some functions (such
+ * as \c copy for spaces (Gecode::Space) or \c copy for propagators
+ * (Gecode::Propagator) also feature this argument. Here it is used
+ * to pass on the Boolean value to other datastructures used inside spaces
+ * or propagators.
+ *
+ * The actual value the \a share argument has is defined by the search
+ * engine: when a search engine uses the \a clone member function of
+ * a space it decides whether sharing is to be used in the cloning of
+ * the space or not. If the search engine is single-threaded, it will
+ * use full sharing (\a share will be true). Only if the search engine
+ * uses concurrency or parallelism with more than a single thread,
+ * it will pass false as value. This means that by not sharing data structures
+ * among spaces which are to be used in different threads, all parts of
+ * %Gecode but the actual search engine do not need to provide concurrency
+ * control.
+ *
+ * As examples for data structures which are sensitive to sharing, consider
+ * Gecode::Support::SharedArray, Gecode::IntSet, and Gecode::DFA.
+ */
+
+/**
+  \page PageGlossary Brief glossary
+
+This page gives brief explanations about some of the most
+frequently occurring terms (currently limited to important
+entities manifest in the implementation) used in the %Gecode
+reference documentation.
+
+\section GlossaryActor Actor
+
+An actor is either a branching (\ref GlossaryBranching) or a
+propagator (\ref GlossaryPropagator). Actors provide the
+functionality that is common for propagators and branchings such
+as member functions for copying during cloning, memory
+allocation, and so on. Actors are implemented by the class
+Gecode::Actor. More on programming actors can be found in the
+module \ref TaskActor.
+
+\section GlossaryBranching Branching
+
+A branching defines the shape of the search tree. Branchings are
+also known as labelings or distributors, and a branching creates
+a series of choice points. Branchings are implemented by the
+class Gecode::Branching. A common abstraction for defining
+branchings based on view and value selection is provided by the
+class Gecode::ViewValBranching.
+
+\section GlossaryBranchingDesc Branching description
+
+A branching description speeds up recomputation by providing
+batch recomputation. It is created by a branching (\ref
+GlossaryBranching) and allows to replay the effect of that
+branching without the need to first perform constraint
+propagation. The base-class for branching descriptions is
+Gecode::BranchingDesc. An example for a branching description
+that works together with branchings based on view and value
+selection is Gecode::PosValDesc.
+
+\section GlossarySpace Computation space
+
+A computation space (space for short) comprises all entities for
+a constraint problem to be solved, including all actors (\ref
+GlossaryActor) and variables (\ref GlossaryVariable). A space can
+be seen as corresponding to a node in the search tree. It
+organizes constraint propagation, the branching process,
+exploration, and memory management. Spaces are implemented by the
+class Gecode::Space. They provide functionality for \ref
+TaskIntScript, \ref TaskSearch, and \ref FuncMemSpace.
+
+\section GlossaryME Modification event
+
+A modification event describes how a view (\ref GlossaryView) or
+variable implementation (\ref GlossaryVarImp) is changed by an
+update operation performed on the view or variable. Each variable
+domain defines its own modification events (see \ref
+TaskActorIntMEPC and \ref TaskActorSetMEPC). However modification
+events that describe generic events such as failure, no
+modification, or assignment to a single value are predefined (see
+\ref TaskVarMEPC).
+
+\section GlossaryPropCond Propagation condition
+
+A propagation condition defines when a propagator requires to be
+re-executed. Re-execution is controlled by the modification events
+that occur on the variables the propagator depends on (see \ref
+GlossaryPropagator). Propagation conditions and the relation
+between propagation conditions and modification events depends on
+the variable domain (see \ref TaskActorIntMEPC and \ref
+TaskActorSetMEPC). However, the propagation conditions that
+states re-execution when a variable becomes assigned is generic
+(see \ref TaskVarMEPC).
+
+\section GlossaryPropagator Propagator
+
+A propagator implements a constraint (actually, a constraint can
+be implemented by a collection of propagators). Execution by a
+propagator is defined by its dependencies: the views (referring to
+some variables) together with their propagation conditions. A
+propagator is implemented by inheriting from the class
+Gecode::Propagator. Common abstractions for propagators are also
+available (see \ref TaskPropPat, \ref TaskPropRePat, and \ref
+TaskPropSetPat).
+
+\section GlossaryPME Propagator modification event
+
+A propagator maintains as propagator modification event for each
+variable domain a modification event. These modification events
+describe which modification events occurred on all views
+(variables) the propagator depends on (see \ref
+GlossaryPropagator). A propagator modification event is available
+through a view or variable implementation (see for example \ref
+TaskActorIntView or \ref TaskActorSetView).
+
+\section GlossaryVariable Variable
+
+A variable is used for modeling problems, be it for direct
+modeling or for modeling through some interface. A variable
+provides only those operations useful for modeling and excludes
+in particular operations that can modify the variable domain
+directly. A variable is implemented by a variable implementation
+(see below).
+
+\section GlossaryVarImp Variable implementation
+
+A variable implementation is implemented by inheriting from
+Gecode::Variable. It implements the variable domain and provides
+operations to access and modify the domain. Examples of variable
+implementations are Gecode::Int::IntVarImp and
+Gecode::Set::SetVarImp.
+
+\section GlossaryView View
+
+A view offers essentially the same interface as a variable
+implementation and allows both domain access and
+modification. Typically, several views exist for the same
+variable implementation to obtain several constraints from the
+same propagator. Examples of views are \ref TaskActorIntView and
+\ref TaskActorSetView.
+
+*/
+ 
+/**
+ * \page PageUsage Using Gecode
+ *
+ * \section SecUsageInclude Including header files
+ *
+ * Deciding which header files must be included when using %Gecode is
+ * quite straightforward. There are the following header files for inclusion:
+ *  - gecode/kernel.hh must always be included (the header files below
+ *    also always include kernel.hh).
+ *  - gecode/search.hh must be included, if search engines are used 
+ *    (see for example \ref TaskIntSearch).
+ *  - gecode/int.hh must be included, if any integer functionality is used
+ *    (see for example \ref TaskIntInt and \ref TaskActorInt).
+ *  - gecode/set.hh must be included, if any finite set functionality is used
+ *    (see for example \ref TaskIntSet and \ref TaskActorSet).
+ *  - gecode/minimodel.hh must be included, if direct modelling support
+ *    is used (see for example \ref TaskMiniModel).
+ *
+ * Other functionality is available through a set of header files. For example
+ * to access the implementation of particular propagators, a particular header
+ * file must be included. The header file to be included is always mentioned
+ * in the documentation of the class or function.
+ *
+ * \section SecUsageLink Linking libraries
+ *
+ * Setting the exact name for a library on a particular platform aside,
+ * inclusion of header files basically coincides with against which
+ * library must be linked. That is:
+ *  - If gecode/kernel.hh is included, linking against the kernel library is
+ *    required.
+ *  - If gecode/search.hh is included, linking against the search library is
+ *    required.
+ *  - If gecode/int.hh is included, linking against the integer library is
+ *    required.
+ *  - If gecode/set.hh is included, linking against the set library is
+ *    required.
+ *  - If gecode/minimodel.hh is included, linking against the minimodel
+ *    library is required.
+ *
+ * The functionality in \ref FuncSupport and \ref FuncIter require no
+ * library for linking. Reusing integer or set propagators of course
+ * require the integer or set library.
+ *
+ * If there is a difference between library and DLL (such as on Windows)
+ * linking must be done against the appropriate library and the
+ * corresponding DLL must be available for execution (such as in the
+ * PATH environment variable).
+ *
+ * \section SecUsageLibraries Library names
+ *
+ * \subsection SULA Windows with Visual Studio
+ *
+ *  - Kernel library and DLL: GecodeKernel.lib and GecodeKernel.dll
+ *  - Search library and DLL: GecodeSearch.lib and GecodeSearch.dll
+ *  - Integer library and DLL: GecodeInt.lib and GecodeInt.dll
+ *  - Set library and DLL: GecodeSet.lib and GecodeSet.dll
+ *  - Minimodel library and DLL: GecodeMiniModel.lib and GecodeMiniModel.dll
+ *
+ * \subsection SULB Unix (Linux, MacOS X)
+ *
+ * Depending on whether %Gecode was compiled as a static or as a dynamic
+ * library, different filename suffixes are used on different Unix platforms.
+ * All library names follow the following scheme:
+ *
+ *  - Kernel library: libgecodekernel.<EXT>
+ *  - Search library: libgecodesearch.<EXT>
+ *  - Integer library: libgecodeint.<EXT>
+ *  - Set library: libgecodeset.<EXT>
+ *  - Minimodel library: libgecodeminimodel.<EXT>
+ *
+ * where <EXT> depends on the library type and platform:
+ *
+ *  - libgecode[...].a for static libaries on all Unix flavors
+ *  - libgecode[...].so for shared libraries on Linux
+ *  - libgecode[...].dylib for shared libraries on MacOS X
+ *
+ * You can use for example
+ * 
+ * <code>gcc -L$GPREFIX/lib -lgecodekernel</code>
+ *
+ * to link the kernel library, if the libraries are found in
+ * <code>$GPREFIX/lib</code>.
+ */
+ 
+/**
+ * \page PageComp Compiling and installing Gecode
+ *
+ * The %Gecode library, including examples and documentation, can be built
+ * on all recent versions of Windows, Linux, and MacOS X. Porting to other
+ * Unix flavors should be easy, if any change is necessary at all.
+ *
+ * \section Prerequisites
+ *
+ * In order to compile %Gecode, you need a standard Unix toolchain including
+ * the following programs:
+ *
+ *  - a bash-compatible shell
+ *  - GNU make
+ *  - sed
+ *  - cp
+ *  - tar
+ *
+ * These are available in all standard installations of Linux. On MacOS X,
+ * you need to install the Apple developer tools. For
+ * Windows, we require the
+ * <a href="http://www.cygwin.com/">Cygwin environment</a> that provides
+ * all necessary tools.
+ *
+ * We currently support
+ *   - the Microsoft Visual C++ compilers for Windows. The Microsoft
+ *     Visual C++ 2005 Express Edition is available free of charge from
+ *     <a href="http://msdn.microsoft.com/vstudio/express/visualc/">the MSDN
+ *     web pages</a>. 
+ *   - the GNU Compiler Collection (gcc) for Windows and Unix flavors such as
+ *     Linux and MacOS X. The GNU gcc is open source software and available
+ *     from <a href="http://gcc.gnu.org/">the GCC home page</a>. It is included
+ *     in all Linux distributions and the Apple MacOS X developer tools.
+ *     %Gecode requires at least version 3.4 of gcc. We recommend using version
+ *     4.0 or higher. Very unfortunately, the parser used in versions of gcc
+ *     before 3.4 is broken and hence cannot compile %Gecode.
+ *   - The Intel C++ compiler for Windows and Linux. Please note that this
+ *     compiler was only tested using the evaluation license available from
+ *     Intel. If you encounter problems or have suggestions for improvements,
+ *     please let us know.
+ *
+ * \section CompConf Configuring the sources
+ *
+ * %Gecode uses GNU autoconf to acquire information about the system it is
+ * compiled on. Typically, you need to run the <code>configure</code>
+ * script in the toplevel directory.
+ *
+ * To setup %Gecode for your particular system, you may need to add one or
+ * more of the following options to <code>configure</code>:
+ *
+ *  - When using the Microsoft Visual C++ compiler, add
+ *    <code>CC=cl CXX=cl</code> to your
+ *    invocation of <code>configure</code>
+ *  - When using the Intel C++ compiler under Windows, add
+ *    <code>CC=icl CXX=icl</code> to your
+ *    invokation of configure.
+ *  - When using the Intel C++ compiler under Linux, add
+ *    <code>CC=icc CXX=icpc</code> to your
+ *    invokation of configure.
+ *  - To install %Gecode somewhere else than the default
+ *    <code>/usr/local</code>, use the <code>--prefix=[...]</code> switch
+ *  - You can enable and disable the individual modules %Gecode consists of
+ *    using <code>--enable-[MODULE]</code> and <code>--disable-[MODULE]</code>
+ *
+ * You can get a list of all supported configuration options by calling 
+ * <code>configure</code> with the <code>--help</code> switch.
+ *
+ * \subsection CompConfExamples Example configurations
+ *
+ * To compile %Gecode on a <b>Windows machine using the Microsoft compiler</b>, use
+ *
+ * <code>./configure CC=cl CXX=cl</code>
+ *
+ * To compile only the %Gecode library <b>without examples</b> on a Unix machine, use
+ *
+ * <code>./configure --disable-examples</code>
+ *
+ * To compile on a <b>Unix machine</b> using a different than the default
+ * <code>gcc</code> compiler, and install under <code>/opt/gecode</code>, use
+ *
+ * <code>./configure --prefix=/opt/gecode CC=gcc-4.0 CXX=g++-4.0</code>
+ *
+ * To compile a <b>debug build</b> on Unix, turning on all assertions and not
+ * inlining anything, use
+ *
+ * <code>./configure --enable-debug</code>
+ *
+ * To compile on <b>Cygwin</b>, but linking against the <b>Windows libraries</b> instead
+ * of the Cygwin libraries, use
+ *
+ * <code>./configure CC="gcc -mno-cygwin" CXX="g++ -mno-cygwin"</code>
+ *
+ * To compile on a system using a different than the default compiler,
+ * and a <code>/bin/sh</code> that is not bash compatible (e.g. a
+ * <b>Solaris machine</b>), use
+ *
+ * <code>./configure --with-host-os=linux \ </code><br>
+ * <code>&nbsp;&nbsp;&nbsp;CC="gcc-4.0" CXX="g++-4.0" \ </code><br>
+ * <code>&nbsp;&nbsp;&nbsp;SHELL="/bin/bash"</code><br>
+ * <code>make SHELL="/bin/bash"</code>
+ *
+ * You can compile as <b>"universal binary" on a Mac OS
+ * machine</b>. Configure with
+ *
+ * <code>./configure --enable-universal</code>
+ *
+ * For building universal binaries on a PowerPC machine, you have to supply
+ * the path to the universal SDK (which is the default on Intel based Macs):
+ * 
+ * <code>./configure --enable-universal</code>
+ * <code>&nbsp;&nbsp;&nbsp;--with-sdk=/Developer/SDKs/MacOSX10.4u.sdk</code>
+ *
+ * \subsection CompConfUsr Passing options for compilation
+ *
+ * Additional options for compilation can be passed to the compiler
+ * from the make commandline via the variable <code>CXXUSR</code>. For
+ * example, to pass to gcc the additional option "-mtune=i686" the following
+ * can be used:
+ *
+ * <code>make CXXUSR="-mtune=i686"</code>
+ *
+ * \subsection CompConfSepDir Compiling in a separate directory
+ *
+ * The %Gecode library can be built in a separate directory. This is useful
+ * if you do not want to clutter the source tree with all the object files
+ * and libraries.
+ *
+ * Configuring %Gecode in a separate directory is easy. Assume that the
+ * sources can be found in directory <code>$GSOURCEDIR</code>, change to
+ * the directory where you want to compile %Gecode and call
+ *
+ * <code>$GSOURCEDIR/configure [options]</code>
+ *
+ * This will generate all necessary files in the new build directory.
+ *
+ * \section CompComp Compiling the sources
+ *
+ * After successful configuration, simply invoking
+ *
+ * <code>make</code>
+ *
+ * in the toplevel %Gecode directory will compile the whole library.
+ *
+ * \section CompExamples Running the examples
+ *
+ * After compiling the examples, they can be run directly from the command
+ * line. For instance, try the %Golomb Rulers Problem:
+ *
+ * <code>./examples/golomb</code>
+ *
+ * or (when running Windows):
+ *
+ * <code>./examples/golomb.exe</code>
+ * 
+ * On some platforms, you may need to set environment variables like
+ * <code>LD_LIBRARY_PATH</code> (Linux) or <code>DYLD_LIBRARY_PATH</code>
+ * (Mac OS) to the toplevel compile directory (where the dynamic libraries
+ * are placed after compilation).
+ *
+ * For more information on example scripts see \ref Example.
+ *
+ * \section Installation Installation
+ *
+ * After a successful compilation, you can install the %Gecode library
+ * and all header files necessary for compiling against it by invoking
+ *
+ * <code>make install</code>
+ *
+ * in the build directory.
+ *
+ * \section DepMngmt Dependency management
+ *
+ * The dependencies between source files are not handled automatically. If you
+ * are using a Gecode version from our subversion repository or if you
+ * modified any of the source files, you will have to call
+ * <code>make depend</code> before compilation in order to determine the
+ * source dependencies.
+ *
+ * Dependency management is only needed for recompiling Gecode after changing
+ * something. In an unmodified version (or after a <code>make clean</code>)
+ * all files are compiled anyway.
+ *
+ * \section UnsupPlatfrms Compiling for unsupported platforms
+ *
+ * If you want to try compiling Gecode on a platform that we do not support
+ * officially, you can override the platform tests during
+ * <code>configure</code>. There are two options to specify the type of
+ * platform:
+ *
+ *  - <code>--with-host-os=[linux|darwin|windows]</code>
+ *  - <code>--with-compiler-vendor=[gnu|microsoft|intel]</code>
+ *
+ * Using the first option, you can state that your platform should behave like
+ * Linux, Darwin (which is actually BSD), or Windows. This affects mainly
+ * the filenames and the tools used to generate shared and static libraries.
+ *
+ * The second option says
+ * that your compiler can be used very much like the gnu compiler
+ * <code>gcc</code>, the Microsoft compiler <code>cl</code>, or the Intel
+ * compiler <code>icl</code>. Please let us know of any successfull attempt at
+ * compiling Gecode on other platforms.
+ *
+ * \section Useful Makefile targets
+ *
+ * The main %Gecode Makefile supports the following useful targets:
+ *
+ *  - <code>all</code> compiles all parts of the library that were enabled
+ *                     during <code>configure</code>, and the examples if
+ *                     enabled
+ *  - <code>install</code> installs library, headers and examples (if enabled)
+ *                         into the <code>prefix</code> given at
+ *                         <code>configure</code>
+ *  - <code>clean</code> removes object files
+ *  - <code>veryclean</code> removes object files, libraries, and all files 
+ +                           generated during <code>make</code>
+ *  - <code>distclean</code> removes object files, libraries, and all
+ *                           generated files
+ *  - <code>depend</code> computes dependencies between source files
+ *  - <code>test</code> compiles the test suite
+ *  - <code>doc</code> generates this reference documentation using doxygen
+ *  - <code>installdoc</code> installs the documentation
+ *  - <code>distdoc</code> creates tgz and zip archives of the documentation
+ *  - <code>distzip</code> creates a binary distribution as a zip archive
+ *  - <code>disttgz</code> creates a binary distribution as a tgz archive
+ *
+ *
+ */
+