Building HIP from Source#
HIP code can be developed either on AMD ROCm platform using HIP-Clang compiler, or a CUDA platform with nvcc installed. Before build and run HIP, make sure drivers and pre-build packages are installed properly on the platform.
Install ROCm packages (see ROCm Installation Guide on AMD public documentation site (https://docs.amd.com/)) or install pre-built binary packages using the package manager,
sudo apt install mesa-common-dev sudo apt install clang sudo apt install comgr sudo apt-get -y install rocm-dkms
Install Nvidia driver and pre-build packages (see HIP Installation Guide at https://docs.amd.com/ for the release)
Branch of repository#
Before get HIP source code, set the expected branch of repository at the variable
For example, for ROCm5.0 release branch, set
ROCm5.1 release branch, set
Similiar format for future branches.
ROCM_PATH is path where ROCM is installed. BY default
ROCM_PATH is at
Build HIP on AMD platform#
Get HIP source code#
git clone -b $HIP_BRANCH https://github.com/ROCm-Developer-Tools/hipamd.git git clone -b $HIP_BRANCH https://github.com/ROCm-Developer-Tools/hip.git git clone -b $HIP_BRANCH https://github.com/ROCm-Developer-Tools/ROCclr.git
Set the environment variables#
export HIPAMD_DIR="$(readlink -f hipamd)" export HIP_DIR="$(readlink -f hip)"
ROCclr is defined on AMD platform that HIP use Radeon Open Compute Common Language Runtime (ROCclr), which is a virtual device interface that HIP runtimes interact with different backends. See ROCm-Developer-Tools/ROCclr
HIPAMD repository provides implementation specifically for AMD platform. See ROCm-Developer-Tools/hipamd
cd "$HIPAMD_DIR" mkdir -p build; cd build cmake -DHIP_COMMON_DIR=$HIP_DIR -DCMAKE_PREFIX_PATH="<ROCM_PATH>/" -DCMAKE_INSTALL_PREFIX=$PWD/install .. make -j$(nproc) sudo make install
If you don’t specify
CMAKE_INSTALL_PREFIX, hip runtime will be installed to
By default, release version of AMDHIP is built.
Default paths and environment variables#
By default HIP looks for HSA in
<ROCM_PATH>/hsa(can be overridden by setting
By default HIP is installed into
<ROCM_PATH>/hip(can be overridden by setting HIP_PATH environment variable).
By default HIP looks for clang in
<ROCM_PATH>/llvm/bin(can be overridden by setting
By default HIP looks for device library in
<ROCM_PATH>/lib(can be overridden by setting
Optionally, consider adding
PATHto make it easier to use the tools.
HIPCC_VERBOSE=7to output the command line for compilation.
After make install command, make sure
HIP_PATH is pointed to
Generating profiling header after adding/changing a HIP API#
When you add or change a HIP API, you might need to generate a new
hip_prof_str.h header. This header is used by rocm tools to track HIP APIs like rocprofiler/roctracer etc.
To generate the header after your change, use the tool
hip_prof_gen.py present in
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: ```shell 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 sudo make install ### Build HIP tests #### Build HIP directed tests Developers can build HIP directed tests right after build HIP commands, ```shell make -j$(nproc) build_tests
By default, all HIP directed tests will be built and generated under the folder
Take HIP directed device APIs tests, as an example, all available test applications will have executable files generated under,
Run all HIP directed_tests, use the command,
ctest ```shell Or
Build and run a single directed test, use the follow command as an example, ```shell make directed_tests.texture.hipTexObjPitch cd $HIPAMD_DIR/build/directed_tests/texcture ./hipTexObjPitch
Please note, the integrated HIP directed tests, will be deprecated in future release.
Build HIP catch tests#
After build and install HIP commands, catch tests can be built via the following instructions,
cd "$HIP_DIR" mkdir -p build; cd build export HIP_PATH=$HIPAMD_DIR/build/install cmake ../tests/catch/ -DHIP_PLATFORM=amd make -j$(nproc) build_tests ctest # run tests ```shell HIP catch tests are built under the folder $HIP_DIR/build. To run a single catch test, the following is an example,
cd $HIP_DIR/build/unit/texture ./TextureTest
### Build HIP Catch2 standalone test HIP Catch2 supports build a standalone test, for example, ```shell export PATH=$HIP_DIR/bin:$PATH export HIP_PATH=$HIPAMD_DIR/build/install hipcc $HIP_DIR/tests/catch/unit/memory/hipPointerGetAttributes.cc -I ./tests/catch/include ./tests/catch/hipTestMain/standalone_main.cc -I ./tests/catch/external/Catch2 -g -o hipPointerGetAttributes ./hipPointerGetAttributes ... All tests passed ```shell HIP catch tests, especially new architectured Catch2, will be official HIP tests in the repository and can be built alone as with the instructions shown above. ## Build HIP on NVIDIA platform ### Get HIP source code
### Set the environment variables
export HIP_DIR=”$(readlink -f hip)” export HIPAMD_DIR=”$(readlink -f hipamd)”
### Build HIP
cd “$HIPAMD_DIR” mkdir -p build; cd build cmake -DHIP_COMMON_DIR=$HIP_DIR -DHIP_PLATFORM=nvidia -DCMAKE_INSTALL_PREFIX=$PWD/install … make -j$(nproc) sudo make install
### Build HIP tests Build HIP tests commands on NVIDIA platform are basically the same as AMD, except set `-DHIP_PLATFORM=nvidia`. ## Run HIP Compile and run the [square sample](https://github.com/ROCm-Developer-Tools/HIP/tree/rocm-5.0.x/samples/0_Intro/square).