.. highlight:: rst
.. |project_name| replace:: rocBLAS

==============
|project_name|
==============

-----------------
Quick Start Guide
-----------------

This section describes how to configure and build the |project_name| project. We assume the user has a
ROCm installation, Python 3.8 or newer and CMake 3.25.2 or newer.

The |project_name| project consists of three components:

1. **|project_name| library**: The main library providing the rocBLAS host API and non-GEMM device kernels.
   Build system files are currently located in the ``library`` subdirectory, though this location is
   expected to change in the future to better reflect the library's nature.
2. **GEMM device libraries**: Generated by Tensile, these libraries contain the GEMM device kernels. Build
   system files are added as a subdirectory pointing to Tensile. While ``find_package`` support is currently
   enabled, it is expected to be removed in the future to allow only super-build consumption via ``add_subdirectory``.
3. **Client applications**: Provides testing, benchmarking, and sample applications. Build system files are
   located in the ``client`` subdirectory.

^^^^^^^^^^^^^^^^^^^
Configure and build
^^^^^^^^^^^^^^^^^^^

|project_name| provides modern CMake support and relies on native CMake fnuctionality with exception of
some project specific options. As such, users are advised to refer to the CMake documentation for
general usage questions. Below are usage examples to get started. For details on all configuration
options see the options section.

Full build of |project_name|
-----------------------

   .. code-block:: cmake
      :linenos:

      cd rocBLAS/next-cmake
      # configure
      cmake -B build                                       \
            -S .                                           \
            -D CMAKE_CXX_COMPILER=/opt/rocm/bin/amdclang++ \
            -D CMAKE_C_COMPILER=/opt/rocm/bin/amdclang     \
            -D CMAKE_BUILD_TYPE=Release                    \
            -D CMAKE_PREFIX_PATH=/opt/rocm                 \
            -D GPU_TARGETS=gfx90a
      # build
      cmake --build build --parallel 32

Building device libraries
-------------------------
   .. code-block:: cmake
      :linenos:

      cd rocBLAS/next-cmake
      # configure
      cmake -B build                                       \
            -S .                                           \
            -D CMAKE_CXX_COMPILER=/opt/rocm/bin/amdclang++ \
            -D CMAKE_C_COMPILER=/opt/rocm/bin/amdclang     \
            -D CMAKE_BUILD_TYPE=Release                    \
            -D CMAKE_PREFIX_PATH=/opt/rocm                 \
            -D GPU_TARGETS=gfx90a                          \
            -D ROCBLAS_ENABLE_TENSILE=ON                   \
            -D ROCBLAS_ENABLE_CLIENT=OFF
      # build
      cmake --build build --parallel 32

.. tip::
      **For Developers**

      View debugging info by adding ``--log-level=VERBOSE`` to the configure command.


Options
-------

*CMake options*:

* ``CMAKE_BUILD_TYPE``: Any of Release, Debug, RelWithDebInfo, MinSizeRel
* ``CMAKE_INSTALL_PREFIX``: Base installation directory (defaults to ``/opt/rocm`` on Linux, ``C:/hipSDK`` on Windows)
* ``CMAKE_PREFIX_PATH``: Find package search path (consider setting to ``$ROCM_PATH``)
* ``CMAKE_EXPORT_COMPILE_COMMANDS``: Export compile_commands.json for clang tooling support (default: ``ON``)

*Superbuild options*:

* ``BUILD_SHARED_LIBS``: Build the rocBLAS shared or static library (default: ``ON``)
* ``BUILD_TESTING``: Build test client (default: ``ON``)
* ``BUILD_CODE_COVERAGE``: Build tests with coverage support (default: ``OFF``)

*Project wide options*:

* ``ROCBLAS_ENABLE_TENSILE``: Enables generation of device libraries (default: ``ON``)
* ``ROCBLAS_ENABLE_CLIENT``: Enables generation of client applications (default: ``ON``)
* ``ROCBLAS_ENABLE_ASAN``: Build with address sanitizer enabled (default: ``OFF``)
* ``ROCBLAS_BUILD_COVERAGE``: Build tests with coverage support (default: ``OFF``)

*rocBLAS library options*:

* ``ROCBLAS_BUILD_SHARED_LIBS``: Build the |project_name| shared or static library (default: same as ``BUILD_SHARED_LIBS``)
* ``ROCBLAS_ENABLE_TENSILE``: Build |project_name| library with Tensile backend (default: ``ON``)
* ``ROCBLAS_ENABLE_HIPBLASLT``: Build |project_name| library with hipBLASLt backend (default: ``ON``)
* ``ROCBLAS_ENABLE_BLIS``: Enable BLIS support (default: ``ON``)
* ``ROCBLAS_ENABLE_MARKER``: Enable rocTracer marker support (default: ``OFF``)
* ``ROCBLAS_CONFIG_DIR``: Path placed into ldconfig file (default: ``${CPACK_PACKAGING_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}``)

*Tensile device libraries options*:

* ``ROCBLAS_TENSILE_SUBDIR_PATH``: Path to Tensile subdirectory (default: ``${CMAKE_CURRENT_SOURCE_DIR}/../../Tensile``)
* ``ROCBLAS_TENSILE_INSTALL_DIR``: Path to tensile library (default: ``${CPACK_PACKAGING_INSTALL_PREFIX}${CMAKE_INSTALL_LIBDIR}/rocblas`` on Linux, ``${CPACK_PACKAGING_INSTALL_PREFIX}rocblas/bin`` on Windows)

*Client options*:

* ``ROCBLAS_BUILD_TESTING``: Build test client (default: same as ``BUILD_TESTING``)
* ``ROCBLAS_ENABLE_BENCHMARKS``: Build benchmark client (default: ``ON``)
* ``ROCBLAS_ENABLE_SAMPLES``: Build client samples (default: ``ON``)
* ``ROCBLAS_ENABLE_FORTRAN``: Build Fortran clients (default: ``OFF``)
* ``ROCBLAS_REQUIRE_ROCM_SMI``: Require rocm_smi (default: ``ON`` on Linux, ``OFF`` on Windows)

CMake Targets
-------------

* ``roc::rocblas``