cmake/gmxVersionInfo.cmake

   1 #
   2 # This file is part of the GROMACS molecular simulation package.
   3 #
   4 # Copyright (c) 2014,2015, by the GROMACS development team, led by
   5 # Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   6 # and including many others, as listed in the AUTHORS file in the
   7 # top-level source directory and at http://www.gromacs.org.
   8 #
   9 # GROMACS is free software; you can redistribute it and/or
  10 # modify it under the terms of the GNU Lesser General Public License
  11 # as published by the Free Software Foundation; either version 2.1
  12 # of the License, or (at your option) any later version.
  13 #
  14 # GROMACS is distributed in the hope that it will be useful,
  15 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17 # Lesser General Public License for more details.
  18 #
  19 # You should have received a copy of the GNU Lesser General Public
  20 # License along with GROMACS; if not, see
  21 # http://www.gnu.org/licenses, or write to the Free Software Foundation,
  22 # Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  23 #
  24 # If you want to redistribute modifications to GROMACS, please
  25 # consider that scientific software is very special. Version
  26 # control is crucial - bugs must be traceable. We will be happy to
  27 # consider code for inclusion in the official distribution, but
  28 # derived work must not be called official GROMACS. Details are found
  29 # in the README & COPYING files - if they are missing, get the
  30 # official version at http://www.gromacs.org.
  31 #
  32 # To help us fund GROMACS development, we humbly ask that you cite
  33 # the research papers on the package. Check out http://www.gromacs.org.
  34
  35 # Sets version information variables and provides CMake functions for
  36 # generating files based on them
  37 #
  38 # This script provides the following basic version variables that need to be
  39 # maintained manually:
  40 #   GMX_VERSION_MAJOR      Major version number.
  41 #   GMX_VERSION_MINOR      Minor version number.
  42 #   GMX_VERSION_PATCH      Patch version number.
  43 #       Should always be defined: zero for, e.g., 5.0.
  44 #   GMX_VERSION_SUFFIX     String suffix to add to numeric version string.
  45 #       "-dev" is automatically added when not building from a source package,
  46 #       and does not need to be kept here. This mechanism is not quite enough
  47 #       for building a tarball, but setting the CMake cache variable
  48 #       GMX_BUILD_TARBALL=on will suppress the addition of "-dev" to the
  49 #       version string.
  50 #   LIBRARY_SOVERSION_MAJOR so major version for the built libraries.
  51 #       Should be increased for each binary incompatible release. In GROMACS,
  52 #       the typical policy is to increase it at the start of the development
  53 #       cycle for each major/minor version change, but not for patch releases,
  54 #       even if the latter may not always be fully binary compatible.
  55 #   LIBRARY_SOVERSION_MINOR so minor version for the built libraries.
  56 #       Should be increased for each release that changes only the implementation.
  57 #       In GROMACS, the typical policy is to increase it for each patch version
  58 #       change, even if they may not always be fully binary compatible.
  59 #       If it is somehow clear that the ABI implementation has not changed
  60 #       in a patch release, this variable should not increase. Release candidate
  61 #       and beta versions will not increase this number, since nobody should
  62 #       write code against such versions.
  63 #   LIBRARY_VERSION        Full library version.
  64 #   REGRESSIONTEST_BRANCH  For builds not from source packages, name of the
  65 #       regressiontests branch at gerrit.gromacs.org whose HEAD can test this
  66 #       code, *if* this code is recent enough (i.e., contains all changes from
  67 #       the corresponding code branch that affects the regression test
  68 #       results). Even after a release branch is forked for the source
  69 #       repository, the correct regressiontests branch can still be master,
  70 #       because we do not fork it until behaviour needs to change.
  71 #   REGRESSIONTEST_MD5SUM
  72 #       The MD5 checksum of the regressiontest tarball. Only used when building
  73 #       from a source package.
  74 # They are collected into a single section below.
  75 # The following variables are set based on these:
  76 #   GMX_VERSION            String composed from GMX_VERSION_* numeric variables
  77 #       above. Example: 4.6.1, 5.0
  78 #   GMX_VERSION_STRING     String with GMX_VERSION suffixed with the given
  79 #       suffix and possibly "-dev" for builds not from a source package.
  80 #   GMX_VERSION_NUMERIC    Numeric version number (e.g., 40601 for 4.6.1).
  81 #   GMX_API_VERSION        Numeric API version.
  82 #       This is currently set automatically to GMX_VERSION_NUMERIC, but may
  83 #       become manually maintained in the future if there will be releases
  84 #       where the API does not change, but programs/libraries do.
  85 #       In such a case, this should be the first version where the current API
  86 #       appeared.
  87 #   REGRESSIONTEST_VERSION For source packages, version number of the
  88 #       matching regressiontests tarball.  Not used for builds not from source
  89 #       packages.
  90 # The latter two are used to generate gromacs/version.h to allow software
  91 # written against the GROMACS API to provide some #ifdef'ed code to support
  92 # multiple GROMACS versions.
  93 #
  94 # The following variables are defined without manual intervention:
  95 #   SOURCE_IS_SOURCE_DISTRIBUTION  The source tree is from a source tarball.
  96 #   SOURCE_IS_GIT_REPOSITORY       The source tree is a git repository.
  97 # Note that both can be false if the tree has been extracted, e.g., as a
  98 # tarball directly from git.
  99 # Additionally, the following variable is defined:
 100 #   BUILD_IS_INSOURCE              The build is happening in-source.
 101 #
 102 # This script also declares machinery to generate and obtain version
 103 # information from a git repository.  This is enabled by default if the source
 104 # tree is a git, but can be disabled with
 105 #   GMX_GIT_VERSION_INFO           Advanced CMake variable to disable git
 106 #                                  version info generation.
 107 # The main interface to this machinery is the gmx_configure_version_file()
 108 # CMake function.  The signature is
 109 #   gmx_configure_version_file(<input> <output>
 110 #                              [REMOTE_HASH] [SOURCE_FILE]
 111 #                              [TARGET <target>]
 112 #                              [COMMENT <comment>])
 113 #   <input>      Specify the input and output files as for configure_file().
 114 #   <output>     The configuration is done with configure_file(... @ONLY) with
 115 #                the following variables defined (as well as all the
 116 #                GMX_VERSION* variables from above):
 117 #                  GMX_VERSION_STRING_FULL
 118 #                  GMX_VERSION_FULL_HASH
 119 #                  GMX_VERSION_CENTRAL_BASE_HASH
 120 #                The output file is created during build time, so any dependent
 121 #                targets should specify it as a dependency.
 122 #   REMOTE_HASH  Currently, this has no effect, but it signifies that the
 123 #                <input> file is using the CENTRAL_BASE_HASH variable.
 124 #                This variable is much more expensive to initialize than the
 125 #                others, so this allows local changes in this file to only
 126 #                compute that value when required if that becomes necessary.
 127 #   SOURCE_FILE  Signals that <output> will be used as a source file.
 128 #                The function will set properties for the source file
 129 #                appropriately to signify that it is generated.
 130 #   TARGET       By default, this function uses add_custom_command() to
 131 #                generate the output file.  If TARGET is specified, then
 132 #                add_custom_target() is used to create a target with the given
 133 #                name <target> that runs this custom command.  Use this if
 134 #                the same file will be used for multiple downstream targets,
 135 #                or if the explicit target for the file is otherwise
 136 #                necessary.
 137 #   COMMENT      Set a custom comment to be shown when building the rule
 138 #                (see add_custom_command(... COMMENT <comment>)).
 139 # As an alternative to using this script, also the following variables are
 140 # provided (can be useful when generating more complex CMake scripts that do
 141 # build-time tasks):
 142 #   VERSION_INFO_CMAKE_SCRIPT
 143 #       Absolute path to a CMake script that can be included using include()
 144 #       to declare the GMX_VERSION_* variables documented for
 145 #       gmx_configure_version_file().
 146 #   VERSION_INFO_DEPS
 147 #       If a custom command depends on VERSION_INFO_CMAKE_SCRIPT, then it
 148 #       should add ${VERSION_INFO_DEPS} to its DEPENDS list to get the
 149 #       appropriate dependencies.
 150 # TODO: If someone wants to add a custom target that depends on
 151 # VERSION_INFO_CMAKE_SCRIPT, a separate variable may be needed for those
 152 # dependencies.
 153 #
 154 # The version string printed by 'gmx -version' (and also printed in the startup
 155 # header) can provide useful information for, e.g., diagnosing bug reports and
 156 # identifying what exact version the user was using.  The following formats are
 157 # possible (with examples given for a particular version):
 158 #   4.6.1       Plain version number without any suffix signifies a build from
 159 #               a released source tarball.
 160 #   4.6.1-dev   '-dev' suffix signifies all other builds. If there is no other
 161 #               information, either the user built the code outside any git
 162 #               repository, or disabled the version info generation.
 163 #   4.6.1-dev-YYYYMMDD-1234abc
 164 #               The YYYYMMDD part shows the commit date (not author date) of
 165 #               the HEAD commit from which the code was built.  The abbreviated
 166 #               hash is the hash of that commit (the full hash is available in
 167 #               'gmx -version' output).
 168 #               If the HEAD hash is not identified as coming from branches in
 169 #               "authoritative" GROMACS repositories, 'gmx -version' will show
 170 #               the nearest ancestor commit that is identified as such (but see
 171 #               the '-local' and '-unknown' suffixes below).
 172 #   4.6.1-dev-YYYYMMDD-1234abc-dirty
 173 #               As above, but there were local modifications in the source tree
 174 #               when the code was built.
 175 #   4.6.1-dev-YYYYMMDD-1234abc-unknown
 176 #               As above, but there were no remotes in the repository that
 177 #               could be identified as "authoritative" GROMACS repositories.
 178 #               This happens if the code is not cloned from git.gromacs.org
 179 #               or gerrit.gromacs.org.
 180 #   4.6.1-dev-YYYYMMDD-1234abc-local
 181 #               As above, but there were no commits in the recent history of
 182 #               the branch that could be identified as coming from
 183 #               "authoritative" GROMACS repositories.  This should be
 184 #               relatively rare.
 185 #
 186 # Other variables set here are not intended for use outside this file.
 187 # The scripts gmxGenerateVersionInfo.cmake and gmxConfigureVersionInfo.cmake
 188 # are used internally by this machinery, as well as VersionInfo.cmake.cmakein.
 189
 190 #####################################################################
 191 # Basic nature of the source tree
 192
 193 set(SOURCE_IS_GIT_REPOSITORY OFF)
 194 set(SOURCE_IS_SOURCE_DISTRIBUTION OFF)
 195 if (EXISTS "${PROJECT_SOURCE_DIR}/.git")
 196     set(SOURCE_IS_GIT_REPOSITORY ON)
 197 endif()
 198 # This file is excluded from CPack source packages, but part of the repository,
 199 # so it should get included everywhere else.
 200 if (NOT EXISTS "${PROJECT_SOURCE_DIR}/admin/.isreposource")
 201     set(SOURCE_IS_SOURCE_DISTRIBUTION ON)
 202 endif()
 203 set(BUILD_IS_INSOURCE OFF)
 204 if ("${PROJECT_SOURCE_DIR}" STREQUAL "${PROJECT_BINARY_DIR}")
 205     set(BUILD_IS_INSOURCE ON)
 206 endif()
 207
 208 #####################################################################
 209 # Manually maintained version info
 210
 211 # The GROMACS convention is that these are the version number of the next
 212 # release that is going to be made from this branch.
 213 set(GMX_VERSION_MAJOR 5)
 214 set(GMX_VERSION_MINOR 2)
 215 set(GMX_VERSION_PATCH 0)
 216 # The suffix, on the other hand, is used mainly for betas and release
 217 # candidates, where it signifies the most recent such release from
 218 # this branch; it will be empty before the first such release, as well
 219 # as after the final release is out.
 220 set(GMX_VERSION_SUFFIX "")
 221
 222 # Conventionally with libtool, any ABI change must change the major
 223 # version number, the minor version number should change if it's just
 224 # the implementation that has been altered, and the third number
 225 # counts the number of old major versions that will still run if
 226 # linked to this library (i.e. it is not a patch number). See the
 227 # above descriptions of LIBRARY_SOVERSION_* for policy for changes
 228 # here. The important thing is to minimize the chance of third-party
 229 # code being able to dynamically link with a version of libgromacs
 230 # that might not work.
 231 set(LIBRARY_SOVERSION_MAJOR 2)
 232 set(LIBRARY_SOVERSION_MINOR 0)
 233 set(LIBRARY_VERSION ${LIBRARY_SOVERSION_MAJOR}.${LIBRARY_SOVERSION_MINOR}.0)
 234
 235 #####################################################################
 236 # General version management based on manually set numbers
 237
 238 if (GMX_VERSION_PATCH)
 239     set(GMX_VERSION "${GMX_VERSION_MAJOR}.${GMX_VERSION_MINOR}.${GMX_VERSION_PATCH}")
 240 else()
 241     set(GMX_VERSION "${GMX_VERSION_MAJOR}.${GMX_VERSION_MINOR}")
 242 endif()
 243 set(GMX_VERSION_STRING "${GMX_VERSION}${GMX_VERSION_SUFFIX}")
 244 option(GMX_BUILD_TARBALL "Build tarball without -dev version suffix" OFF)
 245 mark_as_advanced(GMX_BUILD_TARBALL)
 246 if (NOT SOURCE_IS_SOURCE_DISTRIBUTION AND NOT GMX_BUILD_TARBALL)
 247     set(GMX_VERSION_STRING "${GMX_VERSION_STRING}-dev")
 248 endif()
 249
 250 set(REGRESSIONTEST_VERSION "${GMX_VERSION_STRING}")
 251 set(REGRESSIONTEST_BRANCH "refs/heads/master")
 252 # TODO Find some way of ensuring that this is bumped appropriately for
 253 # each release. It's hard to test because it is only used for
 254 # REGRESSIONTEST_DOWNLOAD, which doesn't work until that tarball has
 255 # been placed on the server.
 256 set(REGRESSIONTEST_MD5SUM "298db2fa20a6f4b02e758687ebf48ee8" CACHE INTERNAL "MD5 sum of the regressiontests tarball")
 257
 258 math(EXPR GMX_VERSION_NUMERIC
 259      "${GMX_VERSION_MAJOR}*10000 + ${GMX_VERSION_MINOR}*100 + ${GMX_VERSION_PATCH}")
 260 set(GMX_API_VERSION ${GMX_VERSION_NUMERIC})
 261
 262 #####################################################################
 263 # git version info management
 264
 265 # There can be clusters where git and CMake can run on nodes where the other is
 266 # not available, accessing the same source tree.
 267 # Should be unlikely, but doesn't hurt to check.
 268 set(_git_info_default OFF)
 269 if (SOURCE_IS_GIT_REPOSITORY)
 270     find_package(Git)
 271     if (GIT_FOUND)
 272         set(_git_info_default ON)
 273     endif()
 274 endif()
 275 option(GMX_GIT_VERSION_INFO "Generate git version information" ${_git_info_default})
 276 mark_as_advanced(GMX_GIT_VERSION_INFO)
 277 # Detect preconditions for version info generation if it is requested.
 278 if (GMX_GIT_VERSION_INFO)
 279     if (NOT SOURCE_IS_GIT_REPOSITORY)
 280         message(FATAL_ERROR
 281             "Cannot generate git version information from source tree not under git. "
 282             "Set GMX_GIT_VERSION_INFO=OFF to proceed.")
 283     endif()
 284     # We need at least git v1.5.3 be able to parse git's date output.
 285     if (NOT GIT_FOUND OR GIT_VERSION_STRING VERSION_LESS "1.5.3")
 286         message(FATAL_ERROR
 287             "No compatible git version found (>= 1.5.3 required). "
 288             "Won't be able to generate development version information. "
 289             "Set GMX_GIT_VERSION_INFO=OFF to proceed.")
 290     endif()
 291 endif()
 292
 293 include(gmxCustomCommandUtilities)
 294
 295 # The first two are also for use outside this file, encapsulating the details
 296 # of how to use the generated VersionInfo.cmake.
 297 set(VERSION_INFO_CMAKE_FILE   ${PROJECT_BINARY_DIR}/VersionInfo.cmake)
 298 set(VERSION_INFO_DEPS         ${VERSION_INFO_CMAKE_FILE})
 299 # Capture the location of the necessary files in internal variables for use in
 300 # the function below.
 301 set(VERSION_INFO_CMAKEIN_FILE     ${CMAKE_CURRENT_LIST_DIR}/VersionInfo.cmake.cmakein)
 302 set(VERSION_INFO_CONFIGURE_SCRIPT ${CMAKE_CURRENT_LIST_DIR}/gmxConfigureVersionInfo.cmake)
 303
 304 # Rules to create the VersionInfo.cmake file.
 305 # For git info, the sequence is:
 306 #   1. (configure time) VersionInfo.cmake.cmakein -> VersionInfo-partial.cmake.cmakein
 307 #        - Set all variables that are known at configure time.
 308 #   2. (build time)     VersionInfo-partial.cmake.cmakein -> VersionInfo.cmake
 309 #        - Set variables that may change as result of repository state changes
 310 #          (i.e., everything that requires running git).
 311 #        - Runs every time as a git-version-info target, but the output file
 312 #          timestamp only changes if its contents actually change.
 313 #        - Depending on the native build system, this may run once per build
 314 #          or once per each time it is required for step 3.
 315 #   3. (build time)     VersionInfo.cmake -> other files
 316 #        - Set variables in files specified with gmx_configure_version_file()
 317 #          using the values generated in step 2.
 318 #        - Each file runs as a custom command that depends on the previous
 319 #          steps, and runs only if the VersionInfo.cmake file is newer than the
 320 #          output file.
 321 # Without git info, the sequence is:
 322 #  1. (configure time) VersionInfo.cmake.cmakein -> VersionInfo.cmake
 323 #        - Everything is known at configure time, so the output is generated
 324 #          immediately with all variables set (git info will be empty).
 325 #  2. (build time)     VersionInfo.cmake -> other files
 326 #        - As with git info, processes files from gmx_configure_version_file().
 327 #        - These are again custom commands that depend on the output from
 328 #          step 1, so they get regenerated only when the static version info
 329 #          changes.
 330 if (GMX_GIT_VERSION_INFO)
 331     # Configure information known at this time into a partially filled
 332     # version info file.
 333     set(VERSION_INFO_CMAKEIN_FILE_PARTIAL
 334         ${PROJECT_BINARY_DIR}/VersionInfo-partial.cmake.cmakein)
 335     # Leave these to be substituted by the custom target below.
 336     set(GMX_VERSION_STRING_FULL       "\@GMX_VERSION_STRING_FULL\@")
 337     set(GMX_VERSION_FULL_HASH         "\@GMX_VERSION_FULL_HASH\@")
 338     set(GMX_VERSION_CENTRAL_BASE_HASH "\@GMX_VERSION_CENTRAL_BASE_HASH\@")
 339     configure_file(${VERSION_INFO_CMAKEIN_FILE}
 340                    ${VERSION_INFO_CMAKEIN_FILE_PARTIAL}
 341                    @ONLY)
 342     # If generating the version info, create a target that runs on every build
 343     # and does the actual git calls, storing the results into a CMake script.
 344     # This needs to be run at build time to update the version information
 345     # properly when the git hash changes, but the build system does not.
 346     # All targets added by gmx_configure_version_file() use the information
 347     # from this script to get their variables from, removing the need to run
 348     # git multiple times and simplifying reuse for other purposes.
 349     gmx_add_custom_output_target(git-version-info RUN_ALWAYS
 350         OUTPUT ${VERSION_INFO_CMAKE_FILE}
 351         COMMAND ${CMAKE_COMMAND}
 352             -D GIT_EXECUTABLE=${GIT_EXECUTABLE}
 353             -D PROJECT_VERSION=${GMX_VERSION_STRING}
 354             -D PROJECT_SOURCE_DIR=${PROJECT_SOURCE_DIR}
 355             -D VERSION_CMAKEIN=${VERSION_INFO_CMAKEIN_FILE_PARTIAL}
 356             -D VERSION_OUT=${VERSION_INFO_CMAKE_FILE}
 357             -P ${CMAKE_CURRENT_LIST_DIR}/gmxGenerateVersionInfo.cmake
 358         WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
 359         COMMENT "Generating git version information")
 360     list(APPEND VERSION_INFO_DEPS git-version-info)
 361 else()
 362     # If the version info is static, just generate the CMake script with the
 363     # version variables during the CMake run.
 364     set(GMX_VERSION_STRING_FULL       ${GMX_VERSION_STRING})
 365     set(GMX_VERSION_FULL_HASH         "")
 366     set(GMX_VERSION_CENTRAL_BASE_HASH "")
 367     configure_file(${VERSION_INFO_CMAKEIN_FILE} ${VERSION_INFO_CMAKE_FILE})
 368 endif()
 369 unset(GMX_VERSION_STRING_FULL)
 370 unset(GMX_VERSION_FULL_HASH)
 371 unset(GMX_VERSION_CENTRAL_BASE_HASH)
 372
 373 # The main user-visible interface to the machinery.
 374 # See documentation at the top of the script.
 375 function (gmx_configure_version_file INFILE OUTFILE)
 376     include(CMakeParseArguments)
 377     set(_options REMOTE_HASH SOURCE_FILE)
 378     set(_one_value_args COMMENT TARGET)
 379     set(_multi_value_args EXTRA_VARS)
 380     cmake_parse_arguments(
 381         ARG "${_options}" "${_one_value_args}" "${_multi_value_args}" ${ARGN})
 382     if (ARG_UNPARSED_ARGUMENTS)
 383         message(FATAL_ERROR "Unknown arguments: ${ARG_UNPARSED_ARGUMENTS}")
 384     endif()
 385     # Some callers may pass partial paths that do not really make sense,
 386     # so create a default comment that only contains the actual file name.
 387     get_filename_component(_basename ${OUTFILE} NAME)
 388     set(_comment "Generating ${_basename}")
 389     if (ARG_COMMENT)
 390         set(_comment ${ARG_COMMENT})
 391     endif()
 392     # Mimic configure_file()
 393     if (NOT IS_ABSOLUTE ${INFILE})
 394         set(INFILE ${CMAKE_CURRENT_SOURCE_DIR}/${INFILE})
 395     endif()
 396     # Create command-line definitions for the requested variables
 397     set(_extra_var_defines)
 398     foreach(_var ${ARG_EXTRA_VARS})
 399         list(APPEND _extra_var_defines -D "${_var}=${${_var}}")
 400     endforeach()
 401     # The touch command is necessary to ensure that after the target is run,
 402     # the timestamp is newer than in the input files.
 403     add_custom_command(OUTPUT ${OUTFILE}
 404         COMMAND ${CMAKE_COMMAND}
 405             -D VERSION_VARIABLES=${VERSION_INFO_CMAKE_FILE}
 406             -D VERSION_CMAKEIN=${INFILE}
 407             -D VERSION_OUT=${OUTFILE}
 408             ${_extra_var_defines}
 409             -P ${VERSION_INFO_CONFIGURE_SCRIPT}
 410         COMMAND ${CMAKE_COMMAND} -E touch ${OUTFILE}
 411         WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
 412         DEPENDS ${INFILE} ${VERSION_INFO_DEPS} ${VERSION_INFO_CONFIGURE_SCRIPT}
 413         COMMENT "${_comment}"
 414         VERBATIM)
 415     if (ARG_TARGET)
 416         add_custom_target(${ARG_TARGET} DEPENDS ${OUTFILE} VERBATIM)
 417         gmx_set_custom_target_output(${ARG_TARGET} ${OUTFILE})
 418     endif()
 419     if (ARG_SOURCE_FILE)
 420         set_source_files_properties(${OUTFILE} PROPERTIES GENERATED true)
 421     endif()
 422 endfunction()