Installing and building for Linux#

This topic discusses how to install hipBLAS on Linux from a package and how to build and install it from the source code. For a list of installation prerequisites, see hipBLAS prerequisites.

Installing prebuilt packages#

You can manually download the prebuilt hipBLAS packages from the ROCm native package manager or by clicking the GitHub releases tab. The versions on GitHub might be more recent. Release notes are available for each release on the releases tab.

To download the prebuilt package, use this command:

sudo apt update && sudo apt install hipblas

Building hipBLAS from source#

When building hipBLAS from source, you can choose to build only the library and its dependencies or include the client and its dependencies.

Building the library and library dependencies#

The root directory of this repository contains the helper Python script rmake.py which lets you build and install hipBLAS with a single command. It accepts several options but has a hard-coded configuration that you can override by invoking cmake directly. However, it’s a great way to get started quickly and serves as an example of how to build and install hipBLAS. A few commands in the script require sudo access, which might prompt you for a password.

The install script determines the build platform by querying hipconfig --platform. This value can be explicitly defined by setting the environment variable HIP_PLATFORM to HIP_PLATFORM=amd or HIP_PLATFORM=nvidia.

Common examples showing how to use rmake.py to build the library dependencies and library are listed in this table.

Command	Description
`python3 rmake.py -h`	Help information.
`python3 rmake.py -d`	Build the library dependencies and library in your local directory. The `-d` flag only has to be used once. For subsequent invocations of `rmake.py`, it is not necessary to rebuild the dependencies.
`python3 rmake.py`	Build the library in your local directory. It is assumed the dependencies have been built.
`python3 rmake.py -i`	Build the library, then build and install the hipBLAS package in `/opt/rocm/hipblas`. You will be prompted for sudo access. This installs it for all users. To restrict hipBLAS to your local directory, do not use the `-i` flag.
`python3 rmake.py -n`	Build the library without the functionality provided by rocSOLVER. The rocSOLVER, rocSPARSE, and rocPRIM dependencies will not be required. This flag has no effect when building with a NVIDIA CUDA backend.

Building the library, client, and all dependencies#

The client contains the executables listed in the table below.

Executable name	Description
hipblas-test	Runs GoogleTest tests to validate the library
hipblas-bench	An executable to benchmark or test individual functions
hipblas-example-*	Various examples showing how to use hipBLAS

Common ways to use rmake.py to build the dependencies, library, and client are listed in this table.

Command	Description
`python3 rmake.py -dc`	Build the library dependencies, client dependencies, library, and client in your local directory. The `-d` flag only has to be used once. For subsequent invocations of `rmake.py`, it is not necessary to rebuild the dependencies.
`python3 rmake.py -c`	Build the library and client in your local directory. It is assumed the dependencies have been built.
`python3 rmake.py -idc`	Build the library dependencies, client dependencies, library, and client, then build and install the hipBLAS package. You will be prompted for sudo access. To install hipBLAS for all users, use the `-i` flag. To restrict hipBLAS to your local directory, do not use the `-i` flag.
`python3 rmake.py -ic`	Build and install the hipBLAS package and build the client. You will be prompted for sudo access. This installs it for all users. To restrict hipBLAS to your local directory, do not use the `-i` flag.

Dependencies for building the library#

Use rmake.py with the -d option to install the dependencies required to build the library. This does not install the hipblas-common, rocBLAS, rocSOLVER, rocSPARSE, and rocPRIM dependencies. When building hipBLAS, it is important to take note of the version dependencies for other libraries. The hipblas-common, rocBLAS, and rocSOLVER versions required to build for an AMD backend are listed in the top-level CMakeLists.txt file. rocSPARSE and rocPRIM are currently dependencies for rocSOLVER. To build these libraries from source, see the rocBLAS, rocSOLVER, rocSPARSE, and rocPRIM documentation.

The minimum version of CMake is currently 3.16.8. See the --cmake_install flag in rmake.py to upgrade automatically.

To use the test and benchmark clients’ host reference functions, you must manually download and install AMD’s ILP64 version of the AOCL libraries version 4.2. The aocl-linux-* packages include AOCL-BLAS (aocl-blis) and AOCL-LAPACK (aocl-libflame). If you download and install the full AOCL packages to the default location, then these reference functions should be found by the clients` CMakeLists.txt file.

Note

If you only use the rmake.py -d dependency script and change the default CMake option LINK_BLIS=ON, you might experience hipblas-test stress test failures due to a 32-bit integer overflow on the host. To resolve this issue, exclude the stress tests using the command line argument --gtest_filter=-*stress*.

Manual build#

This section provides information on how to configure CMake and manually build on all supported platforms.

Build the library using individual commands#

mkdir -p [HIPBLAS_BUILD_DIR]/release
cd [HIPBLAS_BUILD_DIR]/release
# Default install location is in /opt/rocm, define -DCMAKE_INSTALL_PREFIX=<path> to specify other
# Default build config is 'Release', define -DCMAKE_BUILD_TYPE=<config> to specify other
CXX=/opt/rocm/bin/amdclang++ ccmake [HIPBLAS_SOURCE]
make -j$(nproc)
sudo make install # sudo required if installing into system directory such as /opt/rocm

Build the library, tests, benchmarks, and samples using individual commands#

The repository contains source code for clients that serve as samples, tests, and benchmarks. These source code files can be found in the clients subdirectory of the hipBLAS GitHub.

Dependencies (only necessary for hipBLAS clients)#

The hipBLAS samples have no external dependencies, but the unit test and benchmarking applications do. These clients have the following dependencies:

LAPACK: LAPACK itself adds a dependency on a Fortran compiler
GoogleTest

GoogleTest and LAPACK are more difficult to install. Many distributions do not provide a GoogleTest package with pre-compiled libraries, and the LAPACK packages do not have the necessary CMake config files for CMake to link to the library. hipBLAS provides a CMake script that builds these dependencies from source. This is an optional step. Users can provide their own builds of these dependencies and configure CMake to find them by setting the CMAKE_PREFIX_PATH definition. The following steps demonstrate how to build dependencies and install them to the default CMake /usr/local directory.