Infrastructure for making proper releases (#94)

``PROCEDURES.md`` needs work, but that can happen later.

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 " ")

INSTALL.md

@@ -22,18 +22,19 @@ invoked with an additional flag (``-fconcepts``) in order to support this aspect
 C++20 standard. See [this issue](https://github.com/BallisticLA/RandBLAS/issues/90) for more info.
 
 BLAS++ is a C++ API for the Basic Linear Algebra Subroutines.
-It can be installed with GNU make or CMake;
-RandBLAS requires the CMake install of BLAS++. 
+It can be installed with GNU make or CMake.
+If you want to use RandBLAS' CMake build system,
+then it will be necessary to have built and installed BLAS++ via CMake.
 
-Random123 is a collection of counter-based random number generators.
+Random123 is a header-only library of counter-based random number generators.
 
 We give recipes for installing BLAS++ and Random123 below.
 Later on, we'll assume these recipes were executed from a directory
 that contains (or will contain) the ``RandBLAS`` project directory as a subdirectory.
 
 One can compile and install BLAS++ from
 [source](https://bitbucket.org/icl/blaspp/src/master/) using CMake by running the following.
-Note that all CMake-related terms for BLAS++ use the name ``blaspp`` instead of ``BLAS++``.
+Note that all CMake and system terms for BLAS++ use the name ``blaspp`` instead of ``BLAS++``.
 ```shell
 git clone https://github.com/icl-utk-edu/blaspp.git
 mkdir blaspp-build
@@ -74,6 +75,18 @@ for more info.
 
 ## 3. Building and installing RandBLAS
 
+The following CMake variables influence the RandBLAS build.
+
++-------------------------+----------------------------------------------------+
+| CMake Variable          | Description                                        |
++-------------------------+----------------------------------------------------+
+| CMAKE_BUILD_TYPE        | Release or Debug. The default is Release.          |
++-------------------------+----------------------------------------------------+
+| blaspp_DIR              | The path to your local BLAS++ install              |
++-------------------------+----------------------------------------------------+
+| Random123_DIR           | The path to your local random123 install           |
++-------------------------+----------------------------------------------------+
+
 Assuming you used the recipes from Section 1 to get RandBLAS' dependencies,
 you can download, build, and install RandBLAS as follows:
 
@@ -115,7 +128,7 @@ Here are the conceptual meanings of the recipe's other build flags:
 ## 4. Using RandBLAS in other projects
 
 Once RandBLAS has been compiled and installed it can be used like any other CMake project.
-For instance, the following CMakeLists.txt demonstrates how an executable can
+For instance, the following CMake snippet demonstrates how an executable can
 be linked to the RandBLAS library:
 
 ```cmake
@@ -126,7 +139,7 @@ target_link_libraries(myexec RandBLAS ...)
 ```
 In order to build that CMake project you'd need to specify a build flag ``-DRandBLAS_DIR=X``, where ``X`` is a directory that contains ``RandBLAS.cmake``.
 
-The vast majority of projects that use RandBLAS will also use BLAS++ and LAPACK++.
+Most projects that use RandBLAS will also use LAPACK++.
 Here is example CMake code for such a project. Note that it references BLAS++ in the final line (as ``blaspp``),
 but it doesn't have a ``find_package`` command for BLAS++. That's because when CMake is told to find RandBLAS,
 the RandBLAS installation will tell CMake where to find blaspp as a dependency.

PROCEDURES.md

@@ -0,0 +1,33 @@
+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
+
+I think this just requires making a git tag. Tags of the form X.Y.Z should work out of the box.
+Tags with prerelease info (like alpha, beta, etc..) might require reworking the string 
+parsing in RandBLAS/CMake/rb_version.cmake.
+
+This ends up being simpler than CVXPY's method of defining new releases, which requires data
+specified manually in cvxpy/setup/versioning.py, while we infer that data from a tag with the
+help of ``git describe``. 
+
+# Writing release notes
+
+This is self-explanatory.
+
+# Updating web docs
+
+## Updating web doc sources
+
+Appropriately adapt the release notes. Maybe just link to the GitHub releases for now.
+
+## ReadTheDocs deployment
+
+Change the default version of the web docs that people see.
+Maybe have to hard-code the version for a given branch.
+
+# Creating a new release on GitHub
+
+This is self-explanatory.

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

RandBLAS/sparse_data/base.hh

@@ -131,7 +131,7 @@ static inline void sorted_nonzero_locations_to_pointer_array(
 ///     .. code:: c++
 ///
 ///         ~SpMat() {
-///             if (this-own_memory) {
+///             if (this->own_memory) {
 ///                 delete [] this->vals;
 ///                 // ... class-specific code ...
 ///             }

rtd/howwebuiltthis.md → rtd/DevNotes.md

@@ -145,4 +145,5 @@ Note: this file needs to be located in ``rtd/sphinxext``. This is because ``conf
     ///
     /// @endverbatim
     /// The matrix \math{\op(\mat(A))} is \math{m \times n}.
-  ```
+  ```
+

rtd/source/index.rst

@@ -2,8 +2,10 @@
    :hidden:
    :maxdepth: 3
 
+   Installation <installation/index>
    Tutorial <tutorial/index>
    API Reference <api_reference/index>
+   Changelog <updates/index>
 
 .. default-domain:: cpp
 
@@ -21,24 +23,10 @@ All sketches produced by RandBLAS are dense.
 As such, dense data matrices can be sketched with dense or sparse operators, while sparse data matrices can only be sketched with dense operators.
 RandBLAS can be used in distributed environments through its ability to (reproducibly) compute products with *submatrices* of sketching operators.
 
-Learn more by reading our `Tutorial <tutorial/index.html>`_ or our `API Reference <api_reference/index.html>`_.
+Learn more by reading our `tutorial <tutorial/index.html>`_ or our `API reference <api_reference/index.html>`_.
+If we've piqued your interest, try RandBLAS yourself!
+We've got a handy `installation guide <installation/index.html>`_  on this website.
 
-Build and Install
------------------
-RandBLAS is configured with CMake. The following CMake variables influence the build.
-
-+-------------------------+----------------------------------------------------+
-| CMake Variable          | Description                                        |
-+-------------------------+----------------------------------------------------+
-| CMAKE_BUILD_TYPE        | Release or Debug. The default is Release.          |
-+-------------------------+----------------------------------------------------+
-| blaspp_DIR              | The path to your local BLAS++ install              |
-+-------------------------+----------------------------------------------------+
-| Random123_DIR           | The path to your local random123 install           |
-+-------------------------+----------------------------------------------------+
-
-See `INSTALL.md <https://github.com/BallisticLA/RandBLAS/blob/main/INSTALL.md>`_ for the most up-to-date 
-installation instructions.
 
 Source Code
 -----------

rtd/source/installation/index.rst

@@ -0,0 +1,56 @@
+Installation
+============
+
+
+RandBLAS is a header-only C++20 library with two required dependencies. One of these
+dependencies (`Random123 <https://github.com/DEShawResearch/random123>`_) is header-only,
+while the other (`BLAS++ <https://github.com/icl-utk-edu/blaspp>`_) needs to be compiled.
+
+Having a compiled dependency makes setting up RandBLAS a little more complicated than
+setting up other header-only libraries. RandBLAS also has OpenMP and GoogleTest as 
+optional dependencies. Access to OpenMP is essential for RandBLAS to achieve its 
+best possible performance.
+
+RandBLAS is most useful when called from programs that can access LAPACK,
+or an equivalent library for dense matrix computations. However, we don't
+require that such a library is available.
+
+RandBLAS uses `C++20 concepts <https://en.cppreference.com/w/cpp/language/constraints>`_.
+Make sure your compiler supports these!
+
+CMake users
+-----------
+RandBLAS offers a CMake build system.
+This system manages a simple configuration step (populating ``RandBLAS/config.h``),
+connecting to BLAS++ (assuming it was built with CMake), and building unit tests.
+
+You can opt to *install* RandBLAS if you want other CMake projects to 
+include it as a dependency. Formal installation just consists 
+of copying the header files and CMake metadata into a directory of your choosing.
+
+See 
+`INSTALL.md <https://github.com/BallisticLA/RandBLAS/blob/main/INSTALL.md>`_
+for detailed build and installation instructions.
+Check out our `examples <https://github.com/BallisticLA/RandBLAS/tree/main/examples>`_
+for CMake projects that use RandBLAS and `LAPACK++ <https://github.com/icl-utk-edu/lapackpp>`_
+to implement high-level randomized algorithms.
+
+Everyone else
+-------------
+Strictly speaking, we only need three things to use RandBLAS in other projects.
+
+1. ``RandBLAS/config.h``, filled according to the instructions in ``RandBLAS/config.h.in``.
+
+2. The locations of Random123 header files.
+
+3. The locations of the header files and compiled binary for BLAS++ (which will
+   referred to as blaspp when installed on your system).
+
+If you have these things at hand, then compiling a RandBLAS-dependent
+program is just a matter of specifying standard compiler flags. 
+
+We recommend that you take a look at 
+`INSTALL.md <https://github.com/BallisticLA/RandBLAS/blob/main/INSTALL.md>`_.
+even if you aren't using CMake, since it has additional 
+advice about selecting an acceptable compiler or getting RandBLAS
+to see OpenMP.