.. meta:: :description: hipSOLVER installation guide :keywords: hipSOLVER, rocSOLVER, ROCm, API, documentation, install *************************** Build hipSOLVER from source *************************** To build hipSOLVER as part of the ROCm Core SDK, see `TheRock build instructions `__. TheRock is the recommended way to build ROCm components from source. Alternatively, you can build hipSOLVER standalone using the following instructions. Build and install the library using a script (Ubuntu only) ========================================================== The root directory of the `hipSOLVER project `_ in the `rocm-libraries GitHub `_ includes the ``install.sh`` bash script for building and installing hipSOLVER on Ubuntu with a single command. The script does not accept many options and hardcodes most configuration attributes, but it's a great way to get started quickly and serves as an example of how to build and install hipSOLVER. A more extensive set of options can be specified by invoking ``cmake`` directly. A few commands in the script require ``sudo`` access, so it might prompt you for a password. .. note:: To build hipSOLVER for ROCm 7.0.2 and earlier, use the hipSOLVER repository at ``_. For more information, see the documentation associated with the release you want to build. Here are some typical examples of using the script: .. note:: Run these commands from the ``rocm-libraries/projects/hipsolver`` directory. * ``./install.sh -id``: Build the library and dependencies and install them (the ``-d`` flag only needs to be passed once on a system). * ``./install.sh -ic``: Build library and clients (tests, benchmarks, and samples) and install them. To list more options, use the ``-h`` (help) option of the install script. .. code-block:: shell ./install.sh -h Build and install the library manually ====================================== For a standard library installation, follow these steps: .. code-block:: bash mkdir -p /release cd /release CXX=/opt/rocm/bin/hipcc cmake make -j$(nproc) sudo make install ``sudo`` is required to install hipSOLVER to a system directory, such as ``/opt/rocm``, which is the default location. * Use ``-DCMAKE_INSTALL_PREFIX=`` to specify a different install directory. * Use ``-DCMAKE_BUILD_TYPE=`` to specify a build configuration, such as ``Debug``. The default build configuration is ``Release``. Library dependencies --------------------- The ROCm (rocSOLVER) backend has the following dependencies: * `rocSOLVER `_ * `rocBLAS `_ * `rocSPARSE `_ (optional) * `SuiteSparse `_: ``CHOLMOD`` and ``SuiteSparse_config`` modules (optional) rocSOLVER itself depends on rocBLAS and rocSPARSE, therefore all three libraries should be installed as part of a standard rocSOLVER installation. For more information about building and installing rocSOLVER, see the :doc:`rocSOLVER installation guide `. SuiteSparse is a third-party library which can be installed using the package managers of most distributions. Together with rocSPARSE, it is used to provide functionality for the ``hipsolverSp`` API. By default, both libraries are run-time dependencies. They are dynamically loaded by ``dlopen`` if they are present on the system. If the ``BUILD_WITH_SPARSE`` option is set to ``ON``, they become build-time dependencies instead and must be present on the system to build hipSOLVER. .. code-block:: shell DBUILD_WITH_SPARSE=ON Build the library, tests, benchmarks, and samples manually ========================================================== The repository contains source code for client programs that serve as tests, benchmarks, and samples. The client source code can be found in the ``clients`` subdirectory. Client dependencies -------------------- The hipSOLVER samples have no external dependencies, but the unit test and benchmarking applications do. These clients introduce the following dependencies: * `LAPACK `_ (Adds a dependency on a Fortran compiler) * `GoogleTest `_ * `hipBLAS `_ (Optional) * `hipSPARSE `_ (Optional, but required with the default settings) Many distributions do not provide a GoogleTest package with precompiled libraries, and the LAPACK packages do not have the necessary CMake configuration files to link to the CBLAS library. hipSOLVER provides a CMake script that builds LAPACK and GoogleTest from source. This is an optional step because you can provide your own builds of these dependencies, setting ``CMAKE_PREFIX_PATH`` to let CMake find them. The following sequence of steps builds the dependencies and installs them to the default CMake directory ``/usr/local``: .. code-block:: bash mkdir -p /release/deps cd /release/deps cmake /deps make -j$(nproc) install hipBLAS is only required if the ``BUILD_HIPBLAS_TESTS`` option is set to ``ON``. It's used to ensure compatibility between the hipBLAS enumerations defined separately by hipBLAS and hipSOLVER. hipSPARSE is required by default but the dependency is ignored if the ``BUILD_HIPSPARSE_TESTS`` option is set to ``OFF``. It's used to create objects required by tests for the ``hipsolverSp`` API. .. code-block:: shell DBUILD_HIPBLAS_TESTS=ON DBUILD_HIPSPARSE_TESTS=OFF Both libraries can be installed the same way as hipSOLVER. For example, the install scripts for hipBLAS and hipSPARSE can be invoked to build and install those libraries using the following command: .. code-block:: shell ./install.sh -i For more details, see the :doc:`hipBLAS ` and :doc:`hipSPARSE ` documentation. Library and clients -------------------- After the dependencies are installed on the system, you can configure which clients to build. This requires adding a few extra flags to the CMake configure script for the library. If the dependencies are not installed into the default system locations, like ``/usr/local``, pass the ``CMAKE_PREFIX_PATH`` to CMake so it can find them. .. code-block:: bash -DCMAKE_PREFIX_PATH="" Follow this example to build the library and clients: .. code-block:: bash CXX=/opt/rocm/bin/hipcc cmake -DBUILD_CLIENTS_TESTS=ON -DBUILD_CLIENTS_BENCHMARKS=ON [HIPSOLVER_SOURCE] make -j$(nproc) sudo make install # sudo required if installing into system directory such as /opt/rocm