/**

\page Installation Installation

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 --prefix=/usr/local/lib
> make -j 4
> make doc # this is optional and requires doxygen installed
> make install
\endverbatim

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 patch \endlink
your favorite MD code so that it can be combined with PLUMED.
Again, for the impatients, something like this could do the job:
\verbatim
> source /plumed/root/dir/sourceme.sh
> cd /md/root/dir
> plumed patch -p
\endverbatim
Then compile your MD code.
For some MD software these instructions are not sufficient,
and you are invited to read well the instructions
at the end of this page.
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
with the new procedure, just put in place your old files. However,
it should be easy to enforce a similar setup on autoconf (by passing
the proper arguments on the command line) and we encourage this.
In case you have problems on your architecture, please
report to the mailing list.

Useful command line options for ./configure can be found typing
\verbatim
> ./configure --help
\endverbatim
Notice that some functionalities of PLUMED depend on external
libraries which are looked for by configure. You can typically
avoid looking for a library using the "disable" syntax, e.g.
\verbatim
> ./configure --disable-mpi --disable-matheval
\endverbatim

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. 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:
\verbatim
> ./configure CXX=icpc CC=icc
\endverbatim
Notice that in this example, since icpc is not an mpi compiler, mpi will not
be enabled.

To tune the compilation option you can use e.g.
\verbatim
> ./configure CXXFLAGS=-O3
\endverbatim

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)
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. 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
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.

\warning On Linux you might have problems using the LDFLAGS option. In particular,
if you have problems in linking file 'src/lib/plumed-shared', try to set correctly
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 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
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:
- DYNAMIC_LIB : these are the libraries needed to compile the PLUMED
library (e.g. -L/path/to/matheval -lmatheval etc). Notice that for the
PLUMED shared library to be compiled properly these should be dynamic
libraries. Also notice that PLUMED preferentially requires BLAS and LAPACK library;
see \ref BlasAndLapack for further info. Notice that the variables 
that you supply with `configure LIBS=something` will end up in this
variable. This is a bit misleading but is required to keep the configuration
files compatible with PLUMED 2.0.
- LIBS : these are the libraries needed when patching an MD code; typically only "-ldl" (needed to have functions for dynamic loading).
- CPPFLAGS : add here definition needed to enable specific optional functions;
e.g. use -D__PLUMED_HAS_MATHEVAL to enable matheval library
- SOEXT : this gives the extension for shared libraries in your system, typically
"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=").

\subsection 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 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
\verbatim
> 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
> cd regtest
> make
\endverbatim 
Notice that regtests are performed using the "plumed" executable that is currenty in the path.
You can check with exact version they will use with the command
\verbatim
> which plumed
\endverbatim
This means that if you do not source "sourceme.sh" file, tests will fails. Moreover, in case you have
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
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
hardcoded in the plumed executable and can be verified with
\verbatim
> plumed info --root
\endverbatim
In case you try to use the plumed executable without the compilation
directory in place (e.g. you move away the src/lib/plumed static executable
and delete or rename the compilation directory) PLUMED will 
not work correctly and will give you an
error message
\verbatim
> plumed help
ERROR: I cannot find /xxx/yyy/patches directory
\endverbatim
You can force plumed to run anyway using the option --standalone-executable:
\verbatim
> plumed --standalone-executable help
\endverbatim
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 InstallingPlumed Installing PLUMED

It might be convenient to install PLUMED in a predefined location.
This will allow you to remove the original compilation directory,
or to recompile e.g. a different PLUMED version in the same place.
Notice that installation *is optional*. Even from the compilation
directory, if 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"
\verbatim
> export PLUMED_PREFIX=$HOME/opt
> make install
\endverbatim
If PLUMED_PREFIX is not set, it will be assumed to be
the one set when configuring with autoconf. E.g. you could
have used
\verbatim
> ./configure --prefix=$HOME/opt
> make
> make install
\endverbatim
If not set, it defaults to /usr/local.
The install command should be executed with root permissions (e.g. "sudo make install")
in case you want to install PLUMED on a system directory.
An almost full copy of the compilation directory will
be installed into $PLUMED_PREFIX/lib/plumed/ directory. A link to the proper
PLUMED executable will be set up in $PLUMED_PREFIX/bin,
PLUMED include files will be copied to $PLUMED_PREFIX/include/plumed
and PLUMED libraries will be linked to $PLUMED_PREFIX/lib.

One should then set the environment properly. We suggest to do it using
the module framework (http://modules.sourceforge.net). An ad hoc generated
module file for PLUMED can then be found in $PLUMED_PREFIX/lib/plumed/src/lib/modulefile
Just edit it at your will and put it in your modulefile directory.
This will also allow you to install several PLUMED versions alongside and
switch among them. If you do not want to use modules, you can 
still have a look at the modulefile we did so as to know which
environment variables should be set for PLUMED to work correctly.

If the environment is properly configured one should be able to do
the following things:
- use "plumed" executable from the command line. this is also possible before installing.
- link against the PLUMED library using "-lplumed" flag for the linker. this allows
  one to use PLUMED library in general purpose programs
- use the PLUMED internal functionalities (C++ classes) including
  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 versions
alongside without using modules.
An alternative is to also define the environment variable PLUMED_LIBSUFFIX. E.g. with
\verbatim
> export PLUMED_PREFIX=$HOME/opt
> export PLUMED_LIBSUFFIX=v2.0
> make install
\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
do not want to set up modules, but we think using modules (see above) is more flexible.

\section Patching Patching your MD code

At the present times PLUMED can be added to the following list of codes:

@CODES@

To patch your MD code, you should have PLUMED already properly
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 (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
The script will interactively ask which MD engine you are patching.
- Recompile the MD code (if dependencies are set up properly in the MD engine,
  only modified files will be recompiled)

There are different options when patching, check them using 
\verbatim
> plumed patch --help
\endverbatim
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.

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".

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 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.

The free package ALMOST v.2.1 that MUST be dowloaded via SVN (svn checkout svn://svn.code.sf.net/p/almost/code/ almost-code).
ALMOST 2.1 can be found in branches/almost-2.1/ and it can be compiled:

\warning ALMOST needs SQLITE3, GZIP and BZIP2 installed on your computer.

\verbatim
./configure --prefix="wherever you want it" 
make
make install
\endverbatim

PLUMED will not use the RDCs module of ALMOST so you can ignore the warning about the LAPACK.

Once ALMOST is installeed, PLUMED 2 can then be configured with ALMOST enabled: 

\verbatim
./configure --enable-almost CPPFLAGS="-I/ALMOST_INSTALL_PATH/include -I/ALMOST_INSTALL_PATH/include/almost" LDFLAGS="-L/ALMOST_INSTALL_PATH/lib"
\endverbatim
with ALMOST_INSTALL_PATH the full path to the ALMOST installation folder.
 
*/