Provide hook for forks of GROMACS to describe themselves

This will help everybody understand which version of GROMACS is being
used because a description ends up in the log file.

Change-Id: I2ddd4def5b2a3768174a6b0ccc284cbc118906a1

diff --git a/cmake/gmxVersionInfo.cmake b/cmake/gmxVersionInfo.cmake
index 5dcffe6707ad6cc4538176a3f3440b213c8da930..f2589703d00a8683687c517d4de336520cad034b 100644 (file)
--- a/cmake/gmxVersionInfo.cmake
+++ b/cmake/gmxVersionInfo.cmake
@@ -225,6 +225,25 @@ else()
     set(GMX_VERSION "${GMX_VERSION_MAJOR}")
 endif()
 set(GMX_VERSION_STRING "${GMX_VERSION}${GMX_VERSION_SUFFIX}")
+
+# If you are making a custom fork of GROMACS, please describe your
+# fork, perhaps with its version number, in the value of
+# GMX_VERSION_STRING_OF_FORK here. This string will appear in the
+# header of log files that mdrun writes. This will help you, your
+# users, your system administrators, your maintainers and the
+# maintainers of GROMACS core understand how to troubleshoot and
+# reproduce potential problems.
+#
+# If you are distributing a patch to GROMACS, then this change would
+# be great as part of your patch. Otherwise for personal use, you can
+# also just set a CMake cache variable.
+set(GMX_VERSION_STRING_OF_FORK "" CACHE INTERNAL
+    "Version string for forks of GROMACS to set to describe themselves")
+mark_as_advanced(GMX_VERSION_STRING_OF_FORK)
+if (GMX_VERSION_STRING_OF_FORK)
+    set(GMX_VERSION_STRING "${GMX_VERSION_STRING}-${GMX_VERSION_STRING_OF_FORK}")
+endif()
+
 option(GMX_BUILD_TARBALL "Build tarball without -dev version suffix" OFF)
 mark_as_advanced(GMX_BUILD_TARBALL)
 # If run with cmake -P, the -dev suffix is managed elsewhere.
@@ -258,8 +277,17 @@ endif()
 # from Zenodo for the manual and source code
 # Has to be done by hand before every final release
 # Use force to override anything given as a cmake command line input
-set(GMX_MANUAL_DOI "" CACHE INTERNAL "reserved doi for GROMACS manual" FORCE)
-set(GMX_SOURCE_DOI "" CACHE INTERNAL "reserved doi for GROMACS source code" FORCE)
+# Actual input depends on the GMX_VERSION_STRING_OF_FORK variable being set or not.
+# If it is set, we always default to an empty string, otherwise to the value set for the release build.
+if (GMX_VERSION_STRING_OF_FORK)
+    set(GMX_MANUAL_DOI_INTERNAL "")
+    set(GMX_SOURCE_DOI_INTERNAL "")
+else()
+    set(GMX_MANUAL_DOI_INTERNAL "") # Set correct doi string here
+    set(GMX_SOURCE_DOI_INTERNAL "") # Set correct doi string here
+endif()
+set(GMX_MANUAL_DOI ${GMX_MANUAL_DOI_INTERNAL} CACHE INTERNAL "reserved doi for GROMACS manual" FORCE)
+set(GMX_SOURCE_DOI ${GMX_SOURCE_DOI_INTERNAL} CACHE INTERNAL "reserved doi for GROMACS source code" FORCE)
 
 #####################################################################
 # git version info management

diff --git a/docs/dev-manual/contribute.rst b/docs/dev-manual/contribute.rst
index 71fdbf501c4da97b09beffed847852031dd0327c..9f8a0f0ab868e12a006769c220de69b1ef685466 100644 (file)
--- a/docs/dev-manual/contribute.rst
+++ b/docs/dev-manual/contribute.rst
@@ -142,8 +142,11 @@ Alternatives
 https://github.com/gromacs/gromacs. You may wish to fork the project
 under your own GitHub account and make your feature available that
 way. This should help you to generate a following of users that would
-help make the case for contributing the feature to the core. This process
-would then still need to follow the remaining criteria outlined here.
+help make the case for contributing the feature to the core. This
+process would then still need to follow the remaining criteria
+outlined here.  If you fork |Gromacs|, please set the CMake variable
+``GMX_VERSION_STRING_OF_FORK`` to an appropriate descriptive string
+- see cmake/gmxVersionInfo.cmake for details.
 
 There is a project underway to develop a stable API for |Gromacs|,
 which promises to be a great tool for permitting innovation while

diff --git a/docs/release-notes/2020/major/miscellaneous.rst b/docs/release-notes/2020/major/miscellaneous.rst
index 638dcedd09d3770a4de1b10c9b936d1ef2e2e03d..12a23aa356e8accdcb6c6e27b9c61ad5c31e08ab 100644 (file)
--- a/docs/release-notes/2020/major/miscellaneous.rst
+++ b/docs/release-notes/2020/major/miscellaneous.rst
@@ -13,3 +13,11 @@ Macros defined in the mdp (with e.g. -DPOSRES) now cause a warning
 in grompp if they are not encountered while parsing the topology file
 
 :issue:`1975`
+
+Introduced CMake variable GMX_VERSION_STRING_OF_FORK
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+To help users and developers understand which version of |Gromacs| is
+being used, anybody providing a forked version of |Gromacs| shall set 
+GMX_VERSION_STRING_OF_FORK in the source code (or if necessary when 
+running CMake). It will then appear in the log file and users will know
+which version and fork of the code produced the result.