Installing rocSOLVER on Linux

Installing rocSOLVER on Linux#

Prerequisites#

rocSOLVER requires a ROCm-enabled platform. For more information, see the ROCm install guide.

rocSOLVER also requires a compatible versions of rocBLAS installed on the system and may require rocSPARSE depending on the build options. For more information, see the rocBLAS install guide and rocSPARSE install guide.

rocBLAS, rocSPARSE, and rocSOLVER are still under active development, and it is hard to define minimal compatibility versions. For now, a good rule of thumb is to always use rocSOLVER together with the matching rocBLAS and rocSPARSE version. For example, if you want to install rocSOLVER from the ROCm 5.6 release, then be sure that the ROCm 5.6 versions of rocBLAS and rocSPARSE are also installed. If you are building the rocSOLVER branch tip, then you will need to build and install the rocBLAS and rocSPARSE branch tips as well.

Installing from pre-built packages#

If you have added the ROCm repositories to your Linux distribution, the latest release version of rocSOLVER can be installed using a package manager. On Ubuntu, for example, use the commands:

sudo apt-get update
sudo apt-get install rocsolver

Building and installing from source#

The rocSOLVER source code is hosted on GitHub. Download the code and checkout the desired branch using:

git clone -b <desired_branch_name> https://github.com/ROCmSoftwarePlatform/rocSOLVER.git
cd rocSOLVER

To build from source, some external dependencies such as CMake and Python are required. Additionally, if the library clients are to be built (by default they are not), then LAPACK and GoogleTest will be also required. (The library clients, rocsolver-test and rocsolver-bench, provide the infrastructure for testing and benchmarking rocSOLVER. For more details see the rocSOLVER clients How-To).

Using the install.sh script#

It is recommended that the provided install.sh script be used to build and install rocSOLVER. The command

./install.sh --help

gives detailed information on how to use this installation script.

Next, some common use cases are listed:

./install.sh

This command builds rocSOLVER and puts the generated library files, such as headers and librocsolver.so, in the output directory: rocSOLVER/build/release/rocsolver-install. Other output files from the configuration and building process can also be found in the rocSOLVER/build and rocSOLVER/build/release directories. It is assumed that all external library dependencies have been installed. It also assumes that the rocBLAS library is located at /opt/rocm/rocblas.

./install.sh --no-sparse

Use the --no-sparse to build rocSOLVER without rocSPARSE as a dependency. This will disable sparse functionality within rocSOLVER and will cause all relevant methods to return rocblas_status_not_implemented.

./install.sh -g

Use the -g flag to build in debug mode. In this case the generated library files will be located at rocSOLVER/build/debug/rocsolver-install. Other output files from the configuration and building process can also be found in the rocSOLVER/build and rocSOLVER/build/debug directories.

./install.sh --lib_dir /home/user/rocsolverlib --build_dir buildoutput

Use --lib_dir and --build_dir to change output directories. In this case, for example, the installer will put the headers and library files in /home/user/rocsolverlib, while the outputs of the configuration and building processes will be in rocSOLVER/buildoutput and rocSOLVER/buildoutput/release. The selected output directories must be local, otherwise the user may require sudo privileges. To install rocSOLVER system-wide, we recommend the use of the -i flag as shown below.

./install.sh --rocblas_dir /alternative/rocblas/location

Use --rocblas_dir to change where the build system will search for the rocBLAS library. In this case, for example, the installer will look for the rocBLAS library at /alternative/rocblas/location. Similarly, you may use --rocsparse_dir to specify an alternative location for the rocSPARSE library.

./install.sh -s

With the -s flag, the installer will generate a static library (librocsolver.a) instead.

./install.sh -d

With the -d flag, the installer will first install all the external dependencies required by the rocSOLVER library in /usr/local. This flag only needs to be used once. For subsequent invocations of install.sh it is not necessary to rebuild the dependencies.

./install.sh -c

With the -c flag, the installer will additionally build the library clients rocsolver-bench and rocsolver-test. The binaries will be located at rocSOLVER/build/release/clients/staging. It is assumed that all external dependencies for the client have been installed.

./install.sh -dc

By combining the -c and -d flags, the installer will also install all the external dependencies required by rocSOLVER clients. Again, the -d flag only needs to be used once.

./install.sh -i

With the -i flag, the installer will additionally generate a pre-built rocSOLVER package and install it, using a suitable package manager, at the standard location: /opt/rocm/rocsolver. This is the preferred approach to install rocSOLVER on a system, as it will allow the library to be safely removed using the package manager.

./install.sh -p

With the -p flag, the installer will also generate the rocSOLVER package, but it will not be installed.

./install.sh -i --install_dir /package/install/path

When generating a package, use --install_dir to change the directory where it will be installed. In this case, for example, the rocSOLVER package will be installed at /package/install/path.

Manual building and installation#

Manual installation of all the external dependencies is not an easy task. Get more information on how to install each dependency at the corresponding documentation sites:

CMake (version 3.16 is recommended).
LAPACK (which internally depends on a Fortran compiler), and
GoogleTest
fmt

Once all dependencies are installed (including ROCm, rocBLAS, and rocSPARSE), rocSOLVER can be manually built using a combination of CMake and Make commands. Using CMake options can provide more flexibility in tailoring the building and installation process. Here we provide a list of examples of common use cases (see the CMake documentation for more information on CMake options).

mkdir -p build/release && cd build/release
cmake --toolchain=toolchain-linux.cmake -DCMAKE_INSTALL_PREFIX=rocsolver-install ../..
make install

This is equivalent to ./install.sh.

mkdir -p buildoutput/release && cd buildoutput/release
cmake --toolchain=toolchain-linux.cmake -DCMAKE_INSTALL_PREFIX=/home/user/rocsolverlib ../..
make install

This is equivalent to ./install.sh --lib_dir /home/user/rocsolverlib --build_dir buildoutput.

mkdir -p build/release && cd build/release
cmake --toolchain=toolchain-linux.cmake -DCMAKE_INSTALL_PREFIX=rocsolver-install -DBUILD_WITH_SPARSE=OFF ../..
make install

This is equivalent to ./install.sh --no-sparse.

mkdir -p build/release && cd build/release
cmake --toolchain=toolchain-linux.cmake -DCMAKE_INSTALL_PREFIX=rocsolver-install -Drocblas_DIR=/alternative/rocblas/location ../..
make install

This is equivalent to ./install.sh --rocblas_dir /alternative/rocblas/location.

mkdir -p build/debug && cd build/debug
cmake --toolchain=toolchain-linux.cmake -DCMAKE_INSTALL_PREFIX=rocsolver-install -DCMAKE_BUILD_TYPE=Debug ../..
make install

This is equivalent to ./install.sh -g.

mkdir -p build/release && cd build/release
cmake --toolchain=toolchain-linux.cmake -DCMAKE_INSTALL_PREFIX=rocsolver-install -DBUILD_SHARED_LIBS=OFF ../..
make install

This is equivalent to ./install.sh -s.

mkdir -p build/release && cd build/release
cmake --toolchain=toolchain-linux.cmake -DCMAKE_INSTALL_PREFIX=rocsolver-install -DBUILD_CLIENTS_TESTS=ON -DBUILD_CLIENTS_BENCHMARKS=ON ../..
make install

This is equivalent to ./install.sh -c.

mkdir -p build/release && cd build/release
cmake --toolchain=toolchain-linux.cmake -DCMAKE_INSTALL_PREFIX=rocsolver-install -DCPACK_SET_DESTDIR=OFF -DCPACK_PACKAGING_INSTALL_PREFIX=/opt/rocm ../..
make install
make package

This is equivalent to ./install.sh -p.

mkdir -p build/release && cd build/release
cmake --toolchain=toolchain-linux.cmake -DCMAKE_INSTALL_PREFIX=rocsolver-install -DCPACK_SET_DESTDIR=OFF -DCPACK_PACKAGING_INSTALL_PREFIX=/package/install/path ../..
make install
make package
sudo dpkg -i rocsolver[-\_]*.deb

On an Ubuntu system, for example, this would be equivalent to ./install.sh -i --install_dir /package/install/path.