docs/doxygen/user/usinglibrary.md

   1 Using \Gromacs as a library {#page_usinglibrary}
   2 ===========================
   3
   4 Getting started
   5 ===============
   6
   7 The \Gromacs library (`libgromacs`) provides a few different alternatives for
   8 using it.  These are listed here from the highest level of abstraction to the
   9 low-level functions.
  10  - If you are writing a trajectory analysis tool, please see
  11    \ref page_analysisframework.  \ref page_analysistemplate should contain
  12    all the ingredients to get started.
  13    If you have an existing tool written using the analysis template from 4.5 or
  14    4.6 (using the selection engine added in 4.5), you need to do some
  15    conversion work to get this work with the new template.  This is mostly
  16    straightforward, but requires some studying to understand the new framework.
  17  - If you are writing a command line tool for some other purpose, you can use
  18    the facilities provided by \ref module_commandline.  There are a few
  19    different alternatives, depending on how much control you want to give
  20    \Gromacs:
  21     - For C++ code, you can implement gmx::CommandLineModuleInterface, and
  22       use gmx::runCommandLineModule() to execute it.  This requires using some
  23       additional \Gromacs classes (in particular, for implementing
  24       gmx::CommandLineModuleInterface::writeHelp(), if you want to support the
  25       `-h` option).
  26     - For C code, you can use gmx_run_cmain() to wrap an existing C main
  27       method.  The only constraint on the provided main method is that it
  28       should use parse_common_args() for argument processing.
  29       This approach should allow you to convert existing C tools written
  30       against pre-5.0 \Gromacs (e.g., using the analysis template from 4.0 or
  31       earlier) to the new version.
  32     - If you want more control (for example, you do not want the default
  33       command line options added by \Gromacs), you can directly initialize
  34       \Gromacs using gmx::initForCommandLine() before calling other \Gromacs
  35       routines.  This allows you to write your own handling for command line
  36       options from scratch.  This is also discussed in \ref module_commandline.
  37  - For most control, you can use gmx::init() to do basic initialization, create
  38    your own implementation for gmx::ProgramContextInterface, and set that using
  39    gmx::setProgramContext().  This allows you to customize how the \Gromacs
  40    library shows the name of the program in messages, as well as how it locates
  41    its own data files.
  42
  43 If these do not fit your needs, you may need to modify the \Gromacs source code
  44 yourself.  In particular, it is currently relatively difficult to extend the
  45 functionality of `mdrun` without modifying the source code directly.
  46 If you think that some particular API would be necessary for your work, and
  47 think that it would be easy to expose, please drop a line on the
  48 `gmx-developers` mailing list, or contribute the necessary changes on
  49 http://gerrit.gromacs.org/.
  50
  51 Linking against `libgromacs`
  52 ============================
  53
  54 \Gromacs is a bit picky on how the headers need to be used: depending on
  55 compilation options used for \Gromacs, some preprocessor defines may need to be
  56 set, the required include path may also depend on compilation options, and some
  57 extra libraries may need to be linked.  You will also likely need to use the
  58 same compiler (or sufficiently similar one that uses the same standard library)
  59 that was used to compile \Gromacs.
  60
  61 To manage this more easily, \Gromacs provides two mechanisms for getting the
  62 correct flags for compilation and linking against the \Gromacs library:
  63  - `pkg-config`: \Gromacs installs `libgromacs.pc` file (suffixed with the
  64    library suffix) for use with `pkg-config` if that is present on the system.
  65    Sourcing `GMXRC` adjusts the `pkg-config` search path such that these files
  66    are found automatically.
  67    See `Makefile.pkg` installed with the analysis template for one example of
  68    how to use it (to use it with a differently suffixed \Gromacs, just replace
  69    `libgromacs` with `libgromacs`<em>_suffix</em> in the `pkg-config` calls).
  70  - CMake package configuration files and a find module that allow
  71    `find_package(GROMACS)` to work.  See below for details about how to use
  72    this in CMake.  Sourcing `GMXRC` sets an environment variable that allows
  73    CMake to find the configuration file automatically.
  74    See `CMakeLists.txt` installed with the analysis template for one example of
  75    how to use it.
  76
  77 These mechanisms are currently provided on a best-effort basis, but are not
  78 routinely tested on a wide range of configurations.  Please report any issues
  79 with details of how \Gromacs was built so that the mechanism can be improved.
  80 Known issues:
  81  - `pkg-config` files are not relocatable, i.e., they hard-code the
  82    installation prefix as an absolute path.
  83  - Installing both static and shared libraries with the same suffix to the same
  84    installation prefix is guaranteed to work only if both are built with
  85    exactly the same configuration options (except for `BUILD_SHARED_LIBS`) from
  86    exactly the same version.  There are several files that are shared between
  87    the installations in such a case, and the latter installation will overwrite
  88    those from the former.
  89  - Further, if both static and shared libraries have been installed in the past
  90    to a prefix, then future installations to the same prefix should also
  91    install both static and shared libraries.  Otherwise, some obsolete CMake
  92    package configuration files will be left behind which can lead to finding
  93    the old library.  Alternatively, you can delete `share/cmake/` from the
  94    installation directory before doing the install.
  95  - If a mechanism other than the CMake-generated `install` target is used to
  96    install \Gromacs over an existing installation, and the build type (e.g.,
  97    Release vs.\ Debug) does not match what was previously installed, some
  98    obsolete CMake import target definition files are left behind in
  99    `share/cmake/`, and may cause failures whey trying to use the package
 100    configuration files.
 101  - If \Gromacs is built with `GMX_BUILD_OWN_FFTW=ON`, the CMake-generated
 102    import definitions for `libgromacs` reference a `gmxfftw` target that was
 103    used in the build to reference the `fftw` library.  As this library only
 104    exists in the \Gromacs build tree, and the CMake machinery does not write
 105    any import definitions for it anywhere, linking will fail with errors about
 106    not being able to find a `gmxfftw` library.  So the CMake package
 107    configuration files can only be used with `GMX_BUILD_OWN_FFTW=OFF`.
 108
 109 CMake `find_package(GROMACS)` details
 110 -------------------------------------
 111
 112 The CMake machinery to support `find_package(GROMACS)` has two parts: a
 113 `FindGROMACS.cmake` find module (found in `share/gromacs/template/cmake/` in
 114 the installation and `share/template/cmake/` in the source tree), and actual
 115 package configuration files (`gromacs-config.cmake` and supporting files
 116 installed to `share/cmake/` from input files in `src/gromacs/`).
 117
 118 `FindGROMACS.cmake` is a simple wrapper over the package configuration files,
 119 providing a somewhat more convenient interface to the machinery that supports
 120 multiple suffixed \Gromacs installations in the same installation prefix (see
 121 `GROMACS_SUFFIX` variable below).  This file is intended to be version-agnostic
 122 and remain both forward- and backward-compatible even between major \Gromacs
 123 releases.  All version-specific information and the actual details about the
 124 compilation and linking settings is in the package configuration files.
 125 Build systems willing to utilize `FindGROMACS.cmake` can create a local copy of
 126 it and use it like it is used in the installed
 127 `share/gromacs/template/CMakeLists.txt`.
 128 The package configuration files can also be used directly if desired, bypassing
 129 `FindGROMACS.cmake`.
 130
 131 Input options for influencing what to find:
 132
 133 <dl>
 134 <dt>`GROMACS_SUFFIX` (only for `FindGROMACS.cmake`)</dt>
 135 <dd>This CMake variable can be set before calling `find_package(GROMACS)` to
 136 specify the \Gromacs suffix to search for.  If not set, an unsuffixed version
 137 is searched for.  If using the package configuration files directly, the suffix
 138 must be set using `find_package(GROMACS NAMES gromacs<suffix>)`.</dd>
 139 <dt>`GROMACS_PREFER_STATIC`</dt>
 140 <dd>This CMake variable can be set before calling `find_package(GROMACS)` to
 141 specify whether static or shared libraries are preferred if both are available.
 142 It does not affect which \Gromacs installation is chosen, but if that
 143 installation has both static and shared libraries available (installed from two
 144 different builds with the same suffix), then this chooses the library to be
 145 returned in `GROMACS_LIBRARIES`.</dd>
 146 <dt>`GROMACS_DIR`</dt>
 147 <dd>This CMake (cache) variable is a standard mechanism provided by
 148 `find_package`, and can be used to specify a hint where to search for \Gromacs.
 149 Also `CMAKE_PREFIX_PATH` can be used for this purpose; see CMake documentation
 150 for `find_package` for more details.
 151 `GROMACS_DIR` can also be set as an environment variable, and this is done by
 152 `GMXRC`.</dd>
 153 </dl>
 154
 155 Output variables that specify how the found `libgromacs` and header should be
 156 used:
 157
 158 <dl>
 159 <dt>`GROMACS_INCLUDE_DIRS`</dt>
 160 <dd>List of include directories necessary to compile against the \Gromacs
 161 headers.  Currently, this includes the path to \Gromacs headers, as well as the
 162 path to Boost headers that were used to compile \Gromacs.</dd>
 163 <dt>`GROMACS_LIBRARIES`</dt>
 164 <dd>List of libraries to link with to link against \Gromacs.
 165 Under the hood, this uses imported CMake targets to represent `libgromacs`.</dd>
 166 <dt>`GROMACS_DEFINITIONS`</dt>
 167 <dd>List of compile definitions (with `-D` in front) that are required to
 168 compile the \Gromacs headers.</dd>
 169 <dt>`GROMACS_IS_DOUBLE`</dt>
 170 <dd>Whether the found \Gromacs was compiled in double precision.</dd>
 171 </dl>
 172
 173 Declared macros/functions that can be used for checking for correctness of some
 174 settings:
 175
 176 <dl>
 177 <dt>`gromacs_check_double(GMX_DOUBLE)`</dt>
 178 <dd>Checks that the found \Gromacs is in the expected precision.
 179 The parameter `GMX_DOUBLE` should be the name of a cache variable that
 180 specified whether double-precision was requested.</dd>
 181 <dt>`gromacs_check_compiler(LANG)`<dt>
 182 <dd>Checks that the found \Gromacs was compiled with the same compiler
 183 that is used by the current CMake system.
 184 Currently only `LANG=CXX` is supported.</dd>
 185 </dl>
 186
 187 Notes on \Gromacs API
 188 =====================
 189
 190 The headers for the public \Gromacs API are installed in `include/gromacs/`
 191 under the installation directory.  The layout reflects the source code layout
 192 under the `src/gromacs/` directory (see \ref page_codelayout).  The headers
 193 directly under `include/gromacs/` do not contain any declarations, but instead
 194 include a collection of headers from subdirectories.
 195 You should prefer to include these convenience headers instead of individual
 196 headers from the subdirectories, since they are much more stable.  The
 197 individual headers in the subdirectories can be renamed or moved, but the goal
 198 is to only rarely change the name of these top-level headers.
 199
 200 Pre-5.0 versions of \Gromacs installed (nearly) all headers directly under
 201 `include/gromacs/`.  Most of these headers still exist, but now under
 202 `include/gromacs/legacyheaders/`.  The long-term goal is to move these to
 203 proper module hierarchy or get rid of them, but unfortunately this can take a
 204 long time.  Thus, you should not expect much stability from the API in these
 205 headers.  Some have already been moved, so if you do not find your favorite
 206 header there, try searching for a declaration from the other subdirectories.
 207
 208 For headers under other subdirectories, some effort has been put to design the
 209 API for stability.  However, with limited development resources, and the focus
 210 of \Gromacs being in high performance simulations, all the APIs are subject to
 211 change without notice.  With each new release (with possible exception of patch
 212 releases), you should expect incompatible API changes.  This is in particular
 213 true until the planned reorganization of the `legacyheaders/` subdirectory is
 214 complete.
 215
 216 The header version.h (installed as `gromacs/version.h`) provides defines that
 217 calling code can use to check the exact (released) version of \Gromacs that
 218 installed the headers.
 219
 220 This Doxygen documentation only covers part of the API.  In particular, nearly
 221 all of `include/gromacs/legacyheaders/` is undocumented, as well as code
 222 recently moved from there.