Build HIP from source#

Building the HIP runtime#

Set the repository branch using the variable: ROCM_BRANCH. For example, for ROCm 6.1, use:

export ROCM_BRANCH=rocm-6.1.x

  1. Get HIP source code.

    Note

    Starting in ROCM 5.6, CLR is a new repository that includes the former ROCclr, HIPAMD and OpenCl repositories. OpenCL provides headers that ROCclr runtime depends on.

    Note

    Starting in ROCM 6.1, a new repository hipother is added to ROCm, which is branched out from HIP. hipother provides files required to support the HIP back-end implementation on some non-AMD platforms, like NVIDIA.

    git clone -b "$ROCM_BRANCH" https://github.com/ROCm/clr.git
git clone -b "$ROCM_BRANCH" https://github.com/ROCm/hip.git
git clone -b "$ROCM_BRANCH" https://github.com/ROCm/hipother.git
git clone -b "$ROCM_BRANCH" https://github.com/ROCm/HIPCC.git

    CLR (Common Language Runtime) repository includes ROCclr, HIPAMD and OpenCL.

    ROCclr (Radeon Open Compute Common Language Runtime) is a virtual device interface which is defined on the AMD platform. HIP runtime uses ROCclr to interact with different backends.

    HIPAMD provides implementation specifically for HIP on the AMD platform.

    OpenCL provides headers that ROCclr runtime currently depends on. hipother provides headers and implementation specifically for non-AMD HIP platforms, like NVIDIA.

  2. Set the environment variables.

    export CLR_DIR="$(readlink -f clr)"
export HIP_DIR="$(readlink -f hip)"
export HIP_OTHER="$(readlink -f hipother)"
export HIPCC_DIR="$(readlink -f HIPCC)"

  3. Build the HIPCC runtime.

    cd "$HIPCC_DIR"
mkdir -p build; cd build
cmake ..
make -j4

  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 -DHIPCC_BIN_DIR=$HIPCC_DIR/build -DHIP_CATCH_TEST=0 -DCLR_BUILD_HIP=ON -DCLR_BUILD_OCL=OFF ..

make -j$(nproc)
sudo make install

    Note

    Note, if you don’t specify CMAKE_INSTALL_PREFIX, the HIP runtime is installed at <ROCM_PATH>/hip.

    By default, release version of HIP is built. If need 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>/hip. This can be overridden by setting the HIP_PATH

      environment variable.

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

      environment variable.

    • Clang is in <ROCM_PATH>/llvm/bin. This can be overridden by setting the

      HIP_CLANG_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.

    • Optionally, you can set HIPCC_VERBOSE=7 to output the command line for compilation.

    After you run the make install command, make sure HIP_PATH points to $PWD/install/hip.

    1. 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

  1. Get the HIP source code.

    git clone -b "$ROCM_BRANCH" https://github.com/ROCm/clr.git
git clone -b "$ROCM_BRANCH" https://github.com/ROCm/hip.git
git clone -b "$ROCM_BRANCH" https://github.com/ROCm/hipother.git
git clone -b "$ROCM_BRANCH" https://github.com/ROCm/HIPCC.git

  2. Set the environment variables.

    export CLR_DIR="$(readlink -f clr)"
export HIP_DIR="$(readlink -f hip)"
export HIP_OTHER="$(readlink -f hipother)"
export HIPCC_DIR="$(readlink -f HIPCC)"

  3. Build the HIPCC runtime.

    cd "$HIPCC_DIR"
mkdir -p build; cd build
cmake ..
make -j4

  4. Build HIP.

    cd "$CLR_DIR"
mkdir -p build; cd build
cmake -DHIP_COMMON_DIR=$HIP_DIR -DHIP_PLATFORM=nvidia -DCMAKE_INSTALL_PREFIX=$PWD/install -DHIPCC_BIN_DIR=$HIPCC_DIR/build -DHIP_CATCH_TEST=0 -DCLR_BUILD_HIP=ON -DCLR_BUILD_OCL=OFF -DHIPNV_DIR=$HIP_OTHER/hipnv ..
make -j$(nproc)
sudo make install

Build HIP tests#

  • Build HIP catch tests.

    HIP catch tests are separate from the HIP project and use Catch2.

    • Get HIP tests source code.

      git clone -b "$ROCM_BRANCH" https://github.com/ROCm/hip-tests.git

    • Build HIP tests from source.

      export HIPTESTS_DIR="$(readlink -f hip-tests)"
cd "$HIPTESTS_DIR"
mkdir -p build; cd build
export HIP_PATH=$CLR_DIR/build/install  # or any path where HIP is installed; for example: ``/opt/rocm``
cmake ../catch/ -DHIP_PLATFORM=amd
make -j$(nproc) build_tests
ctest # run tests

      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

    • Build a HIP Catch2 standalone test.

      cd "$HIPTESTS_DIR"
hipcc $HIPTESTS_DIR/catch/unit/memory/hipPointerGetAttributes.cc \
-I ./catch/include ./catch/hipTestMain/standalone_main.cc \
-I ./catch/external/Catch2 -o hipPointerGetAttributes
./hipPointerGetAttributes
...

All tests passed

The commands to build HIP tests on an NVIDIA platform are the same as on an AMD platform. However, you must first set -DHIP_PLATFORM=nvidia.