TheRock/rocm-libraries/dnn-providers/hip-kernel-provider/rocke/BUILDING.md

Building & running rocke

rocke/ has two Python source roots:

Root	Packages	Installed in product?
platform/python	rocke (authoring SDK + engine frontend)	yes (wheel / CMake)
library	kernels, builders, dispatch (SDPA/MHA)	no — build-time only

The package import name is rocke; the SDPA product lives under separate top-level packages. Because the two halves sit under different roots, every process that touches both needs both roots resolvable.

We do not scatter sys.path surgery across scripts. Instead both roots are editable-installed once into an environment, after which rocke, kernels, builders, and dispatch import normally everywhere — scripts, -m module runs, and pytest — from any working directory, with no PYTHONPATH.

The only remaining filesystem lookups in the tree are for genuine non-package data (the dsl_docs/ tree and the loose _ua_shape_utils benchmark helper). Those resolve through rocke.assets (platform_root(), dsl_docs_dir(), shape_utils_dir()), with the roots overridable via ROCKE_PLATFORM_ROOT / ROCKE_DSL_DOCS (shape_utils_dir() derives from dsl_docs_dir()) — never via per-file parents[N] math.

Quick start (CMake-managed environment)

When the rocke features are enabled, the build creates and maintains the editable environment for you:

cmake -S dnn-providers/hip-kernel-provider -B build \
      -DHIPKERNELPROVIDER_ENABLE_ROCKE=ON
cmake --build build            # also builds the `rocke-pyenv` target

This produces build/rocke-pyenv/, a virtualenv with platform and library editable-installed. Use it directly:

build/rocke-pyenv/bin/python -m builders.gfx950.attention.benchmark_prefill2d_live --help
build/rocke-pyenv/bin/python -m pytest rocke/library/tests

Properties:

• Always current. Editable installs point at live source, so editing a .py needs no reinstall. The install only re-runs when a pyproject.toml changes (the build gates it on a stamp), e.g. when a new top-level package is added.
• Hermetic. Everything lands in build/rocke-pyenv/, never your system or user site-packages — so the generic names kernels / builders / dispatch are confined to this venv.
• Inherits system torch. The venv is created with --system-site-packages, so the ROCm PyTorch you already have is reused, not reinstalled.

Toggle off with -DROCKE_BUILD_PYENV=OFF if you manage the environment yourself.

Manual setup (your own venv)

Equivalent to what CMake does, for editing/running outside the build:

python3 -m venv --system-site-packages .venv
. .venv/bin/activate
pip install --upgrade pip "setuptools>=61" wheel
# editable_mode=compat writes a .pth at the source root so newly added modules
# are importable without reinstalling.
pip install --config-settings editable_mode=compat -e rocke/platform
pip install --config-settings editable_mode=compat --no-deps -e rocke/library

Order matters: platform first (it provides the rocke distribution that rocke-library depends on); library with --no-deps so pip resolves rocke from the local editable install rather than an index.

After this, from any directory:

python -c "import rocke, kernels, builders, dispatch"   # all resolve
python -m builders.gfx942.attention.parity_unified_attention --help
pytest rocke/library/tests

ROCm PyTorch must come from the ROCm wheel index for your system (see platform/requirements.txt / platform/BUILD.md); it is not installed here.

Daily loop

1. One-time: build (CMake makes the venv) or run the manual setup.
2. Edit any .py under platform/python/rocke/ or library/ — changes are live, no reinstall.
3. Run scripts/tests against the venv interpreter.
4. Re-run the install only after adding a new top-level package or changing a pyproject.toml. Under CMake this happens automatically (the stamp depends on both pyproject.toml files).

Running the full test sweep

The sweep needs the test/heuristics extras plus a ROCm PyTorch:

# test runner + heuristics ML deps (pytest, pytest-subtests, pandas,
# scikit-learn, lightgbm) come from the platform `dev` extra:
pip install --config-settings editable_mode=compat -e "rocke/platform[dev]"
pip install --config-settings editable_mode=compat --no-deps -e rocke/library
# torch: ROCm build for your system (see platform/requirements.txt). A CPU
# torch lets the non-GPU suite import/run; GPU tests then skip without a device.

pytest rocke/platform/tests rocke/library/tests

Expected residual on a box whose /opt/rocm clang is a different LLVM vintage than rocke's hardcoded datalayout constants: the 7 TestDatalayoutDriftGuard::test_datalayout_matches_hipcc_emitted_ir subtests fail with an e-m: datalayout diff. This is a toolchain-vs-constant drift the guard is designed to catch (regenerate _DATALAYOUT_* in core/lower_llvm.py for the local toolchain) — it is independent of the platform/library layout and reproduces identically on develop.

One more layout-independent residual appears only when the C++ engine is not built (a pure-pip/Python-fallback checkout, as above): test_rocke_ci_static.py::TestIrParityCoverage::test_ir_cases_match_golden_sha256 reports IR drift for 6 conv/* cases. The golden hashes track the C++ engine's output; #8841 (cshuffle) changed the Python lowerer's conv epilogue IR, so the Python-fallback hashes differ until the goldens are regenerated. Like the datalayout guard it reproduces identically on develop and is unrelated to the platform/library split — build the C++ engine (platform/cpp/) to run this test against its intended baseline. Everything else is green; GPU-only tests skip without a device.

Data / asset paths

Non-package assets are located through rocke.assets, not path math:

from rocke.assets import platform_root, dsl_docs_dir, shape_utils_dir

Override the roots for out-of-tree consumption with ROCKE_PLATFORM_ROOT, ROCKE_DSL_DOCS.

C++ engine

The platform C++ engine (platform/cpp/ → librocke_core.a) and its rocke_engine pybind binding are built by CMake, not pip, and are intentionally not part of any wheel. See platform/BUILD.md.