Build hipThreads from source

Build hipThreads from source#

To build hipThreads as part of the ROCm Core SDK, see TheRock build instructions. TheRock is the recommended way to build ROCm components from source.

Alternatively, you can build hipThreads standalone using the following instructions.

Prerequisites#

On Linux, ROCm must be installed before hipThreads is built.

hipThreads has the following prerequisites on Linux and Windows:

  • CMake version 3.21 or higher

  • hipcc

  • HIP and libhipcxx from an installed ROCm

  • A build tool such as make or Ninja

hipThreads has these additional prerequisites on Windows:

Get the hipThreads source code#

The hipThreads source code is available from the ROCm libraries GitHub repository. Use sparse checkout when cloning the hipThreads project:

git clone --no-checkout --filter=blob:none https://github.com/ROCm/rocm-libraries.git
cd rocm-libraries
git sparse-checkout init --cone
git sparse-checkout set projects/hipthreads

Then use git checkout to check out the branch you need. For example, to check out the develop branch:

git checkout develop

The develop branch is intended for users who want to preview new features or contribute to the hipThreads code base.

If you don’t intend to contribute to the hipThreads code base and won’t be previewing features, use a branch that matches the version of ROCm installed on your system.

Build on Linux#

By default, hipThreads installs under $ROCM_PATH to match other ROCm components. Override this by passing -DCMAKE_INSTALL_PREFIX=<path> to the CMake configure step.

From the projects/hipthreads directory, configure, build, and install:

cmake -B build
cmake --build ./build
sudo cmake --install ./build

The GPU architecture is auto-detected on Linux, so you do not need to set -DCMAKE_HIP_ARCHITECTURES.

Note

Installing to $ROCM_PATH usually requires sudo.

Build on Windows#

Run all of the following from the x64 Native Tools Command Prompt for VS 2022 so that CMake can find the MSVC toolchain and the Windows SDK.

Unlike Linux, the GPU architecture is not auto-detected on Windows and must be passed with -DCMAKE_HIP_ARCHITECTURES. It must match between the hipThreads build and every consumer, or you will get undefined device-symbol errors. For example, gfx1201 targets the Radeon RX 9070 XT.

cmake -B build -G Ninja ^
  -DCMAKE_CXX_COMPILER="clang++" -DCMAKE_C_COMPILER="clang" ^
  -DCMAKE_INSTALL_PREFIX="%HIP_PATH%" ^
  -DHIP_PLATFORM=amd ^
  -DCMAKE_HIP_ARCHITECTURES=gfx1201 ^
  -DCMAKE_BUILD_TYPE=Release .
cmake --build build
cmake --install build

Build and run the tests#

The test suite lives in the test/ directory as test/*.cxx files and is run with lit. lit compiles each test/*.cxx file with hipcc and runs the whole suite, so it works against any build (Debug or Release):

pip install lit
HIPTHREADS_SOURCE_DIR=$PWD HIPTHREADS_BUILD_DIR=$PWD/build lit -j 1 test/

Run with -j 1 so the tests run one at a time, since they share the GPU.

For quick iteration on a single test, you can also build the tests through CMake in a Debug build, which compiles each test/*.cxx file into an executable named after its source file:

cmake -B build-debug -DCMAKE_BUILD_TYPE=Debug -DDISABLE_WERROR=ON
cmake --build build-debug -j$(nproc)
./build-debug/bin/hip_thread_mutex_test
./build-debug/bin/hip_thread_condvar_test

Build and run the examples#

The examples/ directory contains standalone CMake projects that each find and link hipThreads. Each example is organized as a series of stepN-* directories showing an incremental port from CPU std::thread code to hipThreads.

Each example is built and run on its own. For instance, to build and run the SIMD-optimized SAXPY example on Linux:

cd examples/saxpy/step3-simdize
cmake -B build
cmake --build ./build
./build/bin/saxpy

On Windows, use the same Ninja, clang, and -DCMAKE_HIP_ARCHITECTURES flags as the library build above. The exact configure, build, and run commands for each step, on both Linux and Windows, are recorded in a comment at the bottom of that step’s CMakeLists.txt. Some examples need extra setup — for example, the sparse matrix multiply data is pulled with git lfs, and llama3.c takes a model path as an argument — so check the CMakeLists.txt footer for the step you are building.

After installing, see Using hipThreads in a CMake project to consume hipThreads from your own CMake project.

Contents