Multi-arch pip wheel support for rocm-examples

[mapatel-amd]

Summary

The TheRock multi-arch pip wheel distribution is an available method to install ROCm. The examples repository has partial CI support for this install method (ci_therock.yml), but several pieces are missing or incomplete before we can confidently say multi-arch usage is supported end-to-end.

This issue tracks all the work needed to get there.

---

Documentation

• Add a "Installing via TheRock pip wheel" section to the top-level README.md
  explaining the per-architecture wheel families (gfx110X-all, gfx1151,
  gfx90X-dcgpu, gfx94X-dcgpu, gfx120X-all), the rocm[libraries,devel]
  meta-package, and how to set ROCM_PATH from rocm-sdk path --root

• Document required environment variables for wheel installs and why each is needed:

  export ROCM_PATH=$(rocm-sdk path --root)
  export HIP_PLATFORM=amd
  export HIP_PATH=$ROCM_PATH
  export HIP_CLANG_PATH=$ROCM_PATH/llvm/bin
  export HIP_INCLUDE_PATH=$ROCM_PATH/include
  export HIP_LIB_PATH=$ROCM_PATH/lib
  export HIP_DEVICE_LIB_PATH=$ROCM_PATH/lib/llvm/amdgcn/bitcode
  export PATH="$ROCM_PATH/bin:$HIP_CLANG_PATH:$PATH"
  export LD_LIBRARY_PATH="$HIP_LIB_PATH:$ROCM_PATH/lib:$ROCM_PATH/lib64:$ROCM_PATH/llvm/lib:${LD_LIBRARY_PATH:-}"
  export LIBRARY_PATH="$HIP_LIB_PATH:$ROCM_PATH/lib:$ROCM_PATH/lib64:${LIBRARY_PATH:-}"
  export CPATH="$HIP_INCLUDE_PATH:${CPATH:-}"
  export PKG_CONFIG_PATH="$ROCM_PATH/lib/pkgconfig:${PKG_CONFIG_PATH:-}"

• Add troubleshooting section covering hipErrorInvalidImage (kpack issues),
  missing library kernels, and how to diagnose with AMD_LOG_LEVEL=4

• Create Scripts/multiarch-testing/README.md to reflect any changes from
  the items above

Local testing / Docker

• Create a Scripts/multiarch-testing/ directory
• Add a Dockerfile under Scripts/multiarch-testing/ that installs ROCm
  via the TheRock multiarch pip wheel (parameterized by THEROCK_FAMILY) and sets all
  required environment variables, one for Ubuntu, SLES, and Rocky if not done already
• Provide a companion run-tests.sh that builds the image and runs
  CMake configure → build → ctest in a single command

CI coverage

• Add Ubuntu 24.04, Ubuntu 26.04, RHEL 10.1, Oracle Linux 10, Rocky 9 to DISTRO_MAP and workflow_dispatch options
• Populate per-arch skip lists in generate_skip_tests.py for tests that
  fail due to upstream packaging gaps, not example bugs
• Gate wheel CI jobs on rocm-sdk test and skip (not fail) if the wheel
  is broken for that arch
• Add a nightly run against the latest nightly wheel to catch packaging
  regressions early

Build system

• Audit all add_custom_command outputs for CMAKE_CURRENT_SOURCE_DIR
  paths that break read-only source mounts

Things to Note

• Documentation isn't mandatory, but would be nice

[mapatel-amd]

This branch mapatel/rocm-25114-multi-arch-ub24.04 contains all the Dockerfiles and the file to run tests with those dockerfiles. As of today's date, with those files all standard tests are passing on the distributions used in those tests, that being: Ubuntu 24.04, Ubuntu 26.04, RHEL 10.1, Rocky 9, and Oracle Linux 10.

To run the tests, go to this folder and follow instructions from the README and at the top of run-tests.sh.

Edit: #461 has been done to help with dockerfiles running properly.