initial versioning infrastructure commit

CMake/RandBLASConfig.cmake.in

@@ -1,11 +1,12 @@
 include(CMakeFindDependencyMacro)
 list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}")
 
-set(RandBLAS_VERSION "@RandBLAS_VERSION@")
+set(RandBLAS_FULL_VERSION "@RandBLAS_FULL_VERSION@")
 set(RandBLAS_VERSION_MAJOR "@RandBLAS_VERSION_MAJOR@")
 set(RandBLAS_VERSION_MINOR "@RandBLAS_VERSION_MINOR@")
 set(RandBLAS_VERSION_PATCH "@RandBLAS_VERSION_PATCH@")
-set(RandBLAS_VERSION_DEVEL "@RandBLAS_VERSION_DEVEL@")
+set(RandBLAS_COMMITS_SINCE_RELEASE "@RandBLAS_COMMITS_SINCE_RELEASE@")
+set(RandBLAS_COMMIT_HASH "@RandBLAS_COMMIT_HASH@")
 
 # BLAS++
 if (NOT blaspp_DIR)

CMake/RandBLASConfigVersion.cmake.in

@@ -1,4 +1,4 @@
-set(PACKAGE_VERSION "@RandBLAS_VERSION@")
+set(PACKAGE_VERSION "@RandBLAS_FULL_VERSION@")
 
 # Check whether the requested PACKAGE_FIND_VERSION is compatible
 if("${PACKAGE_VERSION}" VERSION_LESS "${PACKAGE_FIND_VERSION}")

CMake/rb_version.cmake

@@ -8,19 +8,29 @@ if(GIT_FOUND)
         ERROR_QUIET)
 endif()
 if(NOT tmp)
-    set(tmp "0.0.0")
+    set(tmp "0.0.0-0-gunknown")
 endif()
-set(RandBLAS_VERSION ${tmp} CACHE STRING "RandBLAS version" FORCE)
+set(RandBLAS_FULL_VERSION ${tmp} CACHE STRING "RandBLAS version" FORCE)
 
-string(REGEX REPLACE "^([0-9]+)\\.([0-9]+)\\.([0-9]+)(.*$)"
-  "\\1" RandBLAS_VERSION_MAJOR ${RandBLAS_VERSION})
+string(REGEX REPLACE "^([0-9]+)\\.([0-9]+)\\.([0-9]+)-(.*$)"
+  "\\1" RandBLAS_VERSION_MAJOR ${RandBLAS_FULL_VERSION})
 
-string(REGEX REPLACE "^([0-9]+)\\.([0-9]+)\\.([0-9]+)(.*$)"
-  "\\2" RandBLAS_VERSION_MINOR ${RandBLAS_VERSION})
+string(REGEX REPLACE "^([0-9]+)\\.([0-9]+)\\.([0-9]+)-(.*$)"
+  "\\2" RandBLAS_VERSION_MINOR ${RandBLAS_FULL_VERSION})
 
-string(REGEX REPLACE "^([0-9]+)\\.([0-9]+)\\.([0-9]+)(.*$)"
-  "\\3" RandBLAS_VERSION_PATCH ${RandBLAS_VERSION})
+string(REGEX REPLACE "^([0-9]+)\\.([0-9]+)\\.([0-9]+)-(.*$)"
+  "\\3" RandBLAS_VERSION_PATCH ${RandBLAS_FULL_VERSION})
 
-message(STATUS "RandBLAS_VERSION_MAJOR=${RandBLAS_VERSION_MAJOR}")
-message(STATUS "RandBLAS_VERSION_MINOR=${RandBLAS_VERSION_MINOR}")
-message(STATUS "RandBLAS_VERSION_PATCH=${RandBLAS_VERSION_PATCH}")
+string(REGEX REPLACE "^([0-9]+)\\.([0-9]+)\\.([0-9]+)-(.*$)"
+  "\\4" RandBLAS_VERSION_CHANGES ${RandBLAS_FULL_VERSION})
+
+string(REGEX REPLACE "^([0-9]+)-g([a-zA-Z0-9]+)" "\\1" RandBLAS_COMMITS_SINCE_RELEASE ${RandBLAS_VERSION_CHANGES})
+string(REGEX REPLACE "^([0-9]+)-g([a-zA-Z0-9]+)" "\\2" RandBLAS_COMMIT_HASH ${RandBLAS_VERSION_CHANGES})
+
+
+message(STATUS " ")
+message(STATUS "RandBLAS version information")
+message(STATUS "  The nominal version number is ${RandBLAS_VERSION_MAJOR}.${RandBLAS_VERSION_MINOR}.${RandBLAS_VERSION_PATCH}.")
+message(STATUS "  The commit hash for the current RandBLAS source code is ${RandBLAS_COMMIT_HASH}.")
+message(STATUS "  There have been ${RandBLAS_COMMITS_SINCE_RELEASE} commits since the nominal version was assigned.")
+message(STATUS " ")

PROCEDURES.md

@@ -0,0 +1,20 @@
+Procedures for making a new RandBLAS release
+============================================
+
+This file provides the procedures for releasing a new version of RandBLAS. The process involves defining a new release in the commit history, changing the default version that CMake reports if it can't detect Git, and deploying updated web documentation.
+
+# Defining a new release
+
+## Incrementing the MINOR version number
+
+## Incrementing the PATCH version number
+
+# Updating web docs
+
+## Updating web doc sources
+
+## ReadTheDocs deployment
+
+
+# Creating a new release on GitHub
+

RandBLAS/config.h.in

@@ -1,11 +1,57 @@
 #ifndef RandBLAS_config_h
 #define RandBLAS_config_h
 
-#define RandBLAS_VERSION "@RandBLAS_VERSION@"
+#define RandBLAS_FULL_VERSION "@RandBLAS_FULL_VERSION@"
 #define RandBLAS_VERSION_MAJOR @RandBLAS_VERSION_MAJOR@
 #define RandBLAS_VERSION_MINOR @RandBLAS_VERSION_MINOR@
 #define RandBLAS_VERSION_PATCH @RandBLAS_VERSION_PATCH@
+#define RandBLAS_COMMITS_SINCE_RELEASE @RandBLAS_COMMITS_SINCE_RELEASE@ 
+#define RandBLAS_COMMIT_HASH "@RandBLAS_COMMIT_HASH@"
+// ^ CMake sets those based on the output of a shell command executed in the RandBLAS git repo.
+//
+//   The specific command is
+//       git describe --tags --match "[0-9]*.[0-9]*.[0-9]*"
+//   That should return a string of the form
+//       [X].[Y].[Z]-[C]-g[H]
+//   The contents of this string are interpreted as follows.
+//       [X] is a nonnegative integer equal to the major version number
+//       [Y] is a nonnegative integer equal to the minor version number
+//       [Z] is a nonnegative integer equal to the patch number
+//       [C] is a nonnegative integer equal to the number of commits since the version number was assigned
+//       [H] is a short-form commit hash, indicating the state of repository's source code.
+//   RandBLAS_FULL_VERSION is the entire string returned by the git command.
+//
+//   If you want to use RandBLAS without using CMake, you need to create config.h manually.
+//   We explain how to do that below. But first
+//
+//      DISCLAIMER: if you're looking at a config.h file actually generated by CMake parsing
+//      this config.h.in file, then the instructions below will mostly look like nonsense.
+//      This is because CMake will have performed string substitution on the original
+//      comments as given in config.h.in.
+//
+//   Start by making a copy of this config.h.in file and giving it the name config.h.
+//   From there, substitute every expression the form @X@ with a value based on the
+//   ``git describe`` command. For example, if ``git describe``returned 0.1.0-456-gcb84abc,
+//   then your config.h file would make the substitutions
+//
+//      @RandBLAS_FULL_VERSION@           -->    0.1.0-456-gcb84abc
+//      @RandBLAS_VERSION_MAJOR@          -->    0
+//      @RandBLAS_VERSION_MINOR@          -->    1
+//      @RandBLAS_VERSION_PATCH@          -->    0
+//      @RandBLAS_COMMITS_SINCE_RELEASE@  -->    456
+//      @RandBLAS_COMMIT_HASH@            -->    cb84abc
+//
 
 #cmakedefine RandBLAS_HAS_OpenMP
+// ^ CMake determines whether or not to #define RandBLAS_HAS_OpenMP
+//
+//   If you don't want to use CMake, then your config.h file should
+//   either delete that line (if you aren't linking to OpenMP) or
+//   it should replace it with
+//
+//       #define RandBLAS_HAS_OpenMP
+//
+//   if you are linking to OpenMP.
+//
 
 #endif