Build HIP from source#
Prerequisites#
HIP code can be developed either on AMD ROCm platform using HIP-Clang compiler, or a CUDA platform with nvcc
installed.
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#
In the ROCM 7.1 release, HIP is integrated into the core ROCm projects resides in the rocm-systems
monorepository.
In addition, the following components are also part of the monrepository:
clr
, AMD’s Compute Language Runtime, includes ROCclr, HIPAMD and OpenCl.hipother
, provides files required to support the HIP back-end implementation on some non-AMD platforms, like NVIDIA.hip-tests
, the HIP testing suite.
Set the repository branch using the variable: ROCM_BRANCH
. For example, for ROCM 7.1, use:
export ROCM_BRANCH=release/rocm-rel-7.1
Get HIP source code.
git clone -b "$ROCM_BRANCH" [email protected]:ROCm/rocm-systems.git
Set the environment variables.
export CLR_DIR="$(readlink -f rocm-systems/projects/clr)" export HIP_DIR="$(readlink -f rocm-systems/projects/hip)"
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 theINSTALL_PREFIX
as the command option. environment variable.
- HIP is installed into
- HSA is in
<ROCM_PATH>
. This can be overridden by setting theHSA_PATH
environment variable.
- HSA is in
- Clang is in
<ROCM_PATH>/llvm/bin
. This can be overridden by setting the HIP_CLANG_PATH
environment variable.
- Clang is in
- The device library is in
<ROCM_PATH>/lib
. This can be overridden by setting the DEVICE_LIB_PATH
environment variable.
- The device library is in
- Optionally, you can add
<ROCM_PATH>/bin
to yourPATH
, which can make it easier to use the tools.
- Optionally, you can add
Optionally, you can set
HIPCC_VERBOSE=7
to output the command line for compilation.
After you run the
make install
command, HIP is installed to<ROCM_PATH>
by default, or$PWD/install/hip
whileINSTALL_PREFIX
is defined.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 asrocprofiler
androctracer
.To generate the header after your change, use the
hip_prof_gen.py
tool located inhipamd/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
Get the HIP source code.
git clone -b "$ROCM_BRANCH" [email protected]:ROCm/rocm-systems.git
Set the environment variables.
export CLR_DIR="$(readlink -f rocm-systems/projects/clr)" export HIP_DIR="$(readlink -f rocm-systems/projects/hip)" export HIP_OTHER="$(readlink -f rocm-systems/projects/hipother)"
Build HIP.
cd "$CLR_DIR" mkdir -p build; cd build cmake -DHIP_COMMON_DIR=$HIP_DIR -DHIP_PLATFORM=nvidia -DCMAKE_INSTALL_PREFIX=$PWD/install -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 utilize the Catch2 testing framework.
Get HIP tests source code.
git clone -b "$ROCM_BRANCH" [email protected]:ROCm/rocm-systems.git export HIPTESTS_DIR="$(readlink -f rocm-systems/projects/hip-tests)"
Build HIP tests from source.
cd "$HIPTESTS_DIR" mkdir -p build; cd build cmake ../catch -DHIP_PLATFORM=amd -DHIP_PATH=$CLR_DIR/build/install # or any path where HIP is installed; for example: ``/opt/rocm`` export ROCM_PATH=/opt/rocm make 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
.
Run HIP#
After installation and building HIP, you can compile your application and run. Simple examples can be found in the ROCm-examples repository.