Improved installation doc

[makedoc]

user-doc/Installation.txt

@@ -11,12 +11,16 @@ For those of you who are impatient, the following might do the job:
 \verbatim
 > ./configure --prefix=/usr/local
 > make -j 4
-> make doc # this is optional and requires doxygen installed
-> make install # this is also optional - plumed can be used from the compilation directory
+> make doc # this is optional and requires proper doxygen version installed
+> make install
 \endverbatim
+Notice that `make install` is not strictly necessary  as plumed can be used from the compilation
+directory. This is very useful so as to quickly test the implementation of new features.
+However, we strongly recommend to perform a full install.
 
-Once the above is completed you can use PLUMED to analyze
-existing trajectories or you can play with the Lennard-Jones code that is included.
+Once the above is completed the `plumed` executable should be in your execution path
+and you will be able to use PLUMED to analyze
+existing trajectories or play with the Lennard-Jones code that is included.
 However, because PLUMED is mostly used to bias on the fly simulations
 performed with serious molecular dynamics packages, 
 you can find instructions about how to
@@ -24,7 +28,6 @@ you can find instructions about how to
 your favorite MD code so that it can be combined with PLUMED below.
 Again, if you are impatient, something like this will do the job:
 \verbatim
-> source /plumed/root/dir/sourceme.sh
 > cd /md/root/dir
 > plumed patch -p
 \endverbatim
@@ -34,7 +37,7 @@ It is thus recommended that you read the instructions
 at the end of this page.
 Notice that MD codes could in principle be "PLUMED ready"
 in their official distribution. If your favorite MD code is available "PLUMED ready" 
-you will have to compile PLUMED first as a library then check the MD codes' manual to
+you will have to compile PLUMED first, then (optionally) install it, then check the MD codes' manual to
 discover how to link it.
 
 \section ConfiguringPlumed Configuring PLUMED
@@ -99,29 +102,31 @@ first try to configure without any additional flags and to then check the log so
 or not the libraries were properly detected.
 
 If a library is not found during configuration, you can try to use options to modify the
-seatch path.
+search path.
 For example if your matheval libraries is in /opt/local (this is where MacPorts put it)
-use
+and configure is not able to find it you can try
 \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
 without any additional flag, and then in case of failure will retry adding
-"-lmatheval" to the LIBS options. This allows you to use libraries
+"-lmatheval" to the LIBS options.
+If also this does not work, the matheval library will be
+disabled and some features will not be available.
+This procedure allows you to use libraries
 with custom names. 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.
-If not it will try adding "-lmatheval". If also this does not work, the matheval library will be
-disabled and some features will not be available.
+In this example, the linker will directly try to link `/opt/local/lib/libmymatheval.so`.
 This rule is true for all the libraries, so that you will always be able to link
 a specific version of a library by specifying it using the LIBS variable.
 
 \warning On Linux you might have problems using the LDFLAGS option. In particular,
-if you have problems in linking the file 'src/lib/plumed-shared', try to set correctly
+if makefile complaints that it cannot link the file 'src/lib/plumed-shared',
+try to set correctly
 the runtime path by using
 \verbatim
 > ./configure LDFLAGS="-L/opt/local/lib -Wl,-rpath,/opt/local/lib" \
@@ -133,7 +138,7 @@ with MD codes later.
 
 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).
+look for them without any link flag, then add "-lblas" and "-llapack", respectively).
 As such  if you want to use a specific version of blas or lapack
 you can make them available to configure by using
 \verbatim
@@ -210,19 +215,21 @@ Once configured, PLUMED can be compiled using the following command:
 This will compile the entire code and produce a number of files
 in the 'src/lib' directory, including the executable 
 'src/lib/plumed'. When shared libraries are enabled,
-a shared libraries called 'src/lib/libKernel.so' should also have been compiled. 
+a shared libraries called 'src/lib/libKernel.so' should also be present.
 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:
+In case you want to run PLUMED *without installing it* (i.e. from the compilation
+directory), you can use the file 'sourceme.sh' that has been created by
+the configure script in the main PLUMED directory.
+This file can be "sourced" (presently only working for bash shell)
+if you want to use PLUMED *before installing it* (i.e. from the compilation
+directory). It is a good idea to source it now, so that you can play with the just compiled
+PLUMED:
 \verbatim
 > source sourceme.sh
 \endverbatim
 
-If compilation is successful, 
+Now
 a "plumed" executable should be in your path. Try to type
 \verbatim
 > plumed -h
@@ -230,7 +237,7 @@ a "plumed" executable should be in your path. Try to type
 
 \warning If 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.
+or compile the manual. This is not a problem.
 
 You can also check if PLUMED is correctly compiled by performing our regression tests.
 Be warned that some of them fail because of the different numerical accuracy on different machines.
@@ -272,29 +279,32 @@ this is currently the only way to use the PLUMED static executable on Windows.
 
 \section InstallingPlumed Installing PLUMED
 
-It might be convenient to install PLUMED in a predefined location.
+It is strongly suggested to
+install PLUMED in a predefined location.
+This is done using
+\verbatim
+> make install
+\endverbatim
 This will allow you to remove the original compilation directory,
 or to recompile a different PLUMED version in the same place.
-Notice that installation *is optional*. Even from the compilation
-directory, if the environment is properly set (see sourceme.sh file)
-PLUMED should work.
 
-To install PLUMED one should first decide the location. Just set
-the environment variable PLUMED_PREFIX, then type "make install"
+To install PLUMED one should first decide the location.
+The standard way to do it is during the configure step:
 \verbatim
-> export PLUMED_PREFIX=$HOME/opt
+> ./configure --prefix=$HOME/opt
+> make
 > make install
 \endverbatim
-If PLUMED_PREFIX is not set, it will be assumed to be
-the one set when you configured with autoconf. So if you configured
-using
+However, you can also change it after compilation setting
+the environment variable PLUMED_PREFIX.
 \verbatim
-> ./configure --prefix=$HOME/opt
+> ./configure
 > make
+> export PLUMED_PREFIX=$HOME/opt
 > make install
 \endverbatim
-Then the PLUMED_PREFIX will be set equal to $HOME/opt.
-If the PLUMED_PREFIX is not set, it defaults to /usr/local.
+If you didn't specify the --prefix option during configure, and you did not set the PLUMED_PREFIX
+environment variable, PLUMED will be installed in /usr/local.
 The install command should be executed with root permissions (e.g. "sudo make install")
 if you want to install PLUMED on a system directory.
 Notice that upon installation PLUMED currently needs to relink a library. If
@@ -370,25 +380,50 @@ There are different options available when patching. You can check all of them u
 > plumed patch --help
 \endverbatim
 Particularly interesting options include:
-- --static (default) just link PLUMED as a collection of object files.
+- --static (default) just link PLUMED as a collection of object files. This is only suggested if for external reasons you
+  absolutely need a static executable. Notice that with this setting it is often more complicated to configure
+  properly the MD code, since all the libraries that PLUMED depends on should be properly specified. The `./configure` script
+  does its best in this sense, but sometime it cannot solve the problem. Additionally, this patching mode has been reported
+  not to work properly on OSX.
 - --shared allows you to link PLUMED as a shared library. As a result when PLUMED is updated, there will be no need to recompile the MD code.
+  This is way better than --static since the libraries that PLUMED depends on should be automatically linked.
+  Notice that if you later remove the directory where PLUMED is installed also the MD code will not run anymore.
 - --runtime allows you to choose the location of the PLUMED library at runtime by setting the variable PLUMED_KERNEL.
+  This is probably the most flexible option, and we encourage system administrators to use this option when installing
+  PLUMED on shared facilities. Indeed, using this setting it will be possible to update separately the PLUMED library
+  and the MD code, leaving to the user the possibility to combine different versions at will. 
+  We also recommend to use the provided modulefile (see above) to properly set the runtime environment.
 
 Notice that it is not currently possible to link PLUMED as a static library (something like 'libplumed.a').
 The reason for this is that PLUMED heavily relies on C++ static constructors that do not behave well in static libraries.
 For this reason, to produce a static executable with an MD code + PLUMED we link PLUMED as a collection of object files.
 
-A note for cross compiling: if you are compiling an executable from a different machine, then then
-"plumed" executable will not be available in the compilation environment. You should thus use the following command
-\verbatim
-> plumed-patch
-\endverbatim
-as a replacement for "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
 manual </a>.
 
+\section CrossCompiling Cross compiling
+
+If you are compiling an executable from a different machine, then
+`plumed` executable will not be available in the compilation environment.
+This means that you won't be able to perform regtests on the machine
+nor to compile the manual.
+You can try to run the regtests on the computing nodes, but this might require some tweak
+since often machines where people do cross compiling have architectures with limited capabilities
+on the compute nodes. Also notice that many of the `plumed` options (e.g. patch) are implemented
+as shell scripts launched from within the `plumed` executable. If the compute nodes have some limitation
+(e.g. they do not allow to fork new processes) these options will not work. Anyway, the PLUMED library
+in combination with an MD software should work if both PLUMED and the MD software have been properly compiled.
+
+Also notice that it will not be possible
+to use the command `plumed patch` on the machine where you are compiling.
+You should thus use `plumed-patch` instead of `plumed patch` (notice that it should be written as a single word).
+Try e.g.:
+\verbatim
+> plumed-patch --help
+\endverbatim
+This script provides a "shell only" implementation of `plumed patch` that will skip the launch of the `plumed` executable.
+
 \section installingalmost Installing PLUMED with ALMOST
 
 In order to used some of the NMR based collective variables (\ref CS2BACKBONE and \ref CH3SHIFTS) PLUMED needs to be linked with ALMOST.