Changeset 750cff for src/documentation/install.dox

Timestamp:

Oct 31, 2011, 5:13:52 PM (13 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:

5982c5

Parents:

19bc74

Message:

HUGE: Update on documenation.

• a general skeleton of the documentation is now in place with all the major components of MoleCuilder explained to some extent.
• some information has been transfered from TRAC (e.g. install procecure) into this doxygen documentation where it is general and not specific to the situation at our institute.

File:

• src/documentation/install.dox (modified) (1 diff)

src/documentation/install.dox

@@ -13 +13 @@
  */
 
-/* \page install Installation
+/**
+ *  \page install Installation
  *
- *  Installation should without problems succeed as follows:
- *  -# ./configure (or: mkdir build;mkdir run;cd build; ../configure --bindir=../run)
- *  -# make
- *  -# make install
+ * \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\n
- *  -# make doxygen-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.
+ *  -# 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
  */