Build and install hipFile from source

To build hipFile as part of the ROCm Core SDK, see TheRock build instructions. TheRock is the supported path for full-stack ROCm source builds.

Alternatively, you can build hipFile standalone from rocm-systems using the steps below. For ROCm meta packages instead of compiling, see Install hipFile.

Prerequisites

hipFile targets Linux with ROCm HIP. For supported GPUs and stack components, see ROCm Core SDK components.

• CMake 3.21 or later

• A C++ compiler that matches the HIPFILE_CXX_STANDARD value you select. The default is C++20.

• HIP and HSA packages from ROCm so CMake can locate hip and hsa-runtime64

• libmount from util-linux for mount metadata parsing

• A Linux kernel built with CONFIG_PCI_P2PDMA=y for the peer-to-peer DMA fastpath. hipFile builds and runs without it, but all I/O uses the fallback path. See Check for kernel P2PDMA support for how to check the running kernel, and hipFile kernel P2PDMA support for which distribution kernels enable the option.

Build and install

1. hipFile lives under projects/hipfile in the ROCm rocm-systems repository. Clone with a sparse checkout so you only fetch that subtree.

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

2. Check out the branch you intend to build, then enter the hipFile tree.

   git checkout develop
   cd projects/hipfile
   

3. Configure, compile, and install with CMake. The defaults wire CMAKE_INSTALL_PREFIX to ROCM_PATH so libraries and headers land next to your ROCm install.

   cmake -B build -DCMAKE_HIP_PLATFORM=amd
   cmake --build build -j
   sudo cmake --install build
   

   After installation, libhipfile.so and hipfile.h appear under the lib and include directories beneath CMAKE_INSTALL_PREFIX, typically /opt/rocm when you don’t override ROCM_PATH.

4. Optional CTest pass from the build tree:

   cd build
   ctest --output-on-failure
   

   You can also run cmake --build . --target test from build if you prefer Make-driven test targets.

CMake options

The table lists the most common CMake cache entries for hipFile. Other flags exist for sanitizers, clang-tidy, and documentation generation. Inspect CMakeCache.txt after the first configure pass for the full set.

Option	Default	Description
CMAKE_HIP_PLATFORM	amd	HIP platform selector. Use amd.
ROCM_PATH	/opt/rocm or derived from ROCM_VERSION	ROCm root used for CMAKE_PREFIX_PATH and the default install prefix.
ROCM_VERSION	Read from ${ROCM_PATH}/.info/version when unset	ROCm version string for path logic and compatibility checks.
CMAKE_INSTALL_PREFIX	${ROCM_PATH} when left at the CMake default	Install root for libraries, headers, and tools.
BUILD_SHARED_LIBS	ON	Builds shared libraries when ON and static libraries when OFF.
HIPFILE_CXX_STANDARD	20	C++ dialect. Allowed values are 20, 23, and 26.
HIPFILE_INSTALL_EXAMPLES	ON	Installs sample binaries such as aiscp when enabled.
HIPFILE_INSTALL_TOOLS	ON	Installs host tools such as ais-stats when enabled on AMD builds.
HIPFILE_BUILD_DOCS	OFF	Enables the doc target when ON. Requires Doxygen in your environment.
HIPFILE_USE_CODE_COVERAGE	OFF	Adds LLVM coverage instrumentation for Clang builds.
BUILD_TESTING	ON unless you pass -DBUILD_TESTING=OFF	Controls whether the hipFile test binaries are built.
CMAKE_BUILD_TYPE	RelWithDebInfo	CMake build flavor. Other common values are Debug, Release, MinSizeRel, and None.

Note

The HIPFILE_ options were previously named with an AIS_ prefix (for example, AIS_CXX_STANDARD). The AIS_ names still work but are deprecated, and CMake prints a deprecation warning when you use them.