Install the hipFile Python bindings

Install the hipFile Python bindings#

This page covers building and installing the Cython-based Python bindings for the hipFile C library. Before following these steps, you must have the hipFile C library already built or installed. See Build and install hipFile from source for instructions on building the C library.

Prerequisites#

The Python bindings require the following software:

  • Python >= 3.10 with the venv module

  • Cython (installed into your virtual environment)

  • scikit-build-core (used as the build backend)

  • python-build (the build front-end, or pip for editable installs)

  • CMake (version 3.21 or later)

  • A C compiler (for building the Cython-generated C extension)

  • hipFile C library (libhipfile.so): built or installed before the Python bindings

  • hipFile C development header (hipfile.h)

  • HIP development headers (hip/hip_runtime_api.h)

Note

The Python bindings currently support only the AMD platform.

Set up a virtual environment#

Create and activate a Python virtual environment before installing dependencies or building the bindings:

python3 -m venv .venv
source .venv/bin/activate

Install the required Python build tools inside the virtual environment:

pip install cython scikit-build-core build

Build the hipFile C library#

The Python bindings link against libhipfile.so and include hipfile.h. You must build or install the C library before building the Python package.

If you are building from source, follow the steps in Build and install hipFile from source. Note the paths to the build output directory and the include/ directory: you may need them for the override variables described below.

Build the Python wheel#

Navigate to the python/ directory inside the hipFile source tree and build the wheel:

cd projects/hipfile/python
python -m build --wheel

The build system uses CMake (via scikit-build-core) to locate the hipFile headers, the hipFile shared library, and the HIP runtime headers. By default, it searches:

  • The sibling ../include directory (relative to the python/ directory) is searched for hipfile.h, with /opt/rocm/include as a fallback location

  • The sibling ../build/src/amd_detail directory is searched for libhipfile.so, with /opt/rocm/lib as a fallback location

If these default paths do not match your environment, use the override variables described in CMake override variables.

Install an editable package#

For development, you can install the Python package in editable mode. An editable install lets you modify the Python source code and see changes immediately without rebuilding or reinstalling the package. Changes to the Cython source code still require a rebuild.

cd projects/hipfile/python
pip install -e .

CMake override variables#

If the hipFile library, hipFile headers, or HIP headers are installed in non-default locations, pass override variables to CMake through the build front-end. Use the -Ccmake.define.<KEY>=<VALUE> syntax with python -m build, or set them as environment-specific CMake variables with pip.

Variable

Description

HIPFILE_INCLUDE_DIR

Path to the directory containing hipfile.h. Defaults to ../include (relative to python/) or /opt/rocm/include.

HIPFILE_LIBRARY

Path to libhipfile.so. Defaults to ../build/src/amd_detail or /opt/rocm/lib.

HIP_INCLUDE_DIR

Path to the directory containing hip/hip_runtime_api.h. Defaults to /opt/rocm/include.

For example, to specify a custom hipFile install location when building the wheel:

python -m build --wheel \
  -Ccmake.define.HIPFILE_INCLUDE_DIR=/path/to/hipfile/include \
  -Ccmake.define.HIPFILE_LIBRARY=/path/to/lib \
  -Ccmake.define.HIP_INCLUDE_DIR=/opt/rocm/include

Or with pip install:

pip install -e . \
  -Ccmake.define.HIPFILE_INCLUDE_DIR=/path/to/hipfile/include \
  -Ccmake.define.HIPFILE_LIBRARY=/path/to/lib

Warning

If CMake cannot locate hipfile.h, libhipfile.so, or hip/hip_runtime_api.h, the build fails with a FATAL_ERROR message indicating which path to set.

Confirm the installation#

After building and installing the wheel, or using an editable install, confirm that the bindings are importable:

python -c "import hipfile; print('hipFile Python bindings loaded successfully')"
Contents