2 # This file is part of the GROMACS molecular simulation package.
4 # Copyright (c) 2014,2015,2016,2017,2018, 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.
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.
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.
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.
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.
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.
35 # Sets version information variables and provides CMake functions for
36 # generating files based on them
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_PATCH Patch version number.
42 # Should always be defined: zero for, e.g., 2016.
43 # GMX_VERSION_SUFFIX String suffix to add to numeric version string.
44 # "-dev" is automatically added when not building from a source package,
45 # and does not need to be kept here. This mechanism is not quite enough
46 # for building a tarball, but setting the CMake cache variable
47 # GMX_BUILD_TARBALL=on will suppress the addition of "-dev" to the
49 # LIBRARY_SOVERSION_MAJOR so major version for the built libraries.
50 # Should be increased for each binary incompatible release. In GROMACS,
51 # the typical policy is to increase it at the start of the development
52 # cycle for each major/minor version change, but not for patch releases,
53 # even if the latter may not always be fully binary compatible.
54 # Table of historical values
60 # LIBRARY_SOVERSION_MINOR so minor version for the built libraries.
61 # Should be increased for each release that changes only the implementation.
62 # In GROMACS, the typical policy is to increase it for each patch version
63 # change, even if they may not always be fully binary compatible.
64 # If it is somehow clear that the ABI implementation has not changed
65 # in a patch release, this variable should not increase. Release candidate
66 # and beta versions will not increase this number, since nobody should
67 # write code against such versions.
68 # LIBRARY_VERSION Full library version.
69 # REGRESSIONTEST_BRANCH For builds not from source packages, name of the
70 # regressiontests branch at gerrit.gromacs.org whose HEAD can test this
71 # code, *if* this code is recent enough (i.e., contains all changes from
72 # the corresponding code branch that affects the regression test
73 # results). Even after a release branch is forked for the source
74 # repository, the correct regressiontests branch can still be master,
75 # because we do not fork it until behaviour needs to change.
76 # REGRESSIONTEST_MD5SUM
77 # The MD5 checksum of the regressiontest tarball. Only used when building
78 # from a source package.
79 # They are collected into a single section below.
80 # The following variables are set based on these:
81 # GMX_VERSION String composed from GMX_VERSION_* numeric variables
82 # above. Example: 4.6.1, 5.0, 2016
83 # GMX_VERSION_STRING String with GMX_VERSION suffixed with the given
84 # suffix and possibly "-dev" for builds not from a source package.
85 # GMX_VERSION_NUMERIC Numeric version number (e.g., 40601 for 4.6.1, 20160001 for 2016.1).
86 # GMX_API_VERSION Numeric API version.
87 # This is currently set automatically to GMX_VERSION_NUMERIC, but may
88 # become manually maintained in the future if there will be releases
89 # where the API does not change, but programs/libraries do.
90 # In such a case, this should be the first version where the current API
92 # REGRESSIONTEST_VERSION For source packages, version number of the
93 # matching regressiontests tarball. Not used for builds not from source
95 # The latter two are used to generate gromacs/version.h to allow software
96 # written against the GROMACS API to provide some #ifdef'ed code to support
97 # multiple GROMACS versions.
99 # This script also declares machinery to generate and obtain version
100 # information from a git repository. This is enabled by default if the source
101 # tree is a git, but can be disabled with
102 # GMX_GIT_VERSION_INFO Advanced CMake variable to disable git
103 # version info generation.
104 # The main interface to this machinery is the gmx_configure_version_file()
105 # CMake function. The signature is
106 # gmx_configure_version_file(<input> <output>
109 # [COMMENT <comment>])
110 # <input> Specify the input and output files as for configure_file().
111 # <output> The configuration is done with configure_file(... @ONLY) with
112 # the following variables defined (as well as all the
113 # GMX_VERSION* variables from above):
114 # GMX_VERSION_STRING_FULL
115 # GMX_VERSION_FULL_HASH
116 # GMX_VERSION_CENTRAL_BASE_HASH
117 # The output file is created during build time, so any dependent
118 # targets should specify it as a dependency.
119 # REMOTE_HASH Currently, this has no effect, but it signifies that the
120 # <input> file is using the CENTRAL_BASE_HASH variable.
121 # This variable is much more expensive to initialize than the
122 # others, so this allows local changes in this file to only
123 # compute that value when required if that becomes necessary.
124 # TARGET By default, this function uses add_custom_command() to
125 # generate the output file. If TARGET is specified, then
126 # add_custom_target() is used to create a target with the given
127 # name <target> that runs this custom command. Use this if
128 # the same file will be used for multiple downstream targets,
129 # or if the explicit target for the file is otherwise
131 # COMMENT Set a custom comment to be shown when building the rule
132 # (see add_custom_command(... COMMENT <comment>)).
133 # As an alternative to using this script, also the following variables are
134 # provided (can be useful when generating more complex CMake scripts that do
136 # VERSION_INFO_CMAKE_SCRIPT
137 # Absolute path to a CMake script that can be included using include()
138 # to declare the GMX_VERSION_* variables documented for
139 # gmx_configure_version_file().
141 # If a custom command depends on VERSION_INFO_CMAKE_SCRIPT, then it
142 # should add ${VERSION_INFO_DEPS} to its DEPENDS list to get the
143 # appropriate dependencies.
144 # TODO: If someone wants to add a custom target that depends on
145 # VERSION_INFO_CMAKE_SCRIPT, a separate variable may be needed for those
148 # The version string printed by 'gmx -version' (and also printed in the startup
149 # header) can provide useful information for, e.g., diagnosing bug reports and
150 # identifying what exact version the user was using. The following formats are
151 # possible (with examples given for a particular version):
152 # 2018.1 Plain version number without any suffix signifies a build from
153 # a released source tarball.
154 # 2018.1-dev '-dev' suffix signifies all other builds. If there is no other
155 # information, either the user built the code outside any git
156 # repository, or disabled the version info generation.
157 # 2018.1-dev-YYYYMMDD-1234abc
158 # The YYYYMMDD part shows the commit date (not author date) of
159 # the HEAD commit from which the code was built. The abbreviated
160 # hash is the hash of that commit (the full hash is available in
161 # 'gmx -version' output).
162 # If the HEAD hash is not identified as coming from branches in
163 # "authoritative" GROMACS repositories, 'gmx -version' will show
164 # the nearest ancestor commit that is identified as such (but see
165 # the '-local' and '-unknown' suffixes below).
166 # 2018.1-dev-YYYYMMDD-1234abc-dirty
167 # As above, but there were local modifications in the source tree
168 # when the code was built.
169 # 2018.1-dev-YYYYMMDD-1234abc-unknown
170 # As above, but there were no remotes in the repository that
171 # could be identified as "authoritative" GROMACS repositories.
172 # This happens if the code is not cloned from git.gromacs.org
173 # or gerrit.gromacs.org.
174 # 2018.1-dev-YYYYMMDD-1234abc-local
175 # As above, but there were no commits in the recent history of
176 # the branch that could be identified as coming from
177 # "authoritative" GROMACS repositories. This should be
180 # Other variables set here are not intended for use outside this file.
181 # The scripts gmxGenerateVersionInfo.cmake and gmxConfigureVersionInfo.cmake
182 # are used internally by this machinery, as well as VersionInfo.cmake.cmakein.
184 #####################################################################
185 # Manually maintained version info
187 # The GROMACS convention is that these are the version number of the next
188 # release that is going to be made from this branch.
189 set(GMX_VERSION_MAJOR 2019)
190 set(GMX_VERSION_PATCH 0)
191 # The suffix, on the other hand, is used mainly for betas and release
192 # candidates, where it signifies the most recent such release from
193 # this branch; it will be empty before the first such release, as well
194 # as after the final release is out.
195 set(GMX_VERSION_SUFFIX "")
197 # Conventionally with libtool, any ABI change must change the major
198 # version number, the minor version number should change if it's just
199 # the implementation that has been altered, and the third number
200 # counts the number of old major versions that will still run if
201 # linked to this library (i.e. it is not a patch number). See the
202 # above descriptions of LIBRARY_SOVERSION_* for policy for changes
203 # here. The important thing is to minimize the chance of third-party
204 # code being able to dynamically link with a version of libgromacs
205 # that might not work.
206 set(LIBRARY_SOVERSION_MAJOR 4)
207 set(LIBRARY_SOVERSION_MINOR 0)
208 set(LIBRARY_VERSION ${LIBRARY_SOVERSION_MAJOR}.${LIBRARY_SOVERSION_MINOR}.0)
210 #####################################################################
211 # General version management based on manually set numbers
213 if (GMX_VERSION_PATCH)
214 set(GMX_VERSION "${GMX_VERSION_MAJOR}.${GMX_VERSION_PATCH}")
216 set(GMX_VERSION "${GMX_VERSION_MAJOR}")
218 set(GMX_VERSION_STRING "${GMX_VERSION}${GMX_VERSION_SUFFIX}")
219 option(GMX_BUILD_TARBALL "Build tarball without -dev version suffix" OFF)
220 mark_as_advanced(GMX_BUILD_TARBALL)
221 # If run with cmake -P, the -dev suffix is managed elsewhere.
222 if (NOT SOURCE_IS_SOURCE_DISTRIBUTION AND
223 NOT GMX_BUILD_TARBALL AND
224 NOT CMAKE_SCRIPT_MODE_FILE)
225 set(GMX_VERSION_STRING "${GMX_VERSION_STRING}-dev")
228 set(REGRESSIONTEST_VERSION "${GMX_VERSION_STRING}")
229 set(REGRESSIONTEST_BRANCH "refs/heads/release-2018")
230 # Run the regressiontests packaging job with the correct pakage
231 # version string, and the release box checked, in order to have it
232 # build the regressiontests tarball with all the right naming. The
233 # naming affects the md5sum that has to go here, and if it isn't right
234 # release workflow will report a failure.
235 set(REGRESSIONTEST_MD5SUM "368aabf0eb4e6fbc9abb7961475f66de" CACHE INTERNAL "MD5 sum of the regressiontests tarball for this GROMACS version")
237 math(EXPR GMX_VERSION_NUMERIC
238 "${GMX_VERSION_MAJOR}*10000 + ${GMX_VERSION_PATCH}")
239 set(GMX_API_VERSION ${GMX_VERSION_NUMERIC})
241 # If run with cmake -P from releng scripts, print out necessary version info
243 if (CMAKE_SCRIPT_MODE_FILE)
244 message("{ \"version\": \"${GMX_VERSION_STRING}\", \"regressiontest-md5sum\": \"${REGRESSIONTEST_MD5SUM}\" }")
248 #####################################################################
249 # git version info management
251 # There can be clusters where git and CMake can run on nodes where the other is
252 # not available, accessing the same source tree.
253 # Should be unlikely, but doesn't hurt to check.
254 set(_git_info_default OFF)
255 if (SOURCE_IS_GIT_REPOSITORY)
258 set(_git_info_default ON)
261 option(GMX_GIT_VERSION_INFO "Generate git version information" ${_git_info_default})
262 mark_as_advanced(GMX_GIT_VERSION_INFO)
263 # Detect preconditions for version info generation if it is requested.
264 if (GMX_GIT_VERSION_INFO)
265 if (NOT SOURCE_IS_GIT_REPOSITORY)
267 "Cannot generate git version information from source tree not under git. "
268 "Set GMX_GIT_VERSION_INFO=OFF to proceed.")
270 # We need at least git v1.5.3 be able to parse git's date output.
271 if (NOT GIT_FOUND OR GIT_VERSION_STRING VERSION_LESS "1.5.3")
273 "No compatible git version found (>= 1.5.3 required). "
274 "Won't be able to generate development version information. "
275 "Set GMX_GIT_VERSION_INFO=OFF to proceed.")
279 include(gmxCustomCommandUtilities)
281 # The first two are also for use outside this file, encapsulating the details
282 # of how to use the generated VersionInfo.cmake.
283 set(VERSION_INFO_CMAKE_FILE ${PROJECT_BINARY_DIR}/VersionInfo.cmake)
284 set(VERSION_INFO_DEPS ${VERSION_INFO_CMAKE_FILE})
285 # Capture the location of the necessary files in internal variables for use in
286 # the function below.
287 set(VERSION_INFO_CMAKEIN_FILE ${CMAKE_CURRENT_LIST_DIR}/VersionInfo.cmake.cmakein)
288 set(VERSION_INFO_CONFIGURE_SCRIPT ${CMAKE_CURRENT_LIST_DIR}/gmxConfigureVersionInfo.cmake)
290 # Rules to create the VersionInfo.cmake file.
291 # For git info, the sequence is:
292 # 1. (configure time) VersionInfo.cmake.cmakein -> VersionInfo-partial.cmake.cmakein
293 # - Set all variables that are known at configure time.
294 # 2. (build time) VersionInfo-partial.cmake.cmakein -> VersionInfo.cmake
295 # - Set variables that may change as result of repository state changes
296 # (i.e., everything that requires running git).
297 # - Runs every time as a git-version-info target, but the output file
298 # timestamp only changes if its contents actually change.
299 # - Depending on the native build system, this may run once per build
300 # or once per each time it is required for step 3.
301 # 3. (build time) VersionInfo.cmake -> other files
302 # - Set variables in files specified with gmx_configure_version_file()
303 # using the values generated in step 2.
304 # - Each file runs as a custom command that depends on the previous
305 # steps, and runs only if the VersionInfo.cmake file is newer than the
307 # Without git info, the sequence is:
308 # 1. (configure time) VersionInfo.cmake.cmakein -> VersionInfo.cmake
309 # - Everything is known at configure time, so the output is generated
310 # immediately with all variables set (git info will be empty).
311 # 2. (build time) VersionInfo.cmake -> other files
312 # - As with git info, processes files from gmx_configure_version_file().
313 # - These are again custom commands that depend on the output from
314 # step 1, so they get regenerated only when the static version info
316 if (GMX_GIT_VERSION_INFO)
317 # Configure information known at this time into a partially filled
319 set(VERSION_INFO_CMAKEIN_FILE_PARTIAL
320 ${PROJECT_BINARY_DIR}/VersionInfo-partial.cmake.cmakein)
321 # Leave these to be substituted by the custom target below.
322 set(GMX_VERSION_STRING_FULL "\@GMX_VERSION_STRING_FULL\@")
323 set(GMX_VERSION_FULL_HASH "\@GMX_VERSION_FULL_HASH\@")
324 set(GMX_VERSION_CENTRAL_BASE_HASH "\@GMX_VERSION_CENTRAL_BASE_HASH\@")
325 configure_file(${VERSION_INFO_CMAKEIN_FILE}
326 ${VERSION_INFO_CMAKEIN_FILE_PARTIAL}
328 # If generating the version info, create a target that runs on every build
329 # and does the actual git calls, storing the results into a CMake script.
330 # This needs to be run at build time to update the version information
331 # properly when the git hash changes, but the build system does not.
332 # All targets added by gmx_configure_version_file() use the information
333 # from this script to get their variables from, removing the need to run
334 # git multiple times and simplifying reuse for other purposes.
335 gmx_add_custom_output_target(git-version-info RUN_ALWAYS
336 OUTPUT ${VERSION_INFO_CMAKE_FILE}
337 COMMAND ${CMAKE_COMMAND}
338 -D GIT_EXECUTABLE=${GIT_EXECUTABLE}
339 -D PROJECT_VERSION=${GMX_VERSION_STRING}
340 -D PROJECT_SOURCE_DIR=${PROJECT_SOURCE_DIR}
341 -D VERSION_CMAKEIN=${VERSION_INFO_CMAKEIN_FILE_PARTIAL}
342 -D VERSION_OUT=${VERSION_INFO_CMAKE_FILE}
343 -P ${CMAKE_CURRENT_LIST_DIR}/gmxGenerateVersionInfo.cmake
344 WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
345 COMMENT "Generating git version information")
346 list(APPEND VERSION_INFO_DEPS git-version-info)
348 # If the version info is static, just generate the CMake script with the
349 # version variables during the CMake run.
350 set(GMX_VERSION_STRING_FULL ${GMX_VERSION_STRING})
351 set(GMX_VERSION_FULL_HASH "")
352 set(GMX_VERSION_CENTRAL_BASE_HASH "")
353 configure_file(${VERSION_INFO_CMAKEIN_FILE} ${VERSION_INFO_CMAKE_FILE})
355 unset(GMX_VERSION_STRING_FULL)
356 unset(GMX_VERSION_FULL_HASH)
357 unset(GMX_VERSION_CENTRAL_BASE_HASH)
359 # The main user-visible interface to the machinery.
360 # See documentation at the top of the script.
361 function (gmx_configure_version_file INFILE OUTFILE)
362 include(CMakeParseArguments)
363 set(_options REMOTE_HASH)
364 set(_one_value_args COMMENT TARGET)
365 set(_multi_value_args EXTRA_VARS)
366 cmake_parse_arguments(
367 ARG "${_options}" "${_one_value_args}" "${_multi_value_args}" ${ARGN})
368 if (ARG_UNPARSED_ARGUMENTS)
369 message(FATAL_ERROR "Unknown arguments: ${ARG_UNPARSED_ARGUMENTS}")
371 # Some callers may pass partial paths that do not really make sense,
372 # so create a default comment that only contains the actual file name.
373 get_filename_component(_basename ${OUTFILE} NAME)
374 set(_comment "Generating ${_basename}")
376 set(_comment ${ARG_COMMENT})
378 # Mimic configure_file()
379 if (NOT IS_ABSOLUTE ${INFILE})
380 set(INFILE ${CMAKE_CURRENT_SOURCE_DIR}/${INFILE})
382 # Create command-line definitions for the requested variables
383 set(_extra_var_defines)
384 foreach(_var ${ARG_EXTRA_VARS})
385 list(APPEND _extra_var_defines -D "${_var}=${${_var}}")
387 # The touch command is necessary to ensure that after the target is run,
388 # the timestamp is newer than in the input files.
389 add_custom_command(OUTPUT ${OUTFILE}
390 COMMAND ${CMAKE_COMMAND}
391 -D VERSION_VARIABLES=${VERSION_INFO_CMAKE_FILE}
392 -D VERSION_CMAKEIN=${INFILE}
393 -D VERSION_OUT=${OUTFILE}
394 ${_extra_var_defines}
395 -P ${VERSION_INFO_CONFIGURE_SCRIPT}
396 COMMAND ${CMAKE_COMMAND} -E touch ${OUTFILE}
397 WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
398 DEPENDS ${INFILE} ${VERSION_INFO_DEPS} ${VERSION_INFO_CONFIGURE_SCRIPT}
399 COMMENT "${_comment}"
402 add_custom_target(${ARG_TARGET} DEPENDS ${OUTFILE} VERBATIM)
403 gmx_set_custom_target_output(${ARG_TARGET} ${OUTFILE})