docs/dev-manual/relocatable-binaries.rst

   1 Relocatable binaries
   2 ====================
   3
   4 |Gromacs| (mostly) implements the concept of relocatable binaries, i.e., that
   5 after initial installation to ``CMAKE_INSTALL_PREFIX`` (or binary packaging
   6 with CPack), the whole installation tree can be moved to a different folder and
   7 |Gromacs| continues to work without further changes to the installation tree.
   8 This page explains how this is implemented, and the known limitations in the
   9 implementation.  This information is mainly of interest to developers who need
  10 to understand this or change the code, but it can also be useful for people
  11 installing or packaging |Gromacs|.
  12
  13 A related feature that needs to be considered in all the code related to this
  14 is that the executables should work directly when executed from the build tree,
  15 before installation.  In such a case, the data files should also be looked up
  16 from the source tree to make development easy.
  17
  18 Finding shared libraries
  19 ------------------------
  20
  21 If |Gromacs| is built with dynamic linking, the first part of making the
  22 binaries relocatable is to make it possible for the executable to find
  23 ``libgromacs``, no matter how it is executed.  On platforms that support
  24 a relative RPATH, this is used to make the |Gromacs| executables find the
  25 ``libgromacs`` from the same installation prefix.  This makes the executables
  26 fully relocatable when it comes to linking, as long as the relative folder
  27 structure between the executables and the library is kept the same.
  28
  29 If the RPATH mechanism does not work, ``GMXRC`` also adds the absolute path to
  30 the ``libgromacs`` installed with it to ``LD_LIBRARY_PATH``.  On platforms that
  31 support this, this makes the linker search for the library here, but it is less
  32 robust, e.g., when mixing calls to different versions of |Gromacs|.  Note that
  33 ``GMXRC`` is currently not relocatable, but hardcodes the absolute path.
  34
  35 On native Windows, DLLs are not fully supported; it is currently only possible
  36 to compile a DLL with MinGW, not with Visual Studio or with Intel compilers.
  37 In this case, the DLLs are placed in the ``bin/`` directory instead of
  38 ``lib/`` (automatically by CMake, based on the generic binary type assignment
  39 in ``CMakeLists.txt``).  Windows automatically searches DLLs from the
  40 executable directory, so the correct DLL should always be found.
  41
  42 For external libraries, standard CMake linking mechanisms are used and RPATH
  43 for the external dependencies is included in the executable; on Windows,
  44 dynamic linking may require extra effort to make the loader locate the correct
  45 external libraries.
  46
  47 To support executing the built binaries from the build tree without
  48 installation (critical for executing tests during development), standard CMake
  49 mechanism is used: when the binaries are built, the RPATH is set to the build
  50 tree, and during installation, the RPATH in the binaries is rewritten by CMake
  51 to the final (relative) value.  As an extra optimization, if the installation
  52 tree has the same relative folder structure as the build tree, the final
  53 relative RPATH is used already during the initial build.
  54
  55 The RPATH settings are in the root ``CMakeLists.txt``.  It is possible to
  56 disable the use of RPATH during installation with standard CMake variables,
  57 such as setting ``CMAKE_SKIP_INSTALL_RPATH=ON``.
  58
  59 Finding data files
  60 ------------------
  61
  62 The other, |Gromacs|-specific part, of making the binaries relocatable is
  63 to make them able to find data files from the installation tree.  Such data
  64 files are used for multiple purposes, including showing the quotes at the end
  65 of program execution.  If the quote database is not found, the quotes are
  66 simply not printed, but other files (mostly used by system preparation tools
  67 like :ref:`gmx pdb2gmx` and :ref:`gmx grompp`, and by various analysis tools
  68 for static data) will cause fatal errors if not found.
  69
  70 There are several considerations here:
  71
  72 * For relocation to work, finding the data files cannot rely on any hard-coded
  73   absolute path, but it must find out the location of the executing code by
  74   inspecting the system.  As a fallback, environment variables or such set by
  75   ``GMXRC`` or similar could be used (but currently are not).
  76 * When running executables from the build tree, it is desirable that they will
  77   automatically use the data files from the matching source tree to facilitate
  78   easy testing.  The data files are not copied into the build tree, and the
  79   user is free to choose any relative locations for the source and build trees.
  80   Also, the data files are not in the same relative path in the source tree and
  81   in the installation tree (the source tree has ``share/top/``, the
  82   installation tree ``share/gromacs/top/``; the latter is customizable during
  83   CMake configuration).
  84 * In addition to |Gromacs| executables, programs that link against
  85   ``libgromacs`` need to be able to find the data files if they call certain
  86   functions in the library.  In this case, the executable may not be in the
  87   same directory where |Gromacs| is.  In case of static linking, no part of the
  88   code is actually loaded from the |Gromacs| installation prefix, which makes
  89   it impossible to find the data files without external information.
  90 * The user can always use the ``GMXLIB`` environment variable to provide
  91   alternative locations for the data files, but ideally this should never be
  92   necessary for using the data files from the installation.
  93
  94 Not all the above considerations are fully addressed by the current
  95 implementation, which works like this:
  96
  97 1. It finds the path to the current executable based on ``argv[0]``.  If the
  98    value contains a directory, this is interpreted as absolute or as relative
  99    to the current working directory.  If there is no directory, then a file by
 100    that name is searched from the directories listed in ``PATH``.  On Windows,
 101    the current directory is also searched before ``PATH``.  If a file with a
 102    matching name is found, this is used without further checking.
 103 2. If the executable is found and is a symbolic link, the symbolic links are
 104    traversed until a real file is found.  Note that links in the directory name
 105    are not resolved, and if some of the links contain relative paths, the end
 106    result may contain ``..`` components and such.
 107 3. If an absolute path to the executable was found, the code checks whether the
 108    executable is located in the build output directory (using ``stat()`` or
 109    similar to account for possible symbolic links in the directory components).
 110    If it is, then the hard-coded source tree location is returned.
 111 4. If an absolute path to the executable was found and it was not in the build
 112    tree, then all parent directories are checked.  If a parent directory
 113    contains :file:`share/{gromacs}/top/gurgle.dat`, this directory is returned
 114    as the installation prefix.  The file name ``gurgle.dat`` and the location
 115    are considered unique enough to ensure that the correct directory has been
 116    found.  The installation directory for the data files can be customized
 117    during CMake configuration by setting ``GMX_DATA_INSTALL_DIR``, which
 118    affects the *gromacs* part in the above path (both in the installation
 119    structure and in this search logic).
 120
 121    Note that this search does not resolve symbolic links or normalize the input
 122    path beforehand: if there are ``..`` components *and* symbolic links in the
 123    path, the search may proceed to unexpected directories, but this should not
 124    be an issue as the correct installation prefix should be found before
 125    encountering such symbolic links (as long as the ``bin/`` directory is not a
 126    symbolic link).
 127 5. If the data files have not been found yet, try a few hard-coded guesses
 128    (like the original installation ``CMAKE_INSTALL_PREFIX`` and
 129    ``/usr/local/``).  The first guess that contains suitable files
 130    (``gurgle.dat``) is returned.
 131 6. If still nothing is found, return ``CMAKE_INSTALL_PREFIX`` and let the
 132    subsequent data file opening fail.
 133
 134 The above logic to find the installation prefix is in
 135 ``src/gromacs/commandline/cmdlineprogramcontext.cpp``.  Note that code that
 136 links to ``libgromacs`` can provide an alternative implementation for
 137 ``gmx::ProgramContextInterface`` for locating the data files, and is then fully
 138 responsible of the above considerations.
 139
 140 Information about the used data directories is printed into the console output
 141 (unless run with ``-quiet``), as well as to (some) error messages when locating
 142 data files, to help diagnosing issues.
 143
 144 There is no mechanism to disable this probing search or affect the process
 145 during compilation time, except for the CMake variables mentioned above.
 146
 147 Known issues
 148 ------------
 149
 150 * ``GMXRC`` is not relocatable: it hardcodes the absolute installation path in
 151   one assignment within the script, which no longer works after relocation.
 152   Contributions to get rid of this on all the shells the ``GMXRC`` currently
 153   supports are welcome.
 154 * There is no version checking in the search for the data files; in case of
 155   issues with the search, it may happen that the installation prefix from some
 156   other installation of |Gromacs| is returned instead, and only cryptic errors
 157   about missing or invalid files may reveal this.
 158 * If the searching for the installation prefix is not successful, hard-coded
 159   absolute guesses are used, and one of those returned.  These guesses include
 160   the absolute path in ``CMAKE_INSTALL_PREFIX`` used during compilation of
 161   ``libgromacs``, which will be incorrect after relocation.
 162 * The search for the installation prefix is based on the locating the
 163   executable.  This does not work for programs that link against
 164   ``libgromacs``, but are not installed in the same prefix.  For such cases,
 165   the hard-coded guesses will be used, so the search will not find the correct
 166   data files after relocation.  The calling code can, however, programmatically
 167   provide the |Gromacs| installation prefix, but ideally this would work
 168   without offloading work to the calling code.
 169 * One option to (partially) solve the two above issues would be to use the
 170   ``GMXDATA`` environment variable set by ``GMXRC`` as the fallback (currently
 171   this environment variable is set, but very rarely used).
 172 * Installed ``pkg-config`` files are not relocatable: they hardcode the
 173   absolute installation path.