Changeset 6752dc for src/documentation/install.dox

Timestamp:

Feb 14, 2013, 12:26:01 PM (12 years ago)

Author:

Frederik Heber <heber@…>

Branches:

Action_Thermostats, Add_AtomRandomPerturbation, Add_FitFragmentPartialChargesAction, Add_RotateAroundBondAction, Add_SelectAtomByNameAction, Added_ParseSaveFragmentResults, AddingActions_SaveParseParticleParameters, Adding_Graph_to_ChangeBondActions, Adding_MD_integration_tests, Adding_ParticleName_to_Atom, Adding_StructOpt_integration_tests, AtomFragments, Automaking_mpqc_open, AutomationFragmentation_failures, Candidate_v1.5.4, Candidate_v1.6.0, Candidate_v1.6.1, ChangeBugEmailaddress, ChangingTestPorts, ChemicalSpaceEvaluator, CombiningParticlePotentialParsing, Combining_Subpackages, Debian_Package_split, Debian_package_split_molecuildergui_only, Disabling_MemDebug, Docu_Python_wait, EmpiricalPotential_contain_HomologyGraph, EmpiricalPotential_contain_HomologyGraph_documentation, Enable_parallel_make_install, Enhance_userguide, Enhanced_StructuralOptimization, Enhanced_StructuralOptimization_continued, Example_ManyWaysToTranslateAtom, Exclude_Hydrogens_annealWithBondGraph, FitPartialCharges_GlobalError, Fix_BoundInBox_CenterInBox_MoleculeActions, Fix_ChargeSampling_PBC, Fix_ChronosMutex, Fix_FitPartialCharges, Fix_FitPotential_needs_atomicnumbers, Fix_ForceAnnealing, Fix_IndependentFragmentGrids, Fix_ParseParticles, Fix_ParseParticles_split_forward_backward_Actions, Fix_PopActions, Fix_QtFragmentList_sorted_selection, Fix_Restrictedkeyset_FragmentMolecule, Fix_StatusMsg, Fix_StepWorldTime_single_argument, Fix_Verbose_Codepatterns, Fix_fitting_potentials, Fixes, ForceAnnealing_goodresults, ForceAnnealing_oldresults, ForceAnnealing_tocheck, ForceAnnealing_with_BondGraph, ForceAnnealing_with_BondGraph_continued, ForceAnnealing_with_BondGraph_continued_betteresults, ForceAnnealing_with_BondGraph_contraction-expansion, FragmentAction_writes_AtomFragments, FragmentMolecule_checks_bonddegrees, GeometryObjects, Gui_Fixes, Gui_displays_atomic_force_velocity, ImplicitCharges, IndependentFragmentGrids, IndependentFragmentGrids_IndividualZeroInstances, IndependentFragmentGrids_IntegrationTest, IndependentFragmentGrids_Sole_NN_Calculation, JobMarket_RobustOnKillsSegFaults, JobMarket_StableWorkerPool, JobMarket_unresolvable_hostname_fix, MoreRobust_FragmentAutomation, ODR_violation_mpqc_open, PartialCharges_OrthogonalSummation, PdbParser_setsAtomName, PythonUI_with_named_parameters, QtGui_reactivate_TimeChanged_changes, Recreated_GuiChecks, Rewrite_FitPartialCharges, RotateToPrincipalAxisSystem_UndoRedo, SaturateAtoms_findBestMatching, SaturateAtoms_singleDegree, StoppableMakroAction, Subpackage_CodePatterns, Subpackage_JobMarket, Subpackage_LinearAlgebra, Subpackage_levmar, Subpackage_mpqc_open, Subpackage_vmg, Switchable_LogView, ThirdParty_MPQC_rebuilt_buildsystem, TrajectoryDependenant_MaxOrder, TremoloParser_IncreasedPrecision, TremoloParser_MultipleTimesteps, TremoloParser_setsAtomName, Ubuntu_1604_changes, stable

Children:

1b01e9

Parents:

0a7834

git-author:

Frederik Heber <heber@…> (01/03/13 13:49:00)

git-committer:

Frederik Heber <heber@…> (02/14/13 12:26:01)

Message:

DOCU: Extended installation explanations extensively.

File:

• src/documentation/install.dox (modified) (3 diffs)

src/documentation/install.dox

@@ -16 +16 @@
  *  \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
+ *
+ *  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 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
+ *  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 --enable-fcs-solvers=vmg
+ *  \endcode
+ *
+ *  \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
  *
@@ -34 +155 @@
  * \endcode
  *
- * which will run the configure script that checks whether you have a current
- * version of the following required packages:
- *
+ * 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>)
+ * -# 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>)
@@ -94 +215 @@
  *  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
  *