This document provides information required to build and install ROCR using prebuilt binaries or from source.
Build and install using prebuilt binaries
-------------------------------------------
Here is how you can install ROCR using prebuilt binaries.
Prerequisites
*******************
- A system supporting ROCm. See the `supported operating systems <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html#supported-operating-systems>`_.
- Install ROCm. See `how to install ROCm <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/>`_.
- HSA include files to support application development on the HSA runtime for the ROCR runtime
- A 64-bit version of AMD’s HSA core runtime for the ROCR runtime
**Runtime extension package:**
- A 64-bit version of AMD’s runtime tools library
- A 64-bit version of AMD’s runtime image library
The contents of these packages are installed in ``/opt/rocm/hsa`` and ``/opt/rocm`` by default. The core runtime package depends on the ``hsakmt-roct-dev`` package.
Build and install from source
--------------------------------
Here is how you can build ROCR from source.
Prerequisites
***************
- CMake 3.7 or later. Export CMake bin into your PATH.
- A compatible version of the ``libhsakmt`` library and the ``hsakmt.h`` header file. Obtain the latest version of these files from `ROCR-Runtime/libhsakmt <https://github.com/ROCm/rocm-systems/tree/develop/projects/rocr-runtime/libhsakmt>`_.
The ``libhsakmt`` development packages include a CMake package config file. The runtime locates ``libhsakmt`` via ``find_package`` if ``libhsakmt`` is installed in a standard location. For installations that don't use standard ROCm paths, set CMake variables ``CMAKE_PREFIX_PATH`` or ``hsakmt_DIR`` to override ``find_package`` search paths.
The runtime includes an optional image support module (previously ``hsa-ext-rocr-dev``). By default this module is included in the runtime builds. To exclude the image module from the runtime, set the CMake variable ``IMAGE_SUPPORT`` to OFF.
To build the optional image module, install AMDGCN-compatible clang and device library. You can find the latest version of these additional build dependencies in the `ROCm package repository <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/how-to/native-install/package-manager-integration.html#packages-in-rocm-programming-models>`_.
The latest source for these projects are available in the `llvm project <https://github.com/ROCm/llvm-project>`_ and `ROCm device libs <https://github.com/ROCm/ROCm-Device-Libs>`_ repositories.
The runtime optionally supports use of the CMake user package registry. By default the registry is not modified. Set CMake variable ``EXPORT_TO_USER_PACKAGE_REGISTRY`` to ON to enable updating the package registry.
To build, install, and produce packages on a system with standard ROCm packages installed, clone your copy of ROCR and run the following from ``src/``:
..code-block::shell
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=/opt/rocm ..
make
make install
make package
Example with a custom installation path, build dependency path, and options:
..code-block::shell
cmake -DIMAGE_SUPPORT=OFF \
-DEXPORT_TO_USER_PACKAGE_REGISTRY=ON \
-DCMAKE_VERBOSE_MAKEFILE=1\
-DCMAKE_PREFIX_PATH=<alternate path(s) to build dependencies> \
-DCMAKE_INSTALL_PATH=<custom install path for this build> \
..
Alternatively, use ``ccmake`` and ``cmake-gui``:
..code-block::shell
mkdir build
cd build
ccmake ..
press c to configure
populate variables as desired
press c again
press g to generate and exit
make
Building against the runtime
---------------------------------
The runtime provides a CMake package config file, installed by default to ``/opt/rocm/lib/cmake/hsa-runtime64``. The runtime exports CMake target ``hsa-runtime64`` in namespace ``hsa-runtime64``. A CMake project (``Foo``) using the runtime may locate, include, and link the runtime using the following template:
