I write here some notes related to how plumed is installed.

As a first notice, plumed package is mostly designed to make available these tools:

a plumed executable, that can be used to launch command line tools.
a libplumed.so library, that can be linked to an externally supplied MD code.

These are the main entry points to plumed, but they require several other resources to be properly located so as to work. Moreover, plumed is designed to be usable both when "just compiled" (so as to allow for fast development) and when properly installed. This result in the non trivial problem of knowing where the required resources are located.

Additionally, we provide shell-only alternatives to command line tools. E.g., to use plumed patch in a cross compiled environment, one can call plumed-patch which does the same but bypass the plumed executable and directly executes as a bash script.

As a result, plumed routines and scripts can be entered in three ways:

calling plumed from the command line.
calling plumed-patch from the command line.
entering the shared library from another code (typically an MD code).

This is achieved in the following way:

plumed-* scripts set appropriate environment variables pointing at the correct paths when they are launched.
plumed executable and libplumed.so have access to methods (in the config namespace) to access to the paths and locate resources.

As an example, the $PLUMED_ROOT variable is defined to tell to the plumed scripts where to find most of the plumed-related files. Similarly, from C++ you can use config::getPlumedRoot() to get the same path.

When a plumed command line tool implemented as script is invoked by the plumed executable, thus transfering the control from C++ to an external script, the environment should be consistently set. This is done in method config::getEnvCommand() which builds a string in the form "env PLUMED_ROOT=/path env PLUMED_INCLUDEDIR=/path " etc. In this ways, the scripts are run in an environment with the correct settings.

The following paths need to be set for plumed to work properly. Here they are listed together with the name of the corresponding environment variable (that can be used in plumed scripts) and the method that can be used to retrieve them from C++ code.

Root of plumed: PLUMED_ROOT config::getPlumedRoot()
Path to include files: PLUMED_INCLUDEDIR config::getPlumedIncludedir()
Path to html files: PLUMED_HTMLDIR config::getPlumedHtmldir()
Name of plumed program: PLUMED_PROGRAM_NAME config::getPlumedProgramName()

When using plumed from its build directory (without installing) these paths will be set to the value reported below:

Root of plumed: /build/directory
Path to include files: /build/directory/include (this works thanks to a symlink of /build/directory/src to /build/directory/include/plumed)
Path to html files: /build/directory
Name of plumed program: plumed

These paths are hardcoded in plumed executable and in plumed-* scripts when they are compiled. Notice that it is possible to set the PLUMED_ROOT variable before calling plumed overriding the hard code values. E.g., you can compile plumed in directory /build/directory1, move it to /build/directory2, and launch it with PLUMED_ROOT=/build/directory2 /build/directory2/src/lib/plumed. Notice however that although plumed will find all the required resources in this way, it won't be possible to perform some task such as patching MD code.

When using plumed after installed, these paths will be set to the value reported below:

Root of plumed: /usr/local/lib/plumed
Path to include files: /usr/local/include
Path to html files: /usr/local/share/doc/plumed
Name of plumed program: plumed

These paths are hardcoded in plumed executable and in plumed-* scripts when they are installed. Notice that these value can be customized at configure step using standard arguments to ./configure. When using an installed copy of plumed one can override the hard code values by setting the variables PLUMED_ROOT PLUMED_INCLUDEDIR PLUMED_HTMLDIR and PLUMED_PROGRAM_NAME before launching plumed.

Notice that to enforce a consistent behavior of scripts and plumed executable the same logic needed to be implemented twice. One implementation is found in the src/config/Config.cpp file, another implementation is prependend to the installed scripts by the src/config/Makefile.

Also consider that environment is inherited by subprocesses. That means that if you want to launch another plumed version from a plumed script (crazy idea, perhaps nobody will ever do it) you should unexport the relevant environment variables so that the second plumed executable will find its paths correctly.

Installed files

I here describe what's the content of the most important files installed by plumed.

/usr/local/bin/plumed: this is a static executable that can be used to launch plumed. It is typically used to launch a command line tool (e.g. plumed sum_hills). Notice that some command line tools are actually implemented as bash scripts (e.g. plumed patch). Those scripts are located in $PLUMED_ROOT/scripts/ with an extra .sh suffix. E.g. the plumed patch will set properly the environment then call $PLUMED_ROOT/scripts/patch.sh.

/usr/local/lib/libplumed.so: this is a library containing all the plumed routines. Notice that /usr/local/bin/plumed described above is equal to the combination of /usr/local/lib/libplumed.so with a single object file compiled from buildroot/src/main/main.cpp.

/usr/local/lib/libplumedKernel.so: this is a library containing almost all the plumed routines, with the exception of those called from MD engines. Notice that /usr/local/lib/libplumed.so described above is equal to the combination of /usr/local/lib/libplumedKernel.so with a single object file compiled from buildroot/src/wrapper/PlumedStatic.cpp

To summarize:

bin/plumed = buildroot/src/main/main.cpp + lib/libplumed.so
lib/libplumed.so = buildroot/src/wrapper/PlumedStatic.cpp + lib/libplumedKernel.so

The logic of this subdivision is that it is possible to either link the MD code to /usr/local/lib/libplumed.so or to link it to a single object file (the one compiled from buildroot/src/wrapper/Plumed.c) so as to allow linking at run time an a posteriori chosen plumed library. This is the trick behind the --runtime patching procedure.

Notice that the only differences between buildroot/src/wrapper/PlumedStatic.cpp and buildroot/src/wrapper/Plumed.c are that runtime binding is disabled for the first one and that the second one is compiled as plain C. This makes it less likely to do mistakes when linking lib/libplumed.so (by unintentionally using a different version of plumed), and makes C++ library unnecessary if an external code is only interesting in linking the PLUMED wrappers in buildroot/src/wrapper/Plumed.c.

We can then dissect more the content of /usr/local/lib/libplumedKernel.so. This library puts together a large list of object files. The same object files will be located after install in /usr/local/lib/plumed/obj/k*.o. I use a wildcard here because these might be many files (named k0.o, 'k1.o', etc) or a single kernel.o file (when ld -r -o can be used to merge them together). The reason why we store object files in the installed directory is that this is the most portable way to link statically C++ objects to another executable. Indeed, merging them in a single .a file (such as libplumed.a) would require this library to be linked with special flags so as to allow dropping all the static constructors. Whereas the special flags could be found by autoconf, it seems simpler to directly link /usr/local/lib/plumed/obj/k*.o.

Also notice that this library changes slighlty in the installed version (/usr/local/lib/libplumedKernel.so) and in the pre-install version (buildroot/src/lib/libplumedKernel.so). Indeed, whereas the former include the object file from buildroot/src/config/ConfigInstall.cpp the latter includes the object file from buildroot/src/config/Config.cpp. This object file is the one containing the hardcoded paths discussed above, and thus should include different strings in the installed and pre-install versions.

Installation procedure

When make is invoked, several things are performed. First, all the source files are compiled. The plumed executable and the library files are put in buildroot/src/lib. Then, the "to be installed" versions of the executable and library files are produced and located in buildroot/src/lib/install. These are different from those located in buildroot/src/lib in that they include the buildroot/src/config/ConfigInstall.o object so as to hardcode the proper paths.

When make install is invoked, the makefile checks if the objects in buildroot/src/lib/install should be updated and, if necessary, recompiles them. If not, it just copies all the material in place. Notice that all the resulting files are real files (no symlinks). This is a novelty with respect to PLUMED 2.1 and allows for a proper implementation of the DESTDIR feature required by unix distributions.

Using the standard behavior explained in the autoconf documentation, it is possible to change the paths for plumed install either during configure (with --prefix) or by setting prefix during make install.