Build HIP from source

Build HIP from source#

Prerequisites#

HIP code can be developed on AMD ROCm platform using HIP-Clang compiler. Before building and running HIP, make sure drivers and prebuilt packages are installed properly on the platform.

You also need to install Python 3, which includes the CppHeaderParser package. Install Python 3 using the following command:

apt-get install python3

Check and install CppHeaderParser package using the command:

pip3 install CppHeaderParser

Install ROCm LLVM package using the command:

apt-get install rocm-llvm-dev

Building the HIP runtime#

HIP is one of the core ROCm projects and resides in the rocm-systems monorepository. In addition, the monorepository also includes the following components:

  • clr, AMD’s Compute Language Runtime, which contains ROCclr, HIPAMD, and OpenCL.

  • hip-tests, the HIP testing suite.

Beginning with the TheRock 7.13 release, the rocm-systems codebase is also integrated into the TheRock repository. Developers may build HIP using one of two methods:

  • From rocm-systems monorepository

  • From the ROCm TheRock repository

This document provides instructions for building HIP from the rocm-systems monorepository. For guidance on building HIP using TheRock, see the build documentation included with TheRock.

  1. Set the repository branch

    Set the branch using the variable: ROCM_BRANCH. For example, for TheRock 7.13, use:

    export ROCM_BRANCH=release/therock-7.13

  2. Get HIP source code.

    git clone -b "$ROCM_BRANCH" git@github.com:ROCm/rocm-systems.git

  3. Set the environment variables.

    export CLR_DIR="$(readlink -f rocm-systems/projects/clr)"
export HIP_DIR="$(readlink -f rocm-systems/projects/hip)"
export ROCM_PATH=/opt/rocm

  4. Build HIP.

    cd "$CLR_DIR"
mkdir -p build && cd build
cmake \
  -DHIP_COMMON_DIR="$HIP_DIR" \
  -DHIP_PLATFORM=amd \
  -DCMAKE_PREFIX_PATH="/opt/rocm/" \
  -DCMAKE_INSTALL_PREFIX="$PWD/install" \
  -DCLR_BUILD_HIP=ON \
  -DCLR_BUILD_OCL=OFF \
  ..
make -j$(nproc)
sudo make install

    Note

    If CMAKE_INSTALL_PREFIX is not explicitly specified, the HIP runtime will be installed at <ROCM_PATH>, which is by default at the path /opt/rocm.

    By default, the release version of HIP is built. If you need a debug version, you can put the option CMAKE_BUILD_TYPE=Debug in the command line.

    Default paths and environment variables:

    • HIP is installed into <ROCM_PATH>. This can be overridden by setting the INSTALL_PREFIX as the command option.

    • HSA is in <ROCM_PATH>. This can be overridden by setting the HSA_PATH environment variable.

    • The device library is in <ROCM_PATH>/lib. This can be overridden by setting the DEVICE_LIB_PATH environment variable.

    • Optionally, you can add <ROCM_PATH>/bin to your PATH, which can make it easier to use the tools.

    After you run the make install command, HIP is installed to <ROCM_PATH> by default, or $PWD/install/hip while INSTALL_PREFIX is defined.

  5. Generate a profiling header after adding/changing a HIP API.

    When you add or change a HIP API, you may need to generate a new hip_prof_str.h header. This header is used by ROCm tools to track HIP APIs, such as rocprofiler and roctracer.

    To generate the header after your change, use the hip_prof_gen.py tool located in hipamd/src.

    Usage:

    hip_prof_gen.py [-v] <input HIP API .h file> <patched srcs path> <previous output> [<output>]

    Flags:

    • -v: Verbose messages

    • -r: Process source directory recursively

    • -t: API types matching check

    • --priv: Private API check

    • -e: On error exit mode

    • -p: HIP_INIT_API macro patching mode

    Example usage:

    hip_prof_gen.py -v -p -t --priv <hip>/include/hip/hip_runtime_api.h \
<hipamd>/src <hipamd>/include/hip/amd_detail/hip_prof_str.h \
<hipamd>/include/hip/amd_detail/hip_prof_str.h.new

Build HIP tests#

Build HIP catch tests.

HIP catch tests are built using AMD’s amdclang compiler.

  1. Get HIP tests source code.

    git clone -b "$ROCM_BRANCH" git@github.com:ROCm/rocm-systems.git
export HIPTESTS_DIR="$(readlink -f rocm-systems/projects/hip-tests)"

  2. Build HIP tests from source.

    cd "$HIPTESTS_DIR"
mkdir -p build; cd build
export ROCM_PATH=/opt/rocm
cmake ../catch \
  -DHIP_PLATFORM=amd \
  -DCMAKE_PREFIX_PATH=$CLR_DIR/build/install \
  -DCMAKE_CXX_COMPILER=$ROCM_PATH/bin/amdclang++ \
  -DCMAKE_C_COMPILER=$ROCM_PATH/bin/amdclang \
  -DCMAKE_HIP_COMPILER=$ROCM_PATH/bin/amdclang++ \
  -DOFFLOAD_ARCH_STR="--offload-arch=<selected-gpu-arch>"
make build_tests
ctest # run tests

    Note: The value of OFFLOAD_ARCH_STR should match the GPU architecture present on your system (e.g., gfx1200). You can determine the correct architecture by running the rocminfo command.

    HIP catch tests are built in $HIPTESTS_DIR/build.

    To run any single catch test, use this example:

    cd $HIPTESTS_DIR/build/catch_tests/unit/texture
./TextureTest

  3. Build a HIP Catch standalone test.

    For detailed instructions on building the standalone Catch tests, consult the hip-tests README.md at.

Run HIP#

After installation and building HIP, you can compile your application and run. Simple examples can be found in the ROCm-examples repository.

Contents