Provide correct and accurate Trilinos version info during development to help address changes in backward compatibility

Created by: bartlettroscoe

CC: @trilinos/framework, @fryeguy52

Description

The current setup of Trilinos is that it contains a static version-controlled Version.cmake file with static version information:

SET(Trilinos_VERSION 12.13)
SET(Trilinos_MAJOR_VERSION 12)
SET(Trilinos_MAJOR_MINOR_VERSION 121300)
SET(Trilinos_VERSION_STRING "12.13 (Dev)")
SET(Trilinos_ENABLE_DEVELOPMENT_MODE_DEFAULT ON) # Change to 'OFF' for a release

This info is used to configure the Trilinos_version.h file in the build directory that is installed with the contents:

#define TRILINOS_MAJOR_VERSION 12
#define TRILINOS_MAJOR_MINOR_VERSION 121300
#define TRILINOS_VERSION_STRING "12.13 (Dev)"

The even/odd minor version number (13 currently) does tell the user if one is looking at an (odd-numbere) development version or an (even-numbered) release version but it does not give enough info for codes that use almost continuous integration with Trilinos (e.g. ASC Sierra, ATDM APPs, etc.). For example, Trilinos breaks backward compatibility from time to time which causes downstream customer codes to fail to build or pass all of the tests. In a staged integration processes for customer APPs like ATDM SPARC (see TRIL-243 and TRIL-256), the SPARC 'master' code needs to be able to build and pass tests against both their older accepted version of Trilinos and a newer Trilinos version on the 'develop' (or 'master') branch. To accomplish this, when Trilinos 'develop' breaks backward compatibility, APP customer codes need to add ifdefs and other conditional logic to know what version of Trilinos they are pointing to. In particular, they need to know if they are pointing a version of Trilinos before or after a particular version that breaks backward compatibility. For example, they need to be able to write ifdefs like:

# if <current-trilinos-version> >= <known-version-that-breaks-x>
  # This is a newer version of Trilinos and we need to adjust for that change
  ...
#else
  # This is an older version of Trilinos were our current code works just fine
  ...
#endif

A Trilinos installation needs to be able to advertise its exact development version both at configure-time and at compile-time to enable logic like above.

Whatever solution is provided, it must be able to determine in simple C/C++ processor logic if a version of Trilinos is greater or less than some known version where a break in backward compatibility or a new feature is added. It must work from direct builds of Trilinos and installations of Trilinos as well as from builds and installations created from source tarballs of Trilinos.

NOTE: Comparing git SHA1s is not an option because one must have access to the git repo in order compare versions with < or > comparisons and an installation of Trilinos does not have a full git repo.

Proposed Solution

One way to provide the desired version info is to add the macro define:

#define TRILINOS_VERSION_DATE YYYYMMDDhh

which gives a monotonically increasing 10-digit integer for the version of Trilinos in terms of the 4-digit year (YYYY), 2-digit month (MM), 2-digit day (DD) and 2-digit hour (hh) that is taken from the git commit date (in UTC).

This 10-digit integer would fit in a 32-bit integer with a max signed value of 2^32/2 - 1 = 2147483647. Therefore, this could represent the Trilinos version every hour till the end of the year 2147 (or 128 years from now) with the last hour being 2147 12 31 23 = 2147123123. (Surely 64-bit integers will be handled in all C++ compilers in the year 2148).

This macro could be defined in a new file Trilinos_version_date.h that would not be included by any Trilinos code or tests (so as to not trigger any rebuilding of any Trilinos libraries or exectuables). This file would only get included by client source files that needs to know the exact fine-grained Trilinos version.

This date would be generated automatically from the git commit date of first-parent commits on the Trilinos 'develop' branch which gives a monotonically increasing date/time stamp. For example, the commit:

commit 930294d48f4661013265448c1f254a667c66bf0f
Merge: 6354c01 87054d8
Author: trilinos-autotester <trilinos-autotester@trilinos.org>
Date:   Fri Mar 1 19:34:15 2019 -0700

    Merge Pull Request #4530 from rppawlo/Trilinos/nox-remove-deprecated-code
    
    Automatically Merged using Trilinos Pull Request AutoTester
    PR Title: NOX: remove deprecated code
    PR Author: rppawlo

has the commit date in UTC:

$ env TZ=GMT git log --format="%cd" --date=iso-local -1 930294d
2019-03-02 02:34:15 +0000

This date returned from this git command 2019-03-02 02:34:15 could be read in and set the date/time integer:

#define TRILINOS_VERSION_DATE 201903020234

A 32-bit integer in the C/C++ processor will be able to handle date/time integers of this format and correctly do integer comparisons with them.

To accomplish this, one could configure the file Version.cmake into the build directory from the template Trilinos/cmake/Version.cmake.in and then put that Version.cmake file in the install directory, put it into the source tarball, and also install it into the installation directory from the source tarball. (This would be exactly how this is done for the <Project>RepoVersion.txt file, see here.) Then Trilinos_version_date.h would be generated from TRILINOS_VERSION_DATE in the generated Version.cmake file.