| 1 | /*
|
|---|
| 2 | * Project: MoleCuilder
|
|---|
| 3 | * Description: creates and alters molecular systems
|
|---|
| 4 | * Copyright (C) 2010 University of Bonn. All rights reserved.
|
|---|
| 5 | * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
|
|---|
| 6 | */
|
|---|
| 7 |
|
|---|
| 8 | /**
|
|---|
| 9 | * \file install.dox
|
|---|
| 10 | *
|
|---|
| 11 | * Created on: Oct 28, 2011
|
|---|
| 12 | * Author: heber
|
|---|
| 13 | */
|
|---|
| 14 |
|
|---|
| 15 | /**
|
|---|
| 16 | * \page install Installation
|
|---|
| 17 | *
|
|---|
| 18 | * \section install-prerequisites Prerequisites
|
|---|
| 19 | *
|
|---|
| 20 | * Several packages are required or advised for compilation of the code.
|
|---|
| 21 | * The code has been developed under ubuntu 10.04 and 12.04, so in the
|
|---|
| 22 | * following we concentrate on these systems.
|
|---|
| 23 | *
|
|---|
| 24 | * A specific section will be added when (cross-)compilation for Windows
|
|---|
| 25 | * has succeeded. Note that compiling without Qt under GNU/Cygwin is
|
|---|
| 26 | * relatively straight-forward along the lines of the required packages
|
|---|
| 27 | * for Ubuntu.
|
|---|
| 28 | *
|
|---|
| 29 | * \subsection install-prerequisites-ubuntu ... for Ubuntu
|
|---|
| 30 | *
|
|---|
| 31 | * Under Ubuntu 12.04 the following packages are required:
|
|---|
| 32 | * -# C++ compiler: e.g. g++
|
|---|
| 33 | * -# LAPACK: liblapack-dev
|
|---|
| 34 | * -# GSL: libgsl0-dev
|
|---|
| 35 | * -# BLAS: e.g. libopenblas-dev or libatlas-base-dev
|
|---|
| 36 | * -# Many Boost Libraries: libboost1.48-all-dev
|
|---|
| 37 | * -# gawk: gawk
|
|---|
| 38 | * -# pkg-config: pkg-config
|
|---|
| 39 | * -# CodePatterns: see below for instructions
|
|---|
| 40 | *
|
|---|
| 41 | * The following packages are optional. Note however that certain features
|
|---|
| 42 | * are not available when these packages are missing:
|
|---|
| 43 | * -# MoleCuilder scripting and start scripts
|
|---|
| 44 | * -# Python: python, python-dev
|
|---|
| 45 | * -# Documentation generated from source code:
|
|---|
| 46 | * -# doxygen: doxygen
|
|---|
| 47 | * -# GraphViz: dot
|
|---|
| 48 | * -# Unit tests
|
|---|
| 49 | * -# CppUnit: libcppunit-dev
|
|---|
| 50 | * -# Graphical User Interface
|
|---|
| 51 | * -# Qt: qt4-dev-tools libqt4-core qt4-qmake
|
|---|
| 52 | * -# Qt3D: see below for instructions
|
|---|
| 53 | * -# BOSSANOVA scheme
|
|---|
| 54 | * -# JobMarket: see below for instructions
|
|---|
| 55 | * -# MPQC: see below for instructions
|
|---|
| 56 | * -# ScaFaCoS: see below for instructions
|
|---|
| 57 | * -# VTK: see below for instructions
|
|---|
| 58 | * -# levmar: see below for instructions
|
|---|
| 59 | *
|
|---|
| 60 | * If you are programming with or for MoleCuilder, the following packages are
|
|---|
| 61 | * advised to use:
|
|---|
| 62 | * -# ccache: ccache
|
|---|
| 63 | * -# git: git
|
|---|
| 64 | * -# autotools: autoconf automake autoheader autoconf libtool
|
|---|
| 65 | *
|
|---|
| 66 | * Under Ubuntu 14.04 the required packages remain the same but the following
|
|---|
| 67 | * notes apply:
|
|---|
| 68 | * -# boost must be at least 1.50 as there is some bug with recognizing
|
|---|
| 69 | * pthreads with the new gcc version.
|
|---|
| 70 | * -# no need to compile VTK on your own, just use the VTK-5.8 that comes with
|
|---|
| 71 | * this Ubuntu version.
|
|---|
| 72 | * -# note that prior to 1.4.7 Ubuntu 14.04 is not supported and requires some
|
|---|
| 73 | * changes in the automake/autoconf parts.
|
|---|
| 74 | *
|
|---|
| 75 | * \subsection install-prerequisites-other Other packages
|
|---|
| 76 | *
|
|---|
| 77 | * Here, we want to give some advice on how we managed to compile packages that
|
|---|
| 78 | * don't come as a Debian/Ubuntu package:
|
|---|
| 79 | *
|
|---|
| 80 | * \subsubsection install-prerequisites-other-codepatterns CodePatterns
|
|---|
| 81 | *
|
|---|
| 82 | * CodePatterns are some general object oriented patterns implemented in C++
|
|---|
| 83 | * which are a sort of novice attempt to what some of the boost libraries can
|
|---|
| 84 | * do. E.g. a thread-safe singleton pattern.
|
|---|
| 85 | *
|
|---|
| 86 | * Refer to the project's webpage for further instructions.
|
|---|
| 87 | *
|
|---|
| 88 | * \subsubsection install-prerequisites-other-qt3d Qt3D
|
|---|
| 89 | *
|
|---|
| 90 | * The graphical user interface heavily relies on Qt3D to display atoms and
|
|---|
| 91 | * their bonds and to allow for selections. As the GUI has been developed with
|
|---|
| 92 | * Qt4.8 where Qt3D is not yet implemented - this has been done with Qt5 --
|
|---|
| 93 | * Qt3D has to be compiled and installed manually. Required for compilation
|
|---|
| 94 | * are the complete dev-tools of Qt4. Then, obtain the code from the repository
|
|---|
| 95 | * as described here: http://doc-snapshot.qt-project.org/qt3d-1.0/qt3d-building.html
|
|---|
| 96 | * Make sure that the branch \b qt4 is checked out.
|
|---|
| 97 | * Afterwards, create the Makefiles (check that qt4's qmake is used!), compile, and
|
|---|
| 98 | * install via
|
|---|
| 99 | * \code
|
|---|
| 100 | * qmake-qt4 quick3d.pro
|
|---|
| 101 | * sudo make
|
|---|
| 102 | * sudo make install
|
|---|
| 103 | * \endcode
|
|---|
| 104 | * Note that I had to manually create \b /usr/include/qt4/Qt3D to pass
|
|---|
| 105 | * compilation and installation with error.
|
|---|
| 106 | *
|
|---|
| 107 | * Furthermore, we require a Qt3D pkg-config file, which is sadly not created.
|
|---|
| 108 | * This can be easily created by copying e.g. QtOpenGl.pc and search&replacing
|
|---|
| 109 | * OpenGl to Qt3D (check for double QtQt appearances).
|
|---|
| 110 | *
|
|---|
| 111 | * \subsubsection install-prerequisites-other-jobmarket JobMarket
|
|---|
| 112 | *
|
|---|
| 113 | * JobMarket is a package for allowing a server to give wrapped-up jobs to
|
|---|
| 114 | * clients which work on the given job and return some wrapped-up results.
|
|---|
| 115 | * This has been implemented with boost::asio.
|
|---|
| 116 | *
|
|---|
| 117 | * The package is private property of Frederik Heber. Contact the author for
|
|---|
| 118 | * further information on how to obtain the code and installation instructions.
|
|---|
| 119 | *
|
|---|
| 120 | * \subsubsection install-prerequisites-other-scafacos ScaFaCoS
|
|---|
| 121 | *
|
|---|
| 122 | * ScaFaCoS (http://www.scafacos.org/) is a library of fast Coulomb solvers,
|
|---|
| 123 | * created by the same-named BMBF funded project. The library contains Versatile
|
|---|
| 124 | * MultiGrid (vmg) as one of its solvers which is used in the BOSSANOVA scheme
|
|---|
| 125 | * for the calculation of long-range forces.
|
|---|
| 126 | *
|
|---|
| 127 | * ScaFaCoS requires the following packages to compile:
|
|---|
| 128 | * -# MPI: mpi-default-dev libopenmpi-dev
|
|---|
| 129 | * -# F2C: libf2c2-dev
|
|---|
| 130 | * -# Fortran compiler: gfortan
|
|---|
| 131 | * -# VTK >=5.10
|
|---|
| 132 | *
|
|---|
| 133 | * Firstly, you should obtain a recent copy of the visualization tool kit (VTK)
|
|---|
| 134 | * (http://www.vtk.org/) and compile as
|
|---|
| 135 | * \code
|
|---|
| 136 | * export MPI_HOME=$( which mpirun | sed 's#/bin/mpirun##g')
|
|---|
| 137 | * export CXX_FLAGS=-fPIC
|
|---|
| 138 | * cmake -DCMAKE_INSTALL_PREFIX:PATH=<install-path> \
|
|---|
| 139 | * -DBUILD_SHARED_LIBS=TRUE \
|
|---|
| 140 | * -DCMAKE_BUILD_WITH_INSTALL_RPATH:BOOL=OFF \
|
|---|
| 141 | * -DCMAKE_INSTALL_RPATH:PATH=<install-path>/lib/vtk-<install-version> \
|
|---|
| 142 | * -DCMAKE_INSTALL_RPATH_USE_LINK_PATH:BOOL=ON \
|
|---|
| 143 | * -DCMAKE_SKIP_BUILD_RPATH:BOOL=OFF \
|
|---|
| 144 | * -DVTK_USE_PARALLEL:BOOL=ON \
|
|---|
| 145 | * -DVTK_USE_MPI:BOOL=ON \
|
|---|
| 146 | * -DMPI_LIBRARY:PATH=${MPI_HOME}/lib/libmpi.so \
|
|---|
| 147 | * -DMPI_EXTRA_LIBRARY:PATH=${MPI_HOME}/lib/libmpi_cxx.so \
|
|---|
| 148 | * -DMPI_INCLUDE_PATH:PATH=${MPI_HOME}/include/mpi \
|
|---|
| 149 | * ..
|
|---|
| 150 | * make -j4
|
|---|
| 151 | * make install
|
|---|
| 152 | * \endcode
|
|---|
| 153 | * where we force rpath-linking and shared libraries (MPI is actually not
|
|---|
| 154 | * required here).
|
|---|
| 155 | *
|
|---|
| 156 | * Compilation additionally required use of
|
|---|
| 157 | * \code CPPFLAGS="-fPIC" \endcode
|
|---|
| 158 | * to generate position-independent code. This is because ScaFaCoS so far does
|
|---|
| 159 | * not use libtool which would otherwise take care of this and created shared
|
|---|
| 160 | * libraries. Note that VMG is the only required solver, others are not used, e.g.
|
|---|
| 161 | * for a debug compile you might want to use:
|
|---|
| 162 | * \code
|
|---|
| 163 | * ../configure \
|
|---|
| 164 | * -C \
|
|---|
| 165 | * --prefix=<path> \
|
|---|
| 166 | * --enable-shared \
|
|---|
| 167 | * BSPLINE_DEG=3 \
|
|---|
| 168 | * MPICC=mpicc.openmpi \
|
|---|
| 169 | * MPICXX=mpicxx.openmpi \
|
|---|
| 170 | * MPIEXEC=mpirun.openmpi \
|
|---|
| 171 | * CPPFLAGS="-Wall -g3 -O0 -ggdb -fPIC" \
|
|---|
| 172 | * --enable-mpi \
|
|---|
| 173 | * --with-boost-libdir=/usr/lib --with-boost=/usr \
|
|---|
| 174 | * --with-vtk=<path-to-vtk> --with-vtk-version=<vtk-version path string, i.e. -5.10> \
|
|---|
| 175 | * --enable-fcs-solvers=vmg
|
|---|
| 176 | * \endcode
|
|---|
| 177 | * where we specify a recent boost and the installed VTK version from above.
|
|---|
| 178 | *
|
|---|
| 179 | * \subsubsection install-prerequisites-other-levmar LevMar
|
|---|
| 180 | *
|
|---|
| 181 | * We also require the levmar (http://www.ics.forth.gr/~lourakis/levmar/) which
|
|---|
| 182 | * implements a Levenberg-Marquardt for non-linear regression which is employed
|
|---|
| 183 | * for fitting empirical potentials to energies obtained from calculated
|
|---|
| 184 | * fragment energies.
|
|---|
| 185 | *
|
|---|
| 186 | * Compile and install as follows
|
|---|
| 187 | * \code
|
|---|
| 188 | * cmake \
|
|---|
| 189 | * -DCMAKE_INSTALL_PREFIX:PATH=<install-path> \
|
|---|
| 190 | * -DCMAKE_C_FLAGS="-fPIC" \
|
|---|
| 191 | * ..
|
|---|
| 192 | * make
|
|---|
| 193 | * cp -f liblevmar.a <install-path>/lib
|
|---|
| 194 | * cp -f levmar.h <install-path>/include
|
|---|
| 195 | * \endcode
|
|---|
| 196 | * where we have to copy the stuff by hand as no \a install target exists.
|
|---|
| 197 | *
|
|---|
| 198 | * \subsubsection install-prerequisites-other-mpqc MPQC
|
|---|
| 199 | *
|
|---|
| 200 | * Massively Parallel Quantum Chemistry (http://www.mpqc.org/) is a Hartree-Fock
|
|---|
| 201 | * solver with emphasis on concurrency. We, however, require only the solver part.
|
|---|
| 202 | * The code base has been adapted a bit to allow use as a JobMarket-compatible
|
|---|
| 203 | * client. Also, it uses the ScaFaCoS package to calculate long-range forces.
|
|---|
| 204 | *
|
|---|
| 205 | * \subsubsection install-prerequisites-other-python Python
|
|---|
| 206 | *
|
|---|
| 207 | * All required Python package are available under Ubuntu 12.04. However, you
|
|---|
| 208 | * may encounter the compilation error in connection with \b pyconfig.h.
|
|---|
| 209 | *
|
|---|
| 210 | * In this case, execute
|
|---|
| 211 | * \code
|
|---|
| 212 | * sudo updatedb
|
|---|
| 213 | * \endcode
|
|---|
| 214 | * in order to update the locate database which is used to find the file.
|
|---|
| 215 | *
|
|---|
| 216 | * \section install-compiling Compiling the Code
|
|---|
| 217 | *
|
|---|
| 218 | * After you obtained the code, you do the following:
|
|---|
| 219 | *
|
|---|
| 220 | * \code
|
|---|
| 221 | * ./bootstrap
|
|---|
| 222 | * \endcode
|
|---|
| 223 | *
|
|---|
| 224 | * This creates the necessary autoconf and automake files.
|
|---|
| 225 | *
|
|---|
| 226 | * After this,
|
|---|
| 227 | *
|
|---|
| 228 | * \code
|
|---|
| 229 | * mkdir build
|
|---|
| 230 | * cd build
|
|---|
| 231 | * ../configure --prefix=`pwd`
|
|---|
| 232 | * \endcode
|
|---|
| 233 | *
|
|---|
| 234 | * which will run the configure script that checks whether you meet all the
|
|---|
| 235 | * requirements. Note that you may supply system-specific paths as follows:
|
|---|
| 236 | * -# GNU Scientific Library (specify via LDFLAGS, ...)
|
|---|
| 237 | * -# Qt4 framework (--with-Qt=<dir> or --with-Qt-include-dir, --with-Qt-bin-dir,
|
|---|
| 238 | * --with-Qt-lib-dir and --with-Qt-lib)
|
|---|
| 239 | * -# Boost library 1.40 or newer with program_options and threads (--with-boost=<dir>,
|
|---|
| 240 | * --with-boost-lib=<path>)
|
|---|
| 241 | * -# CPPUnit framework (--with-cppunit-prefix=<dir>)
|
|---|
| 242 | * -# CodePatterns (--with-codepatterns=<dir>)
|
|---|
| 243 | *
|
|---|
| 244 | * The following packages are optional (code parts/features are disabled if not
|
|---|
| 245 | * found):
|
|---|
| 246 | * -# JobMarket (--enable-jobmarket --with-jobmarket=<dir>
|
|---|
| 247 | * -# VMG library of ScaFaCoS (--enable-vmg --with-vmg-mpi MPICXX=mpicxx PKGCONFIG=<path to ScaFaCoS pkdir>)
|
|---|
| 248 | * -# levmar (--with-levmar=<dir>)
|
|---|
| 249 | *
|
|---|
| 250 | * \a --prefix is the argument to tell configure where all program code should go
|
|---|
| 251 | * to (pwd is the unix command for the current working directory). There are
|
|---|
| 252 | * others, see
|
|---|
| 253 | *
|
|---|
| 254 | * \code
|
|---|
| 255 | * ../configure --help
|
|---|
| 256 | * \endcode
|
|---|
| 257 | *
|
|---|
| 258 | * and some enable/disable switches you should check out:
|
|---|
| 259 | *
|
|---|
| 260 | * - \a --enable-ecut - says that the TestRunner, comprising all unit tests in one
|
|---|
| 261 | * exectuable, shall make use of the Eclipse CppUnitTest (ECUT). If this is
|
|---|
| 262 | * started within eclipse with this plugin installed, a shiny interface will tell
|
|---|
| 263 | * you what failed and what not.
|
|---|
| 264 | * - \a --enable-debug - activates many internal asserts, memory debugger and more
|
|---|
| 265 | * (makes code a lot slower but gives information in case something fails)
|
|---|
| 266 | * - \a --enable-python - activates python scripting. For one you can control
|
|---|
| 267 | * molecuilder within your python code by simply calling its actions. For another
|
|---|
| 268 | * it automatically executes a script \b molecuilder.py in the current folder
|
|---|
| 269 | * prior to launching the respective UI.
|
|---|
| 270 | * - \a --disable-cache - disables caching of certain variables (see CodePatterns).
|
|---|
| 271 | * - \a --enable-valgrind - each test of the testsuite is launched by wrapping
|
|---|
| 272 | * the call through valgrind checking on correct handling of memory.
|
|---|
| 273 | *
|
|---|
| 274 | *
|
|---|
| 275 | * \note A note about configure: If one library is found only under some specific path, you
|
|---|
| 276 | * can add CFLAGS, CPPFLAGS, LDFLAGS, ... to the configure call, like this
|
|---|
| 277 | * \code
|
|---|
| 278 | * ../configure --prefix=`pwd` --enable-hydrogen CFLAGS="-Wall -g3" CXXFLAGS="-Wall -g3"
|
|---|
| 279 | * \endcode
|
|---|
| 280 | * which enables all compiler warnings and full debugging of the code without any
|
|---|
| 281 | * optimization. configure saves these variables, too, such that when it is called
|
|---|
| 282 | * to re-configure it will still make use of them from its cache file.
|
|---|
| 283 | *
|
|---|
| 284 | * There are several flags that change the way molecuilder is compiled and probably
|
|---|
| 285 | * make it run faster, more unsafe, ...
|
|---|
| 286 | * -# \a -DLOG_OBSERVER, What the Observers do is logged, the log is printed on exit
|
|---|
| 287 | * -# \a -DNO_MEMDEBUG, MemDebug (memory debugger) is disabled
|
|---|
| 288 | * -# \a -DNO_CACHING, Cachable are short-wired, i.e. always recalculate, this slows
|
|---|
| 289 | * down the code a lot
|
|---|
| 290 | * -# \a -DNDEBUG, include NO_MEMDEBUG, also ASSERTs are not checked, this speeds up
|
|---|
| 291 | * the code by a factor of 5
|
|---|
| 292 | *
|
|---|
| 293 | * \subsection install-difficulties Difficulties
|
|---|
| 294 | *
|
|---|
| 295 | * You might encounter some problems along the way, which we list up here:
|
|---|
| 296 | * -# Switching from Lucid Lynx to Precise Pangolin, libtool has been patched to
|
|---|
| 297 | * \b link_all_deplibs=no which causes linking to fail. A temporary way around it
|
|---|
| 298 | * is to seek&replace all instances in your build directory (replace no with
|
|---|
| 299 | * unknown). The more general way is to replace packaged and patched libtool
|
|---|
| 300 | * with an unpatched version you have to compile yourself.
|
|---|
| 301 | *
|
|---|
| 302 | * \section install-install Installing
|
|---|
| 303 | *
|
|---|
| 304 | * Now, we are ready to compile and install.
|
|---|
| 305 | *
|
|---|
| 306 | * \code
|
|---|
| 307 | * make
|
|---|
| 308 | * make install
|
|---|
| 309 | * \endcode
|
|---|
| 310 | *
|
|---|
| 311 | * \attention If you have a multi-core system, it is highly recommended to use the
|
|---|
| 312 | * \a -j option of make to allow for multiple threads to work on compiling or
|
|---|
| 313 | * checking the codfe simultaneously.
|
|---|
| 314 | *
|
|---|
| 315 | * And if everything went well, you should launch the unit tests and the testsuite
|
|---|
| 316 | * by (see section \ref tests on how to launch the tests individually)
|
|---|
| 317 | *
|
|---|
| 318 | * \code
|
|---|
| 319 | * make check
|
|---|
| 320 | * \endcode
|
|---|
| 321 | *
|
|---|
| 322 | * If everything is OK, you have a working version of MoleCuilder in form of the
|
|---|
| 323 | * executables \b bin/molecuilder and \b bin/molecuildergui.
|
|---|
| 324 | *
|
|---|
| 325 | * If you have to delete all compiled stuff, enter
|
|---|
| 326 | *
|
|---|
| 327 | * \code
|
|---|
| 328 | * make clean
|
|---|
| 329 | * \endcode
|
|---|
| 330 | *
|
|---|
| 331 | * or
|
|---|
| 332 | *
|
|---|
| 333 | * \code
|
|---|
| 334 | * make distclean
|
|---|
| 335 | * \endcode
|
|---|
| 336 | *
|
|---|
| 337 | * which will also delete all autoconf stuff for configure.
|
|---|
| 338 | *
|
|---|
| 339 | * distclean is at times necessary when stuff does not compile and there's
|
|---|
| 340 | * seemingly no logic behind it, i.e. especially when paths of modules have
|
|---|
| 341 | * changed. To recover your configure options, either look at \b config.log in
|
|---|
| 342 | * the build directory or enter
|
|---|
| 343 | *
|
|---|
| 344 | * \code
|
|---|
| 345 | * ./config.status --version
|
|---|
| 346 | * \endcode
|
|---|
| 347 | *
|
|---|
| 348 | * Further useful commands are
|
|---|
| 349 | * -# make clean uninstall: deletes .o-files and removes executable from the given
|
|---|
| 350 | * binary directory
|
|---|
| 351 | * -# make doc: Creates these html pages out of the documented source
|
|---|
| 352 | * -# make distcheck: Checks whether the code compiles and all tests runs without
|
|---|
| 353 | * from a distributed archive. This is checked for each release version.
|
|---|
| 354 | *
|
|---|
| 355 | * \date 2014-08-21
|
|---|
| 356 | */
|
|---|
