diff --git a/user-doc/Installation.txt b/user-doc/Installation.txt
index 86e628176d9875316a5c534075d979f8151d7fee..2e4f278c479d732ebfad28233a52d4c052ef738a 100644
--- a/user-doc/Installation.txt
+++ b/user-doc/Installation.txt
@@ -2,13 +2,35 @@
\page Installation Installation
-\section CompilingPlumed Compiling PLUMED
-
-Since version 2.1, PLUMED can be configured using autoconf. Just type:
+In this page you can learn how to
+\link ConfiguringPlumed configure\endlink,
+\link CompilingPlumed compile\endlink,
+and \link InstallingPlumed install\endlink
+PLUMED.
+For the impatients, something like this could do the job:
\verbatim
-> ./configure
+> ./configure --prefix=/usr/local/lib
+> make -j 4
+> make doc # this is optional and requires doxygen installed
+> make install
\endverbatim
-This is going to generate a Makefile.conf file and a sourceme.sh file.
+
+This is enough if you want to use PLUMED to analyze
+existing trajectories or to play with the included Lennard-Jones code.
+Since PLUMED is mostly used to bias on the fly simulations
+performed with serious molecular dynamics packages,
+below you can find instructions about how to
+\link Patching link PLUMED \endlink
+to your favorite MD code.
+Notice that MD codes could in principle be "PLUMED ready"
+in their official distribution. In this case, probably
+you have to compile PLUMED first as a library then check their manual to
+discover how to link it.
+
+\section ConfiguringPlumed Configuring PLUMED
+
+The "./configure" command
+just generates a Makefile.conf file and a sourceme.sh file.
In PLUMED 2.0 these files where pre-prepared and stored in the
directory configurations/. The new ones generated by ./configure
should be compatible with the old ones. In other words, if you find in trouble
@@ -32,7 +54,9 @@ avoid looking for a library using the "disable" syntax, e.g.
Notice that when mpi search is enabled (by default) compilers
such as "mpic++" and "mpicxx" are searched first. On the other hand,
if mpi search is disabled ("./configure --disable-mpi") non-mpi
-compilers are searched.
+compilers are searched. Also notice that only a few of the
+possible compiler name are searched. Thus, compilers such as
+"g++-mp-4.8" should be explicitly requested with the CXX option.
You can better control which compiler is used with the
variables CXX and CC. E.g., to use Intel compilers:
@@ -42,7 +66,7 @@ variables CXX and CC. E.g., to use Intel compilers:
Notice that in this example, since icpc is not an mpi compiler, mpi will not
be enabled.
-You can also tune the compilation options
+To tune the compilation option you can use e.g.
\verbatim
> ./configure CXXFLAGS=-O3
\endverbatim
@@ -51,24 +75,38 @@ In case you want to build with debug flags so as to do some checking you can use
\verbatim
> ./configure --enable-debug
\endverbatim
-This will perform some extra check during execution (possibly slowing down PLUMED a bit)
-and write full symbol table in the executable.
+This will perform some extra check during execution (possibly slowing down PLUMED)
+and write full symbol table in the executable (making in much larger).
The main goal of the automatic configure is to find libraries.
In case they are stored in unconventional places you might have to
-suggest their location.
+suggest their location. Notice that there are some
+environment variable that can be used to instruct the linker
+on where libraries should be searched. These variables are compiler dependent,
+but could have been set by the system administrator so that libraries are found
+without any extra flag. Because of this, the suggested procedure is to
+first try without any extra flag and check from the log which libraries where properly
+detected.
+
+In case a library has not been found, you can try to use options to modify the
+seatch path.
E.g. if your matheval libraries is in /opt/local (this is where MacPorts put it)
use
\verbatim
> ./configure LDFLAGS=-L/opt/local/lib CPPFLAGS=-I/opt/local/include
\endverbatim
Notice that PLUMED will first try to link a routine from say matheval
-directly, and then try to add "-lmatheval" to the library. So, if
+without any additional flag, and then in case of failure will retry adding
+"-lmatheval" to the LIBS options. This allows you to use libraries
+with custom name. So, if
your matheval library is called /opt/local/lib/libmymatheval.so you can
link it with
\verbatim
> ./configure LDFLAGS=-L/opt/local/lib CPPFLAGS=-I/opt/local/include LIBS=-lmymatheval
\endverbatim
+In this example, if the linker finds the libmymatheval.so library it will be happy with that.
+If not it will try adding "-lmatheval". If also this does not work, matheval library will be
+disabled and some features will not be available.
This rule is true for all the libraries, so that you will always be able to link
a specific version of a library by adding it to the LIBS variable.
@@ -78,17 +116,28 @@ the runtime path with e.g.
\verbatim
> ./configure LDFLAGS="-L/opt/local/lib -Wl,-rpath,/opt/local/lib" CPPFLAGS=-I/opt/local/include LIBS=-lmymatheval
\endverbatim
-
-Notice that PLUMED needs blas and lapack. The configure script
-is first looking for them in the standard path, then with option "-lblas" and
-"-llapack", respectively. Thus, if you want to use a specific version of them
+Notice that although the file 'src/lib/plumed-shared' is not necessary, being
+able to produce it means that it will be possible to link PLUMED dynamically
+with MD codes later.
+
+Notice that PLUMED needs blas and lapack. These are treated slighty different from
+other libraries. The search is done in the usual way (i.e., first
+look for them without any link flag, then add "-lblas" and "-llapack", resepctively).
+Thus, if you want to use a specific version of them
you can just make them available to configure with
\verbatim
> ./configure LDFLAGS=-L/path/to/blas/lib LIBS=-lnameoflib
\endverbatim
-The script is also finding out if function names have the final underscore added,
-so this should be completely transparent to the user.
-In case blas or lapack are not found, the internal versions are used.
+If the functions of these libraries are not found, the compiler
+looks for a version with final underscore added.
+Finally, since blas and lapack are compulsory in PLUMED,
+if also this second search fails an internal replacement is used.
+Notice that this procedure is transparent to the user.
+In case one wants to disable the search for external libraries
+(e.g. because the system libraries have problems) this can be done with
+\verbatim
+> ./configure --disable-external-lapack
+\endverbatim
As a final resort, you may also edit the resulting Makefile.conf file.
Notable variables there:
@@ -107,19 +156,57 @@ e.g. use -D__PLUMED_HAS_MATHEVAL to enable matheval library
"so" on unix, "dylib" on mac; in case your system does not support dynamic libraries or, for some other reason, you would like only static executables you can
just set this variable to a blank ("SOEXT=").
-Also notice that a new file sourceme.sh
-appears in the main PLUMED directory.
-This file should be "sourced" (presently only working for bash shell)
-if you want to use PLUMED *without installing it* (i.e. from the compilation
-directory. It is a good idea to source it now:
-\verbatim
-> source sourceme.sh
-\endverbatim
+\subsection BlasAndLapack BLAS and LAPACK
-Then compile PLUMED
+We tried to keep PLUMED as independent as possible from external libraries.
+Moreover, some libraries (e.g. Almost and Matheval) providing
+extra features are optional. However, to have a properly working PLUMED
+you need BLAS and LAPACK libraries.
+In case you cannot manage to install blas and lapack, you can use the internal
+ones. Just add to the CPPFLAGS the flags -D__PLUMED_INTERNAL_BLAS
+-D__PLUMED_INTERNAL_LAPACK.
+The automatic configure should be able to choose automatically the internal
+libraries when necessary.
+
+Some additional notes follow.
+
+First of all, the DYNAMIC_LIB variable in the Makefile.conf
+should contain the flag necessary to load these libraries
+(typically -llapack -lblas, in some case followed by -lgfortran
+but full path specification with -L should be necessary depending on your system configuration).
+
+Even though you can incur in some problem.
+- If the linker complains and suggest to recompiled lapack with -fPIC, it means that you have static lapack libraries. Either install dynamic lapack libraries
+or switch to static compilation of PLUMED (by unsetting the SOEXT variable
+in configuration file).
+- If the linker complains that dsyevr_ cannot be found, try to add
+ -DF77_NO_UNDERSCORE to CPPFLAGS
+- If the linker complains about other missing functions (typically starting with
+ "for_" prefix) then you should link also Fortran libraries. Indeed, PLUMED
+ is written in C++ and often C++ linkers do not include by default Fortran libraries
+ which are required for lapack and blas to work. Please check the documentation of your compiler.
+
+\section CompilingPlumed Compiling PLUMED
+
+Once configured, PLUMED can be compiled using the following command:
\verbatim
> make -j 4
\endverbatim
+This will compile the entire code and produce a number of files
+in the 'src/lib' directory, including the executable
+'src/lib/plumed'. In case shared libraries are enabled,
+also a shared libraries should have been compiled, namely
+'src/lib/libKernel.so'. Notice that the extension could be
+'.dylib' on a Mac.
+
+The file 'sourceme.sh' that has been created by
+the configure script in the main PLUMED directory
+can be "sourced" (presently only working for bash shell)
+if you want to use PLUMED *without installing it* (i.e. from the compilation
+directory). It is a good idea to source it now:
+\verbatim
+> source sourceme.sh
+\endverbatim
If compilation is successful,
a "plumed" executable should be in your path. Try to type
@@ -127,6 +214,10 @@ a "plumed" executable should be in your path. Try to type
> plumed -h
\endverbatim
+\warning In case you are cross compiling, the plumed executable
+will not work. As a consequence, you won't be able to run regtests
+or compile the manual.
+
You can also check if PLUMED is correctly compiled performing our regression tests.
Be warned that some of them just fails because of the different numerical accuracy of different machines.
\verbatim
@@ -142,7 +233,7 @@ This means that if you do not source "sourceme.sh" file, tests will fails. Moreo
another version of PLUMED installed somewhere regtests might use that one instead
of the just-compiled one.
-Also notice that the compiled executable, which now sits in src/lib/plumed, relies
+Also notice that the compiled executable, which now sits in 'src/lib/plumed', relies
on other resource files present in the compilation directory.
This directory should thus stay in the correct place, and one should not
rename or delete it. The path to the PLUMED root directory is indeed
@@ -166,36 +257,6 @@ You can force plumed to run anyway using the option --standalone-executable:
Anyway, many features will not be available in this way.
This is currently the only way to use a PLUMED static executable on Windows.
-\section BlasAndLapack BLAS and LAPACK
-
-We tried to keep PLUMED as independent as possible from external libraries.
-Moreover, some libraries (e.g. Almost and Matheval) providing
-extra features are optional. However, to have a properly working PLUMED
-you need BLAS and LAPACK libraries.
-In case you cannot manage to install blas and lapack, you can use the internal
-ones. Just add to the CPPFLAGS the flags -D__PLUMED_INTERNAL_BLAS
--D__PLUMED_INTERNAL_LAPACK.
-The automatic configure should be able to choose automatically the internal
-libraries when necessary.
-
-Some additional notes follow.
-
-First of all, the DYNAMIC_LIB variable in the Makefile.conf
-should contain the flag necessary to load these libraries
-(typically -llapack -lblas, in some case followed by -lgfortran
-but full path specification with -L should be necessary depending on your system configuration).
-
-Even though you can incur in some problem.
-- If the linker complains and suggest to recompiled lapack with -fPIC, it means that you have static lapack libraries. Either install dynamic lapack libraries
-or switch to static compilation of PLUMED (by unsetting the SOEXT variable
-in configuration file).
-- If the linker complains that dsyevr_ cannot be found, try to add
- -DF77_NO_UNDERSCORE to CPPFLAGS
-- If the linker complains about other missing functions (typically starting with
- "for_" prefix) then you should link also Fortran libraries. Indeed, PLUMED
- is written in C++ and often C++ linkers do not include by default Fortran libraries
- which are required for lapack and blas to work. Please check the documentation of your compiler.
-
\section Installing Installing PLUMED
It might be convenient to install PLUMED in a predefined location.
@@ -246,7 +307,7 @@ the following things:
header files such as "#include <plumed/tools/Vector.h>". this is also usefule to
exploit the PLUMED library in general purpose programs
-As a final note, one may want to install several PLUMED version
+As a final note, one may want to install several PLUMED versions
alongside without using modules.
An alternative is to also define the environment variable PLUMED_LIBSUFFIX. E.g. with
\verbatim
@@ -256,7 +317,7 @@ An alternative is to also define the environment variable PLUMED_LIBSUFFIX. E.g.
\endverbatim
will install plumed executable with name "plumed-v2.0". All the other files will be renamed accordingly,
e.g. the PLUMED library will be loaded with "-lplumed-v2.0" and the PLUMED header files
-will be included with "\#include <plumed-v2.0/tools/Vector.h>". This trick is useful if you
+will be included with "#include <plumed-v2.0/tools/Vector.h>". This trick is useful if you
do not want to set up modules, but we think using modules (see above) is more flexible.
\section Patching Patching your MD code
@@ -270,10 +331,10 @@ working. In particular, you should have the command "plumed" in your execution
path, either because it is installed or because you are using it
from the compilation directory.
Then, follow these steps
-- Configure and compile your MD enginge
-- Test if it is working properly
-- Go to the root diretory of the MD engine
-- Patch:
+- Configure and compile your MD enginge (look for the instructions in its documentation).
+- Test if it is working properly.
+- Go to the root directory of the source code of the MD engine.
+- Patch with PLUMED:
\verbatim
> plumed patch -p
\endverbatim
@@ -285,18 +346,22 @@ There are different options when patching, check them using
\verbatim
> plumed patch --help
\endverbatim
-Interesing ones:
-- --shared allows you to link PLUMED as a shared library. when PLUMED is updated, there will be no need to recompile the MD code
+Interesting ones are:
+- --static (default) just link PLUMED as a collection of object files.
+- --shared allows you to link PLUMED as a shared library. when PLUMED is updated, there will be no need to recompile the MD code.
- --runtime allows you to choose the location of the PLUMED library at runtime, setting the variable PLUMED_KERNEL.
-- --static (default) just link PLUMED as a collection of object files
+
+Notice that it is not currently possible to link PLUMED as a static library (something like 'libplumed.a').
+The reason is that PLUMED heavily relies on C++ static constructors that do not behave well in static libraries.
+For this reason, the only we to produce a static executable with an MD code + PLUMED is
+to link PLUMED as a collection of object files.
A note for cross compiling: in case you are compiling an executable from a different machine, then
"plumed" executable will not be available in the compilation environment. You can thus use the following command
\verbatim
> plumed-patch
\endverbatim
-as a replacement of "plumed patch". This trick only works with those commands which are implemented as pure scripts
-(e.g. there is no "plumed-help" available...).
+as a replacement of "plumed patch".
If your MD code is not supported, you may want to implement an interface for
it. Refer to the <a href="../../developer-doc/html/index.html"> developer