From 74db11593d2ef24e3a8f6f80197564ed9f700454 Mon Sep 17 00:00:00 2001 From: Riley Murray Date: Wed, 5 Jun 2024 18:34:13 -0400 Subject: [PATCH] Infrastructure for making proper releases (#94) ``PROCEDURES.md`` needs work, but that can happen later. --- CMake/RandBLASConfig.cmake.in | 5 +- CMake/RandBLASConfigVersion.cmake.in | 2 +- CMake/rb_version.cmake | 32 ++++++++---- INSTALL.md | 25 ++++++--- PROCEDURES.md | 33 ++++++++++++ RandBLAS/config.h.in | 48 ++++++++++++++++- RandBLAS/sparse_data/base.hh | 2 +- rtd/{howwebuiltthis.md => DevNotes.md} | 3 +- rtd/source/index.rst | 22 ++------ rtd/source/installation/index.rst | 56 ++++++++++++++++++++ rtd/source/updates/index.rst | 72 ++++++++++++++++++++++++++ 11 files changed, 260 insertions(+), 40 deletions(-) create mode 100644 PROCEDURES.md rename rtd/{howwebuiltthis.md => DevNotes.md} (99%) create mode 100644 rtd/source/installation/index.rst create mode 100644 rtd/source/updates/index.rst diff --git a/CMake/RandBLASConfig.cmake.in b/CMake/RandBLASConfig.cmake.in index 8ecb92cd..37f8d27b 100644 --- a/CMake/RandBLASConfig.cmake.in +++ b/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) diff --git a/CMake/RandBLASConfigVersion.cmake.in b/CMake/RandBLASConfigVersion.cmake.in index f7278861..285a7712 100644 --- a/CMake/RandBLASConfigVersion.cmake.in +++ b/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}") diff --git a/CMake/rb_version.cmake b/CMake/rb_version.cmake index ba9ff64e..26e9e579 100644 --- a/CMake/rb_version.cmake +++ b/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 " ") diff --git a/INSTALL.md b/INSTALL.md index 66d90ac8..4846fe24 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -22,10 +22,11 @@ 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 @@ -33,7 +34,7 @@ that contains (or will contain) the ``RandBLAS`` project directory as a subdirec 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. diff --git a/PROCEDURES.md b/PROCEDURES.md new file mode 100644 index 00000000..346dde32 --- /dev/null +++ b/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. diff --git a/RandBLAS/config.h.in b/RandBLAS/config.h.in index 55e56249..0070edb2 100644 --- a/RandBLAS/config.h.in +++ b/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 diff --git a/RandBLAS/sparse_data/base.hh b/RandBLAS/sparse_data/base.hh index 883f0cc0..22bc6086 100644 --- a/RandBLAS/sparse_data/base.hh +++ b/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 ... /// } diff --git a/rtd/howwebuiltthis.md b/rtd/DevNotes.md similarity index 99% rename from rtd/howwebuiltthis.md rename to rtd/DevNotes.md index ed1e56d7..32854185 100644 --- a/rtd/howwebuiltthis.md +++ b/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}. - ``` \ No newline at end of file + ``` + \ No newline at end of file diff --git a/rtd/source/index.rst b/rtd/source/index.rst index cedcce61..e11921f9 100644 --- a/rtd/source/index.rst +++ b/rtd/source/index.rst @@ -2,8 +2,10 @@ :hidden: :maxdepth: 3 + Installation Tutorial API Reference + Changelog .. 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 `_ or our `API Reference `_. +Learn more by reading our `tutorial `_ or our `API reference `_. +If we've piqued your interest, try RandBLAS yourself! +We've got a handy `installation guide `_ 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 `_ for the most up-to-date -installation instructions. Source Code ----------- diff --git a/rtd/source/installation/index.rst b/rtd/source/installation/index.rst new file mode 100644 index 00000000..736d3111 --- /dev/null +++ b/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 `_) is header-only, +while the other (`BLAS++ `_) 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 `_. +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 `_ +for detailed build and installation instructions. +Check out our `examples `_ +for CMake projects that use RandBLAS and `LAPACK++ `_ +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 `_. +even if you aren't using CMake, since it has additional +advice about selecting an acceptable compiler or getting RandBLAS +to see OpenMP. diff --git a/rtd/source/updates/index.rst b/rtd/source/updates/index.rst new file mode 100644 index 00000000..d8a4667a --- /dev/null +++ b/rtd/source/updates/index.rst @@ -0,0 +1,72 @@ + +Changes to RandBLAS +=================== + +This page details changes made to RandBLAS over time, in reverse chronological order. +We have a tentative policy of providing bugfix support for any release of +RandBLAS upon request, no matter how old. With any luck, RandBLAS will grow enough +in the future that we will change this policy to support a handful of versions +at a time. + +RandBLAS follows `Semantic Versioning `_. + + +RandBLAS 0.2 +------------ + +*Released June 5, 2024.* + +Today marks the first formal release of RandBLAS. We've been working on it for over three years, so +we couldn't possibly describe all of its capabilities in just this changelog. Instead, we'll repurpose some +text that's featured prominently in our documentation at the time of this release. + +A quote from the README, describing the aims of this project: + + RandBLAS supports high-level randomized linear algebra algorithms (like randomized low-rank SVD) that might be implemented in other libraries. + Our goal is for RandBLAS to become a standard like the BLAS, in that hardware vendors might release their own optimized implementations of algorithms which confirm to the RandBLAS API. + +A quote from the website, describing our current capabilities: + + RandBLAS is efficient, flexible, and reliable. + It uses CPU-based OpenMP acceleration to apply its sketching operators to dense or sparse data matrices stored in main memory. + 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. + +There's a *ton* of documentation besides those snippets. In fact, we have three separate categories of documentation! + + 1. Traditional source code comments. + 2. Web documentation (i.e., this entire website) + 3. Developer notes; `one `_ for RandBLAS as a whole, + `another `_ for our sparse matrix functionality, + and `a third `_ for this website. + +Contributors and Acknowledgements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Since this is our first release, many acknowledgements in order. +We'll start with contributors to the RandBLAS codebase as indicated by the +repository commit history. + + Riley Murray, Burlen Loring, Kaiwen He, Maksim Melnichenko, Tianyu Liang, and Vivek Bharadwaj. + +In addition to code contributors, we had the benefit of supervision and input +from the following established principal investigators + + James Demmel, Michael Mahoney, Jack Dongarra, Piotr Luszczek, Mark Gates, and Julien Langou. + +We would also like to thank Weslley da Silva Pereira, who gave valuable feedback at +the earliest stages of this project, and all of the individuals who gave feedback on +our `RandNLA monograph `_. + +The work that lead to this release of RandBLAS was funded by the +U.S. National Science Foundation and the U.S. Department of Energy, and was +conducted at the International Computer Science Institute, +the University of California at Berkeley, the University of Tennessee at Knoxville, +Lawrence Berkeley National Laboratory, and Sandia National Laboratories. + +What happened to RandBLAS 0.1? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +We tagged a commit on the RandBLAS repository with version 0.1.0 almost two years ago. +However, we hadn't maintained version numbers or a dedicated changelog since then. RandBLAS 0.2.0 is +our *first* formal release. We opted not to release under version 0.1.0 since that could +ambiguously refer to anything from the now-very-old 0.1.0 tag up to the present.