/* * 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 * * \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= \ * -DBUILD_SHARED_LIBS=TRUE \ * -DCMAKE_BUILD_WITH_INSTALL_RPATH:BOOL=OFF \ * -DCMAKE_INSTALL_RPATH:PATH=/lib/vtk- \ * -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= \ * --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= --with-vtk-version= \ * --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= \ * -DCMAKE_C_FLAGS="-fPIC" \ * .. * make * cp -f liblevmar.a /lib * cp -f levmar.h /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 within JobMarket. * 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= 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=, * --with-boost-lib=) * -# CPPUnit framework (--with-cppunit-prefix=) * -# CodePatterns (--with-codepatterns=) * * The following packages are optional (code parts/features are disabled if not * found): * -# JobMarket (--enable-jobmarket --with-jobmarket= * -# VMG library of ScaFaCoS (--enable-vmg --with-vmg-mpi MPICXX=mpicxx PKGCONFIG=) * -# levmar (--with-levmar=) * * \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 2013-04-09 */