/*
 * Project: MoleCuilder
 * Description: creates and alters molecular systems
 * Copyright (C)  2010 University of Bonn. All rights reserved.
 * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
 */

/**
 * \file install.dox
 *
 * Created on: Oct 28, 2011
 *    Author: heber
 */

/**
 *  \page install Installation
 *
 * \section install-compiling Compiling the Code
 *
 * After you obtained the code, you do the following:
 *
 * \code
 * ./bootstrap
 * \endcode
 *
 * This creates the necessary autoconf and automake files.
 *
 * After this,
 *
 * \code
 * mkdir build
 * cd build
 * ../configure --prefix=`pwd`
 * \endcode
 *
 * which will run the configure script that checks whether you have a current
 * version of the following required packages
 *
 * -# GNU Scientific Library (specify via LDFLAGS, ...)
 * -# Qt4 framework (--with-Qt=<dir> or --with-Qt-include-dir, --with-Qt-bin-dir,
 *  --with-Qt-lib-dir and --with-Qt-lib)
 * -# Boost library 1.40 or newer with program_options and threads (--with-boost=<dir>)
 * -# CPPUnit framework (--with-cppunit-prefix=<dir>)
 * -# CodePatterns (--with-codepatterns=<dir>)
 *
 * \a --prefix is the argument to tell configure where all program code should go
 * to (pwd is the unix command for the current working directory). There are
 * others, see
 *
 * \code
 * ../configure --help
 * \endcode
 *
 * and some enable/disable switches you should check out:
 *
 * - \a --enable-ecut - says that the TestRunner, comprising all unit tests in one
 *  exectuable, shall make use of the Eclipse CppUnitTest (ECUT). If this is
 *  started within eclipse with this plugin installed, a shiny interface will tell
 *  you what failed and what not.
 * - \a --enable-debug - activates many internal asserts, memory debugger and more
 *  (makes code a lot slower but gives information in case something fails)
 *
 * \note A note about configure: If one library is found only under some specific path, you
 * can add CFLAGS, CPPFLAGS, LDFLAGS, ... to the configure call, like this
 * \code
 * ../configure --prefix=`pwd` --enable-hydrogen CFLAGS="-Wall -g3" CXXFLAGS="-Wall -g3"
 * \endcode
 * which enables all compiler warnings and full debugging of the code without any
 * optimization. configure saves these variables, too, such that when it is called
 * to re-configure it will still make use of them from its cache file.
 *
 * There are several flags that change the way molecuilder is compiled and probably
 * make it run faster, more unsafe, ...
 * -# \a -DLOG_OBSERVER,  What the Observers do is logged, the log is printed on exit
 * -# \a -DNO_MEMDEBUG,   MemDebug (memory debugger) is disabled
 * -# \a -DNO_CACHING,  Cachable are short-wired, i.e. always recalculate, this slows
 *  down the code a lot
 * -# \a -DNDEBUG,  include NO_MEMDEBUG, also ASSERTs are not checked, this speeds up
 *  the code by a factor of 5
 *
 * \section install-install Installing
 *
 * Now, we are ready to compile and install.
 *
 * \code
 * make
 * make install
 * \endcode
 *
 * \attention If you have a multi-core system, it is highly recommended to use the
 * \a -j option of make to allow for multiple threads to work on compiling or
 * checking the codfe simultaneously.
 *
 * And if everything went well, you should launch the unit tests and the testsuite
 * by (see section \ref tests on how to launch the tests individually)
 *
 * \code
 * make check
 * \endcode
 *
 * If everything is OK, you have a working version of MoleCuilder in form of the
 * executables \b bin/molecuilder and \b bin/molecuildergui.
 *
 * If you have to delete all compiled stuff, enter
 *
 * \code
 * make clean
 * \endcode
 *
 * or
 *
 * \code
 * make distclean
 * \endcode
 *
 * which will also delete all autoconf stuff for configure.
 *
 * distclean is at times necessary when stuff does not compile and there's
 * seemingly no logic behind it, i.e. especially when paths of modules have
 * changed. To recover your configure options, either look at \b config.log in
 * the build directory or enter
 *
 * \code
 * ./config.status --version
 * \endcode
 *
 *  Further useful commands are
 *  -# make clean uninstall: deletes .o-files and removes executable from the given
 *    binary directory
 *  -# make doc: Creates these html pages out of the documented source
 *  -# make check: Runs an extensive set of unit tests and a testsuite which also gives
 *    a good overview on the set of functions.
 *
 * \date 2011-10-31
 */