source: src/documentation/install.dox@ a91710

/*
 * 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-prerequisites Prerequisites
 *
 * Several packages are required or advised for compilation of the code.
 * The code has been developed under ubuntu 10.04 and 12.04, so in the
 * following we concentrate on these systems.
 *
 * A specific section will be added when (cross-)compilation for Windows
 * has succeeded. Note that compiling without Qt under GNU/Cygwin is
 * relatively straight-forward along the lines of the required packages
 * for Ubuntu.
 *
 * \subsection install-prerequisites-ubuntu ... for Ubuntu
 *
 *  Under Ubuntu 12.04 the following packages are required:
 *  -# C++ compiler: e.g. g++
 *  -# LAPACK: liblapack-dev
 *  -# GSL: libgsl0-dev
 *  -# BLAS: e.g. libopenblas-dev or libatlas-base-dev
 *  -# Many Boost Libraries: libboost1.48-all-dev
 *  -# gawk: gawk
 *  -# pkg-config: pkg-config
 *  -# CodePatterns: see below for instructions
 *
 *  The following packages are optional. Note however that certain features
 *  are not available when these packages are missing:
 *  -# MoleCuilder scripting and start scripts
 *    -# Python:  python, python-dev
 *  -# Documentation generated from source code:
 *    -# doxygen: doxygen
 *    -# GraphViz: dot
 *  -# Unit tests
 *    -# CppUnit: libcppunit-dev
 *  -# Graphical User Interface
 *    -# Qt: qt4-dev-tools libqt4-core qt4-qmake
 *    -# Qt3D: see below for instructions
 *  -# BOSSANOVA scheme
 *    -# JobMarket: see below for instructions
 *    -# MPQC: see below for instructions
 *    -# ScaFaCoS: see below for instructions
 *    -# VTK: see below for instructions
 *    -# levmar: see below for instructions
 *
 *  If you are programming with or for MoleCuilder, the following packages are
 *  advised to use:
 *  -# ccache: ccache
 *  -# git: git
 *  -# autotools: autoconf automake autoheader autoconf libtool
 *
 *      Under Ubuntu 14.04 the required packages remain the same but the following
 *  notes apply:
 *  -# boost must be at least 1.50 as there is some bug with recognizing
 *     pthreads with the new gcc version.
 *  -# no need to compile VTK on your own, just use the VTK-5.8 that comes with
 *     this Ubuntu version.
 *  -# note that prior to 1.4.7 Ubuntu 14.04 is not supported and requires some
 *     changes in the automake/autoconf parts.
 * 
 * \subsection install-prerequisites-other Other packages
 *
 *  Here, we want to give some advice on how we managed to compile packages that
 *  don't come as a Debian/Ubuntu package:
 *
 *  \subsubsection install-prerequisites-other-codepatterns CodePatterns
 *
 *   CodePatterns are some general object oriented patterns implemented in C++
 *   which are a sort of novice attempt to what some of the boost libraries can
 *   do. E.g. a thread-safe singleton pattern.
 *
 *   Refer to the project's webpage for further instructions.
 *
 *  \subsubsection install-prerequisites-other-qt3d Qt3D
 *
 *   The graphical user interface heavily relies on Qt3D to display atoms and
 *   their bonds and to allow for selections. As the GUI has been developed with
 *   Qt4.8 where Qt3D is not yet implemented - this has been done with Qt5 --
 *   Qt3D has to be compiled and installed manually. Required for compilation
 *   are the complete dev-tools of Qt4. Then, obtain the code from the repository
 *   as described here: http://doc-snapshot.qt-project.org/qt3d-1.0/qt3d-building.html
 *   Make sure that the branch \b qt4 is checked out.
 *   Afterwards, create the Makefiles (check that qt4's qmake is used!), compile, and
 *   install via
 *   \code
 *   qmake-qt4 quick3d.pro
 *   sudo make
 *   sudo make install
 *   \endcode
 *   Note that I had to manually create \b /usr/include/qt4/Qt3D to pass
 *   compilation and installation with error.
 *
 *   Furthermore, we require a Qt3D pkg-config file, which is sadly not created.
 *   This can be easily created by copying e.g. QtOpenGl.pc and search&replacing
 *   OpenGl to Qt3D (check for double QtQt appearances).
 *
 *  \subsubsection install-prerequisites-other-jobmarket JobMarket
 *
 *   JobMarket is a package for allowing a server to give wrapped-up jobs to
 *   clients which work on the given job and return some wrapped-up results.
 *   This has been implemented with boost::asio.
 *
 *   The package is private property of Frederik Heber. Contact the author for
 *   further information on how to obtain the code and installation instructions.
 *
 *  \subsubsection install-prerequisites-other-scafacos ScaFaCoS
 *
 *  ScaFaCoS (http://www.scafacos.org/) is a library of fast Coulomb solvers,
 *  created by the same-named BMBF funded project. The library contains Versatile
 *  MultiGrid (vmg) as one of its solvers which is used in the BOSSANOVA scheme
 *  for the calculation of long-range forces.
 *
 *  ScaFaCoS requires the following packages to compile:
 *  -# MPI: mpi-default-dev libopenmpi-dev
 *  -# F2C: libf2c2-dev
 *  -# Fortran compiler: gfortan
 *  -# VTK >=5.10
 *
 *  Firstly, you should obtain a recent copy of the visualization tool kit (VTK)
 *  (http://www.vtk.org/) and compile as
 *  \code
 *  export MPI_HOME=$( which mpirun | sed 's#/bin/mpirun##g')
 *  export CXX_FLAGS=-fPIC
 *  cmake -DCMAKE_INSTALL_PREFIX:PATH=<install-path> \
 *        -DBUILD_SHARED_LIBS=TRUE \
 *        -DCMAKE_BUILD_WITH_INSTALL_RPATH:BOOL=OFF \
 *        -DCMAKE_INSTALL_RPATH:PATH=<install-path>/lib/vtk-<install-version> \
 *        -DCMAKE_INSTALL_RPATH_USE_LINK_PATH:BOOL=ON \
 *        -DCMAKE_SKIP_BUILD_RPATH:BOOL=OFF \
 *        -DVTK_USE_PARALLEL:BOOL=ON \
 *        -DVTK_USE_MPI:BOOL=ON \
 *        -DMPI_LIBRARY:PATH=${MPI_HOME}/lib/libmpi.so \
 *        -DMPI_EXTRA_LIBRARY:PATH=${MPI_HOME}/lib/libmpi_cxx.so \
 *        -DMPI_INCLUDE_PATH:PATH=${MPI_HOME}/include/mpi \
 *        ..
 *  make -j4
 *  make install
 *  \endcode
 *  where we force rpath-linking and shared libraries (MPI is actually not
 *  required here).
 *
 *  Compilation additionally required use of
 *  \code CPPFLAGS="-fPIC" \endcode
 *  to generate position-independent code. This is because ScaFaCoS so far does
 *  not use libtool which would otherwise take care of this and created shared
 *  libraries. Note that VMG is the only required solver, others are not used, e.g.
 *  for a debug compile you might want to use:
 *  \code
 *  ../configure \
 *    -C \
 *    --prefix=<path> \
 *    --enable-shared \
 *    BSPLINE_DEG=3 \
 *    MPICC=mpicc.openmpi \
 *    MPICXX=mpicxx.openmpi \
 *    MPIEXEC=mpirun.openmpi \
 *    CPPFLAGS="-Wall -g3 -O0 -ggdb -fPIC" \
 *    --enable-mpi \
 *    --with-boost-libdir=/usr/lib --with-boost=/usr \
 *    --with-vtk=<path-to-vtk> --with-vtk-version=<vtk-version path string, i.e. -5.10> \
 *    --enable-fcs-solvers=vmg
 *  \endcode
 *  where we specify a recent boost and the installed VTK version from above.
 *
 *  \subsubsection install-prerequisites-other-levmar LevMar
 *
 *   We also require the levmar (http://www.ics.forth.gr/~lourakis/levmar/) which
 *   implements a Levenberg-Marquardt for non-linear regression which is employed
 *   for fitting empirical potentials to energies obtained from calculated
 *   fragment energies.
 *
 *   Compile and install as follows
 *   \code
 *    cmake \
 *      -DCMAKE_INSTALL_PREFIX:PATH=<install-path> \
 *      -DCMAKE_C_FLAGS="-fPIC" \
 *      ..
 *    make
 *    cp -f liblevmar.a <install-path>/lib
 *    cp -f levmar.h <install-path>/include
 *   \endcode
 *   where we have to copy the stuff by hand as no \a install target exists.
 *
 *  \subsubsection install-prerequisites-other-mpqc MPQC
 *
 *  Massively Parallel Quantum Chemistry (http://www.mpqc.org/) is a Hartree-Fock
 *  solver with emphasis on concurrency. We, however, require only the solver part.
 *  The code base has been adapted a bit to allow use as a JobMarket-compatible
 *  client. Also, it uses the ScaFaCoS package to calculate long-range forces.
 *
 * \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 meet all the
 * requirements. Note that you may supply system-specific paths as follows:
 * -# 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>,
 * --with-boost-lib=<path>)
 * -# CPPUnit framework (--with-cppunit-prefix=<dir>)
 * -# CodePatterns (--with-codepatterns=<dir>)
 *
 * The following packages are optional (code parts/features are disabled if not
 * found):
 * -# JobMarket (--enable-jobmarket --with-jobmarket=<dir>
 * -# VMG library of ScaFaCoS (--enable-vmg --with-vmg-mpi MPICXX=mpicxx PKGCONFIG=<path to ScaFaCoS pkdir>)
 * -# levmar (--with-levmar=<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)
 * - \a --enable-python - activates python scripting. For one you can control
 *  molecuilder within your python code by simply calling its actions. For another
 *  it automatically executes a script \b molecuilder.py in the current folder
 *  prior to launching the respective UI.
 *  - \a --disable-cache - disables caching of certain variables (see CodePatterns).
 *  - \a --enable-valgrind - each test of the testsuite is launched by wrapping
 *  the call through valgrind checking on correct handling of memory.
 *
 *
 * \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
 *
 * \subsection install-difficulties  Difficulties
 *
 *  You might encounter some problems along the way, which we list up here:
 *  -# Switching from Lucid Lynx to Precise Pangolin, libtool has been patched to
 *  \b link_all_deplibs=no which causes linking to fail. A temporary way around it
 *  is to seek&replace all instances in your build directory (replace no with
 *  unknown). The more general way is to replace packaged and patched libtool
 *  with an unpatched version you have to compile yourself.
 *
 * \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 distcheck: Checks whether the code compiles and all tests runs without
 *  from a distributed archive. This is checked for each release version.
 *
 * \date 2014-08-21
 */