diff --git a/INSTALL.md b/INSTALL.md index 55aae208..91d81f6a 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,24 +1,30 @@ # Installing and using RandBLAS -Sections 1 through 3 of this file describe how to perform a *basic* installation -of RandBLAS and its dependencies. +This guide has five sections. -Section 4 explains how RandBLAS can be used in other CMake projects. +Sections 1 through 3 describe how to build and install RandBLAS using CMake. -Section 5 gives detailed recommendations on configuring BLAS++ and LAPACK++ -for use with RandBLAS. -Its installation instructions for BLAS++ can be used in place -of the BLAS++ instructions in Section 1. +Section 4 explains how to use RandBLAS in other CMake projects. -*We recommend that you not bother with Section 5 the first time you build RandBLAS.* +Section 5 concludes with extra tips. +If you want a TL;DR version of this guide, refer to one of the following. + * Our GitHub Actions to [workflow files](https://github.com/BallisticLA/RandBLAS/tree/main/.github/workflows). + * The [examples folder](https://github.com/BallisticLA/RandBLAS/tree/main/examples). -## 1. Required Dependencies: BLAS++ and Random123 + +## 1. Required dependencies: a C++20 compatible compiler, BLAS++, and Random123 + +RandBLAS uses C++20 [concepts](https://en.cppreference.com/w/cpp/language/constraints). +Make sure your compiler supports these. Some compilers (like gcc 8.5) might need to be +invoked with an additional flag (``-fconcepts``) in order to support this aspect of the +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. -BLAS++ can be installed with GNU make or CMake; +It can be installed with GNU make or CMake; RandBLAS requires the CMake install of BLAS++. + Random123 is a collection of counter-based random number generators. We give recipes for installing BLAS++ and Random123 below. @@ -26,7 +32,8 @@ 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 +[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++``. ```shell git clone https://github.com/icl-utk-edu/blaspp.git mkdir blaspp-build @@ -49,28 +56,36 @@ make prefix=`pwd`/../random123-install install-include ## 2. Optional dependencies: GTest and OpenMP -GoogleTest is Google’s C++ testing and mocking framework. GTest is an optional -dependency without which RandBLAS regression tests will not be available. GTest +GoogleTest (aka *GTest*) is Google’s C++ testing and mocking framework. It is an optional +dependency, without which RandBLAS regression tests will not be available. It can be installed with your favorite package manager. -OpemMP is an open standard that enables code to be parallelized as it is -compiled. RandBLAS detects the presence of OpenMP automatically and makes use of -it if it's found. +OpenMP is a standard that enables code to be parallelized as it is compiled. +RandBLAS does not strictly require OpenMP, but it needs OpenMP to quickly +sample dense sketching operators and to quickly perform any sparse matrix computations. -## 3. Building and installing RandBLAS +RandBLAS' CMake configuration step should automatically detect if OpenMP is available. +Sometimes the CMake configuration will fail to recognize OpenMP even if it's +on your system. This is especially common with the default system compilers on macOS +(you can execute ``gcc`` or ``g++`` on macOS, but those are just aliased to +limited versions of ``clang`` and ``clang++``). So if you're on macOS then we +recommend you install new versions of clang/clang++ via Homebrew, and call +``` +export CC= +export CXX= +``` -RandBLAS is configured with CMake and built with GNU make. -The configuration and build processes are simple once RandBLAS' dependencies are in place. +## 3. Building and installing RandBLAS Assuming you used the recipes from Section 1 to get RandBLAS' dependencies, -you can build download, build, and install RandBLAS as follows: +you can download, build, and install RandBLAS as follows: ```shell git clone git@github.com:BallisticLA/RandBLAS.git mkdir RandBLAS-build cd RandBLAS-build cmake -DCMAKE_BUILD_TYPE=Release \ - -Dblaspp_DIR=`pwd`/../blaspp-install/lib/blaspp/ \ + -Dblaspp_DIR=`pwd`/../blaspp-install/lib/cmake/blaspp/ \ -DRandom123_DIR=`pwd`/../random123-install/include/ \ -DCMAKE_BINARY_DIR=`pwd` \ -DCMAKE_INSTALL_PREFIX=`pwd`/../RandBLAS-install \ @@ -90,11 +105,6 @@ functions in "random_gen.hh". Here are the conceptual meanings of the recipe's other build flags: * `-Dblaspp_DIR=X` means `X` is the directory containing the file `blasppConfig.cmake`. - - If you follow BLAS++ installation instructions from Section 5 instead of - Section 1, then you'd set ``-Dblaspp_DIR=/opt/mklpp/lib/blaspp``. - Recall that we do not recommend that you follow Section 5 the first time you - build RandBLAS. * `-DRandom123_DIR=Y` means `Y` is the directory containing the Random123 header files. @@ -112,25 +122,32 @@ For instance, the following CMakeLists.txt demonstrates how an executable can be linked to the RandBLAS library: ```cmake -cmake_minimum_required(VERSION 3.0) -project(myexec) - +cmake_minimum_required(VERSION 3.11) find_package(RandBLAS REQUIRED) - add_executable(myexec ...) 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++. -In Section 5 give recommendations on how to configure BLAS++ and LAPACK++. -If you follow those recommendations, then you'd use build flags -``-Dblaspp_DIR=/opt/mklpp/lib/blaspp`` and ``-Dlapackpp_DIR=/opt/mklpp/lib/lapackpp`` -when running CMake for your project. +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. +Note also that LAPACK++ is referenced as ``lapackpp``. +```cmake +cmake_minimum_required(VERSION 3.11) +project(my_randblas_project) +# ^ The project name can be whatever you want. +find_package(RandBLAS REQUIRED) +find_package(lapackpp REQUIRED) -## 5. Tips +set(myproject_cxx_source my_project.cc) +add_executable(my_project ${myproject_cxx_source}) +target_include_directories(myproject PUBLIC ${Random123_DIR}) +target_link_libraries(myproject PUBLIC RandBLAS blaspp lapackpp) +``` -### Pay attention to the BLAS++ configuration +## 5. Tips The performance of RandBLAS depends heavily on how BLAS++ is configured. If performance matters to you then you should inspect the @@ -138,83 +155,8 @@ information that's printed to screen when you run ``cmake`` for the BLAS++ insta Save that information somewhere while you're setting up your RandBLAS development environment. -### Recommended BLAS++ and LAPACK++ configuration - -LAPACK++ is a C++ API for a wide range of possible LAPACK implementations. -While LAPACK++ is not required for RandBLAS, it is required in -RandLAPACK, and so it's prudent to configure BLAS++ and LAPACK++ at the same time. - -We recommend you install BLAS++ and LAPACK++ so they link to Intel MKL -version 2022 or higher. -That version of MKL will come with CMake configuration files. -Those configuration files are extremely useful if -you want to make a project that connects RandBLAS and Intel MKL. -Such a situation might arise if you want to use RandBLAS together with -MKL's sparse linear algebra functionality. - -One of the RandBLAS developers (Riley) has run into trouble -getting BLAS++ to link to MKL as intended. -Here's how Riley configured his BLAS++ and LAPACK++ installations: - -0. Install and configure MKL. You can get MKL [here](https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html?operatingsystem=linux&distributions=webdownload&options=online). - Once you've installed it you need to edit your `.bashrc` file. - Riley's bashrc file was updated to contain the line - ``` - export MAIN_MKL_LIBS="/home/riley/intel/oneapi/mkl/latest/lib/intel64" - export LD_LIBRARY_PATH="${MAIN_MKL_LIBS}:${LD_LIBRARY_PATH}" - export LIBRARY_PATH="${MAIN_MKL_LIBS}:${LIBRARY_PATH}" - ``` - -1. Download BLAS++ source, create a new folder called ``build`` - at the top level of the BLAS++ project directory, and ``cd`` into that - folder. - -2. Run ``export CXX=g++`` so that ``gcc`` is the default compiler for - the current bash session. - -3. Decide a common prefix for where you'll put BLAS++ and LAPACK++ - installation files. We recommend ``/opt/mklpp``. - -4. Run the following CMake command - ``` - cmake -DCMAKE_BUILD_TYPE=Release \ - -DCMAKE_INSTALL_PREFIX=/opt/mklpp \ - -Dblas=mkl \ - -Dblas_int=int64 \ - -Dbuild_tests=OFF .. - ``` - Save the output of that command somewhere. It contains information - on the precise BLAS libraries linked to BLAS++. - -5. Run ``cmake --build .`` - -6. Run ``sudo make install`` - -7. Download LAPACK++ source, create a new folder called ``build`` at the top level - of the LAPACK++ project directory, and ``cd`` into that folder. - -8. Run the following CMake command - ``` - cmake -DCMAKE_BUILD_TYPE=Release \ - -Dblaspp_DIR=/opt/mklpp/lib/blaspp \ - -DCMAKE_INSTALL_PREFIX=/opt/mklpp \ - -DCMAKE_BINARY_DIR=`pwd` \ - -Dbuild_tests=OFF .. - make -j2 install - ``` - -You can then link to BLAS++ and LAPACK++ in other CMake projects -just by including ``find_package(blaspp REQUIRED)`` and ``find_package(lapackpp REQUIRED)`` -in your ``CMakeLists.txt`` file, and then passing build flags -``` --Dblaspp_DIR=/opt/mklpp/lib/blaspp -Dlapackpp_DIR=/opt/mklpp/lib/lapackpp -``` -when running ``cmake``. - -### Installation trouble - -RandBLAS has a GitHub Actions workflow to install it from scratch and run its suite of unit tests. -If you're having trouble installing RandBLAS, you can always refer to [that workflow file](https://github.com/BallisticLA/RandBLAS/tree/main/.github/workflows). -The workflow includes statements which print the working directory -and list the contents of that directory at various points in the installation. -We do that so that it's easier to infer a valid choice of directory structure for building RandBLAS. +[An earlier version](https://github.com/BallisticLA/RandBLAS/blob/9d0a03fa41fd7c126b252002a54c2f2562fae31a/INSTALL.md#5-tips) +of this installation guide had specific recommendations for configuring BLAS++ and LAPACK++ on Intel machines. +Those recommendations may be useful to you if you're having a hard time getting these libraries setup correctly. +We removed those recommendations from this guide, since they encouraged a somewhat bad practice of installing BLAS++ +and LAPACK++ to a system-wide location (under ``/opt/``) instead of a location that's used for one project.