Repository files navigation

TheRock (The HIP Environment and ROCm Kit) is a lightweight open source build platform for HIP and ROCm. The project is currently in anearly preview state but is under active development and welcomes contributors. Come try us out! Please seeCONTRIBUTING.md for more info.

TheRock includes:

• Nightly releases of ROCm and PyTorch
• A CMake super-project for HIP and ROCm source builds
• Support for building PyTorch with ROCm from source
  • JAX support and other external project builds are in the works!
• Operating system support including multiple Linux distributions and native Windows
• Tools for developing individual ROCm components
• Comprehensive CI/CD pipelines for building, testing, and releasing supported components

Packages and Python wheels:

Platform	Prebuilt tarballs and ROCm Python packages	PyTorch Python packages
Linux
Windows

We keep the following instructions for recent, commonly used operating systemversions. Most build failures are due to minor operating system differences independencies and project setup. Refer to theEnvironment Setup Guide for contributedinstructions and configurations for alternatives.

# Install Ubuntu dependenciessudo apt updatesudo apt install gfortran git ninja-build cmake g++ pkg-config xxd patchelf automake libtool python3-venv python3-dev libegl1-mesa-dev# Clone the repositorygit clone https://github.com/ROCm/TheRock.gitcd TheRock# Init python virtual environment and install python dependenciespython3 -m venv .venv&&source .venv/bin/activatepip install --upgrade pippip install -r requirements.txt# Download submodules and apply patchespython3 ./build_tools/fetch_sources.py# Install python dependencies for submodulespip install -r requirements-external.txt

If the build system is a non-English system. Make sure to switch toutf-8.

chcp65001

# Install dependencies following the Windows support guide# Clone the repositorygit clone https://github.com/ROCm/TheRock.gitcd TheRock# Init python virtual environment and install python dependenciespython -m venv .venv.venv\Scripts\Activate.batpip install --upgrade pippip install -r requirements.txt# Download submodules and apply patches# Note that dvc is used for pulling large filespython ./build_tools/fetch_sources.py# Install python dependencies for submodulespip install -r requirements-external.txt

The build can be customized through cmake feature flags.

• -DTHEROCK_AMDGPU_FAMILIES=

  or

• -DTHEROCK_AMDGPU_TARGETS=

In case you don't have an existing ROCm/HIP installation from which you can run any of these tools:

You can install therocm Python package for any architecture inside a venv and runoffload-arch from there:

1. python build_tools/setup_venv.py --index-name nightly --index-subdir gfx110X-dgpu --packages rocm .tmpvenv
2. .tmpvenv/bin/offload-arch on Linux,.tmpvenv\Scripts\offload-arch on Windows
3. rm -rf .tmpvenv

By default, the project builds everything available. The following group flagsenable/disable selected subsets:

Individual features can be controlled separately (typically in combination with-DTHEROCK_ENABLE_ALL=OFF or-DTHEROCK_RESET_FEATURES=ON to force aminimal build):

By default, components are built from the sources fetched via the submodules.For some components, external sources can be used instead.

Further flags allow to build components with specific features enabled.

For workflows that demand frequent rebuilds, it isrecommended to build it with ccache enabled to speed up the build.See instructions in the next section forLinux andWindows.

Otherwise, ROCm/HIP can be configured and build with just the following commands:

cmake -B build -GNinja. -DTHEROCK_AMDGPU_FAMILIES=gfx110X-dgpucmake --build build

To build with theccache compiler cache:

• You must have a recent ccache (>= 4.11 at the time of writing) that supportsproper caching with the--offload-compress option used for compressingAMDGPU device code.
• export CCACHE_SLOPPINESS=include_file_ctime to support hard-linking
• Proper setup of thecompiler_check directive to do safe caching in thepresence of compiler bootstrapping
• Set the C/CXX compiler launcher options to cmake appropriately.

Since these options are very fiddly and prone to change over time, we recommendusing the./build_tools/setup_ccache.py script to create a.ccache directoryin the repository root with hard coded configuration suitable for the project.

Example:

# Any shell used to build must eval setup_ccache.py to set environment# variables.eval"$(./build_tools/setup_ccache.py)"cmake -B build -GNinja -DTHEROCK_AMDGPU_FAMILIES=gfx110X-dgpu \  -DCMAKE_C_COMPILER_LAUNCHER=ccache \  -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \.cmake --build build

We are still investigating the exact proper options for ccache on Windows anddo not currently recommend that end users enable it.

Project-wide testing can be controlled with the standard CMake-DBUILD_TESTING=ON|OFF flag. This gates both setup of build tests and compilation of installed testing artifacts.

Tests of the integrity of the build are enabled by default and can be runwith ctest:

ctest --test-dir build

Testing functionality on an actual GPU is in progress and will be documentedseparately.

• Contribution Guidelines: Documentation for the process of contributing to this project including a quick pointer to its governance.
• Development Guide: Documentation on how to use TheRock as a daily driver for developing any of its contained ROCm components (i.e. vs interacting with each component build individually).
• Build System: More detailed information about TheRock's build system relevant to people looking to extend TheRock, add components, etc.
• Environment Setup Guide: Comprehensive guide for setting up a build environment, known workarounds, and other operating specific information.
• Git Chores: Procedures for managing the codebase, specifically focused on version control, upstream/downstream, etc.
• Dependencies: Further specifications on ROCm-wide standards for depending on various components.
• Build Containers: Further information about containers used for building TheRock on CI.
• Build Artifacts: Documentation about the outputs of the build system.
• Releases Page: Documentation for how to leverage our build artifacts.
• Roadmap for Support: Documentation for our prioritized roadmap to support AMD GPUs.