ROCm/TheRock
GitHub: ROCm/TheRock
TheRock 是 AMD ROCm/HIP 的轻量级开源构建系统，通过 CMake super-project 和灵活的组件裁剪机制简化从源码编译 ROCm 及 PyTorch/JAX 的流程。
Stars: 1159 | Forks: 288
# TheRock
[](https://github.com/pre-commit/pre-commit) [](https://github.com/ROCm/TheRock/actions/workflows/multi_arch_ci.yml?query=branch%3Amain) [](https://github.com/ROCm/TheRock/actions/workflows/multi_arch_ci_asan.yml?query=branch%3Amain)
TheRock（The HIP Environment and ROCm Kit）是一个用于 HIP 和 ROCm 的轻量级开源构建平台。它专为 ROCm 贡献者，以及需要访问最新 ROCm 功能但又不想面对传统基于包安装的复杂性的开发者、研究人员和高级用户而设计。该项目目前处于**早期预览状态**，但正在积极开发中，并欢迎贡献者参与。快来体验吧！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取更多信息，并查看 [FAQ](docs/faq.md) 了解常见问题。
## 功能
TheRock 包含：
- ROCm 和 PyTorch 的每日构建（Nightly）发布
- 用于 HIP 和 ROCm 源码构建的 CMake super-project
- 支持从源码构建带有 ROCm 的 PyTorch 和 JAX
- 操作系统支持，包括多种 Linux 发行版和原生 Windows
- 用于开发各个 ROCm 组件的工具
- 用于构建、测试和发布受支持组件的全面 CI/CD pipeline
## 从发布版本安装
## 项目状态
请访问 https://therock-hud.amd.com/ 查看统一的项目 HUD
### 每日构建（Nightly）发布状态
多架构发布（所有 GPU 架构）：
| 作业描述 | 状态 |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 构建 ROCm artifacts/tarballs/packages | [](https://github.com/ROCm/rockrel/actions/workflows/multi_arch_release.yml) |
| 测试 ROCm artifacts | [](https://github.com/ROCm/rockrel/actions/workflows/test_artifacts.yml) |
| 测试 ROCm 原生 Linux packages | [](https://github.com/ROCm/rockrel/actions/workflows/test_native_linux_packages_install.yml) |
| PyTorch packages - Linux 构建/测试 | [](https://github.com/ROCm/rockrel/actions/workflows/multi_arch_release_linux_pytorch_wheels.yml) |
| PyTorch packages - Windows 构建/测试 | [](https://github.com/ROCm/rockrel/actions/workflows/multi_arch_release_windows_pytorch_wheels.yml) |
| PyTorch packages - 完整测试 | [](https://github.com/ROCm/rockrel/actions/workflows/test_pytorch_wheels_full.yml) |
| JAX packages - Linux 构建/测试 | [](https://github.com/ROCm/rockrel/actions/workflows/multi_arch_release_linux_jax_wheels.yml) |
## 从源码构建
我们为近期常用的操作系统版本保留了以下说明。大多数构建失败是由于依赖项和项目设置中的细微操作系统差异造成的。有关替代方案的贡献说明和配置，请参阅[环境设置指南](docs/environment_setup_guide.md)。
### 设置 - Ubuntu (24.04)
```
# 安装 Ubuntu 依赖
sudo apt update
sudo apt install gfortran git ninja-build cmake g++ pkg-config xxd automake libtool python3-venv python3-dev libegl1-mesa-dev texinfo bison flex
# 克隆仓库
git clone https://github.com/ROCm/TheRock.git
cd TheRock
# 从源码安装打过补丁的 patchelf。详情请参见
# https://github.com/ROCm/TheRock/blob/main/docs/environment_setup_guide.md#patchelf
sudo apt install curl make
sudo env INSTALL_PREFIX=/usr/local ./dockerfiles/install_pinned_patchelf.sh
# 初始化 python 虚拟环境并安装 python 依赖
python3 -m venv .venv && source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
# 下载 submodules 并应用补丁
python3 ./build_tools/fetch_sources.py
```
### 设置 - Windows 11 (VS 2022)
如果构建系统是非英语系统，请确保切换到 `utf-8`。
```
chcp 65001
```
```
# 按照 Windows 支持指南安装依赖
# 克隆仓库
git clone https://github.com/ROCm/TheRock.git
cd TheRock
# 初始化 python 虚拟环境并安装 python 依赖
python -m venv .venv
.venv\Scripts\Activate.bat
pip install --upgrade pip
pip install -r requirements.txt
# 下载 submodules 并应用补丁
# 请注意，dvc 用于拉取大文件
python ./build_tools/fetch_sources.py
```
### 构建配置
可以通过 cmake feature flags 自定义构建。
#### 必需的配置标志
- `-DTHEROCK_AMDGPU_FAMILIES=`
或
- `-DTHEROCK_AMDGPU_TARGETS=`
#### 发现系统上可用的 target
如果您没有现成的 ROCm/HIP 安装来运行这些工具：
| 工具 | 平台 |
| ----------------------- | -------- |
| `amd-smi` | Linux |
| `rocm-smi` | Linux |
| `rocm_agent_enumerator` | Linux |
| `hipinfo` | Windows |
| `offload-arch` | 两者 |
您可以在 venv 中为任何架构安装 `rocm` Python package，并从那里运行 `offload-arch`：
1. `python build_tools/setup_venv.py --index-name nightly --packages rocm .tmpvenv`
2. Linux 上运行 `.tmpvenv/bin/offload-arch`，Windows 上运行 `.tmpvenv\Scripts\offload-arch`
3. `rm -rf .tmpvenv`
#### 可选配置标志
默认情况下，该项目会构建所有可用的内容。以下组标志可以启用/禁用选定的子集：
| 组标志 | 描述 |
| ---------------------------------- | ------------------------------------ |
| `-DTHEROCK_ENABLE_ALL=OFF` | 禁用所有可选组件 |
| `-DTHEROCK_ENABLE_CORE=OFF` | 禁用所有核心组件 |
| `-DTHEROCK_ENABLE_COMM_LIBS=OFF` | 禁用所有通信库 |
| `-DTHEROCK_ENABLE_DEBUG_TOOLS=OFF` | 禁用所有调试工具 |
| `-DTHEROCK_ENABLE_MATH_LIBS=OFF` | 禁用所有数学库 |
| `-DTHEROCK_ENABLE_ML_LIBS=OFF` | 禁用所有 ML 库 |
| `-DTHEROCK_ENABLE_PROFILER=OFF` | 禁用 profiler |
| `-DTHEROCK_ENABLE_DC_TOOLS=OFF` | 禁用数据中心工具 |
| `-DTHEROCK_ENABLE_MEDIA_LIBS=OFF` | 禁用所有媒体库 |
| `-DTHEROCK_ENABLE_WSL=ON` | 启用 WSL 特定的 artifacts |
| `-DTHEROCK_ENABLE_EMULATION=ON` | 启用仿真工具 |
可以单独控制各个功能（通常与 `-DTHEROCK_ENABLE_ALL=OFF` 或 `-DTHEROCK_RESET_FEATURES=ON` 结合使用以强制进行最小化构建）：
| 组件标志 | 描述 |
| -------------------------------------- | --------------------------------------------------- |
| `-DTHEROCK_ENABLE_AMD_DBGAPI=ON` | 启用 ROCm 调试 API 库 |
| `-DTHEROCK_ENABLE_COMPILER=ON` | 启用 GPU+主机编译器工具链 |
| `-DTHEROCK_ENABLE_CORE_AMDSMI=ON` | 启用 AMD System Management Interface 库 |
| `-DTHEROCK_ENABLE_HIPIFY=ON` | 启用 hipify 工具 |
| `-DTHEROCK_ENABLE_CORE_RUNTIME=ON` | 启用核心 runtime 组件和工具 |
| `-DTHEROCK_ENABLE_HIP_RUNTIME=ON` | 启用 HIP runtime 组件 |
| `-DTHEROCK_ENABLE_OCL_RUNTIME=ON` | 启用 OpenCL runtime 组件 |
| `-DTHEROCK_ENABLE_WSL_ROCDXG=ON` | 启用 WSL ROCDXG 桥接库 |
| `-DTHEROCK_ENABLE_ROCGDB=ON` | 启用 ROCm 调试器 (ROCgdb) |
| `-DTHEROCK_ENABLE_ROCPROFV3=ON` | 启用 rocprofv3 |
| `-DTHEROCK_ENABLE_ROCPROFSYS=ON` | 启用 rocprofiler-systems |
| `-DTHEROCK_ENABLE_RCCL=ON` | 启用 RCCL |
| `-DTHEROCK_ENABLE_ROCSHMEM=ON` | 启用 rocSHMEM |
| `-DTHEROCK_ENABLE_HIPFILE=ON` | 启用 hipFile |
| `-DTHEROCK_ENABLE_ROCR_DEBUG_AGENT=ON` | 启用 ROCR 调试代理库 |
| `-DTHEROCK_ENABLE_PRIM=ON` | 启用 PRIM 库 |
| `-DTHEROCK_ENABLE_BLAS=ON` | 启用 BLAS 库 |
| `-DTHEROCK_ENABLE_RAND=ON` | 启用 RAND 库 |
| `-DTHEROCK_ENABLE_SOLVER=ON` | 启用 SOLVER 库 |
| `-DTHEROCK_ENABLE_SPARSE=ON` | 启用 SPARSE 库 |
| `-DTHEROCK_ENABLE_MIOPEN=ON` | 启用 MIOpen |
| `-DTHEROCK_ENABLE_MIOPEN_PLUGIN=ON` | 启用 MIOpen_plugin |
| `-DTHEROCK_ENABLE_HIPDNN_SAMPLES=ON` | 启用 hipDNN 示例 (hipDNN 使用示例) |
| `-DTHEROCK_ENABLE_HIPDNN=ON` | 启用 hipDNN |
| `-DTHEROCK_ENABLE_HIPTENSOR=ON` | 启用 hipTensor |
| `-DTHEROCK_ENABLE_HIPBLASLT_PLUGIN=ON` | 启用 hipBLASLt Plugin |
| `-DTHEROCK_ENABLE_ROCWMMA=ON` | 启用 rocWMMA |
| `-DTHEROCK_ENABLE_ROCALUTION=ON` | 启用 rocALUTION |
| `-DTHEROCK_ENABLE_RDC=ON` | 启用 ROCm 数据中心工具 (仅限 Linux) |
| `-DTHEROCK_ENABLE_LIBHIPCXX=ON` | 启用 libhipcxx |
| `-DTHEROCK_ENABLE_SYSDEPS_AMD_MESA=ON` | 启用用于媒体库的 AMD Mesa (仅限 Linux) |
| `-DTHEROCK_ENABLE_ROCDECODE=ON` | 启用 rocDecode 视频解码器 (仅限 Linux) |
| `-DTHEROCK_ENABLE_ROCJPEG=ON` | 启用 rocJPEG JPEG 解码器 (仅限 Linux) |
| `-DTHEROCK_ENABLE_ROCJITSU=ON` | 启用 ROCm 仿真工具 (仅限 Linux) |
hipDNN provider 插件：
| Provider 标志 | 描述 |
| --------------------------------------- | ----------------------------------------- |
| `-DTHEROCK_ENABLE_MIOPENPROVIDER=ON` | 启用 hipDNN MIOpen-provider 插件 |
| `-DTHEROCK_ENABLE_HIPBLASLTPROVIDER=ON` | 启用 hipDNN hipBLASLt-provider 插件 |
| `-DTHEROCK_ENABLE_HIPKERNELPROVIDER=ON` | 启用 hipDNN hip kernel provider 插件 |
默认情况下，组件是通过 submodules 获取的源代码进行构建的。对于某些组件，可以通过设置以下两个选项来使用外部源代码：
| 外部源码设置 | 描述 |
| ------------------------------------------------ | ------------------------------------------------------- |
| `-DTHEROCK_USE_EXTERNAL_=OFF` | 启用/禁用组件的外部源代码位置 |
| `-DTHEROCK__SOURCE_DIR=` | 组件源代码的外部路径 |
以下组件允许指定备用源码位置：
| Component string |
| ------------------- |
| `COMPOSABLE_KERNEL` |
| `ROCGDB` |
其他标志允许在构建组件时启用特定功能。
| 其他标志 | 描述 |
| ------------------------------------------------- | ------------------------------------------------------------------------ |
| `-DTHEROCK_ENABLE_MPI=OFF` | 启用构建支持 Message Passing Interface (MPI) 的组件 |
| `-DTHEROCK_COMPOSABLE_KERNEL_FOR_MIOPEN_ONLY=OFF` | 仅构建 MIOpen 所需的 target 来构建 composable_kernel |
### CMake 构建用法
对于需要频繁重建的工作流，_建议在启用 ccache 的情况下进行构建_ 以加快构建速度。请参阅下一节中关于 [Linux](#ccache-usage-on-linux) 和 [Windows](#ccache-usage-on-windows) 的说明。
否则，只需使用以下命令即可配置和构建 ROCm/HIP：
```
cmake -B build -GNinja . -DTHEROCK_AMDGPU_FAMILIES=gfx110X-all
cmake --build build
```
#### 在 Linux 上使用 CCache
要使用 [ccache](https://ccache.dev/) 编译器缓存进行构建：
- 您必须拥有最新的 ccache（撰写本文时为 >= 4.11），以支持通过 `--offload-compress` 选项对 AMDGPU 设备代码进行压缩和正确缓存。
- `export CCACHE_SLOPPINESS=include_file_ctime` 以支持硬链接
- 正确设置 `compiler_check` 指令，以便在存在编译器引导（bootstrapping）的情况下进行安全缓存
- 适当设置 CMake 的 C/CXX 编译器启动器选项。
由于这些选项非常繁琐且容易随时间发生变化，我们建议使用 `./build_tools/setup_ccache.py` 脚在仓库根目录中创建一个 `.ccache` 目录，其中包含适合该项目的硬编码配置。
示例：
```
# 任何用于构建的 shell 必须执行 eval setup_ccache.py 来设置环境
# 变量。
eval "$(./build_tools/setup_ccache.py)"
cmake -B build -GNinja -DTHEROCK_AMDGPU_FAMILIES=gfx110X-all \
-DCMAKE_C_COMPILER_LAUNCHER=ccache \
-DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
.
cmake --build build
```
#### 在 Windows 上使用 CCache
- 您必须拥有最新的 ccache（撰写本文时为 >= 4.13.3），其中包含针对 MSVC 的错误修复，并支持通过 `--offload-compress` 选项对 AMDGPU 设备代码进行压缩和正确缓存。
- `export CCACHE_SLOPPINESS=include_file_ctime,pch_defines,time_macros` 以支持硬链接和预编译头（amd-llvm 是使用 PCH 构建的）。
- 正确设置 `compiler_check` 指令，以便在存在编译器引导（bootstrapping）的情况下进行安全缓存。
- 适当设置 CMake 的 C/CXX 编译器启动器选项。
由于这些选项非常繁琐且容易随时间发生变化，我们建议使用 `./build_tools/setup_ccache.py` 脚本在仓库根目录中创建一个 `.ccache` 目录，其中包含适合该项目的硬编码配置。
示例（在命令提示符中）：
```
# 任何用于构建的命令提示符必须执行 eval setup_ccache.py 来设置环境
# 变量。
for /f "delims=" %i in ('python build_tools/setup_ccache.py') do @%i
cmake -B build -GNinja -DTHEROCK_AMDGPU_FAMILIES=gfx110X-all \
-DCMAKE_C_COMPILER_LAUNCHER=ccache ^
-DCMAKE_CXX_COMPILER_LAUNCHER=ccache ^
.
cmake --build build
```
### 运行测试
全项目测试可以通过标准的 CMake `-DBUILD_TESTING=ON|OFF` 标志进行控制。这控制了构建测试的设置以及已安装测试 artifact 的编译。
构建完整性测试默认启用，可以使用 ctest 运行：
```
ctest --test-dir build
```
在实际 GPU 上测试功能的工作正在进行中，并将单独记录。
## 开发手册
- [FAQ](docs/faq.md)：TheRock 用户的常见问题。
- [贡献指南](CONTRIBUTING.md)：关于为该项目做贡献的流程文档，包括对其治理的快速指引。
- [开发指南](docs/development/development_guide.md)：关于如何将 TheRock 作为日常工具来开发其包含的任何 ROCm 组件的文档（即与单独构建每个组件进行交互）。
- [构建系统](docs/development/build_system.md)：与希望扩展 TheRock、添加组件等人员相关的 TheRock 构建系统的更多详细信息。
- [环境设置指南](docs/environment_setup_guide.md)：设置构建环境、已知解决方法和其他操作系统特定信息的综合指南。
- [Git 常规事务](docs/development/git_chores.md)：管理代码库的程序，特别侧重于版本控制、上游/下游等。
- [依赖项](docs/development/dependencies.md)：关于依赖各种组件的 ROCm 广泛标准的进一步规范。
- [TheRock 的 Dockerfiles](dockerfiles/README.md)：有关使用 TheRock 构建、测试和分发 ROCm 的容器的信息。
- [构建 Artifacts](docs/development/artifacts.md)：有关构建系统输出的文档。
- [发布页面](RELEASES.md)：关于如何利用我们的构建 artifacts 的文档。
- [受支持的 GPU](SUPPORTED_GPUS.md)：每种 AMD GPU 架构的当前支持状态和优先路线图。
标签：Bash脚本, CMake, GPU计算, HIP, JAX, PyTorch, ROCm, 凭据扫描, 安全工具测试, 构建系统, 系统工具, 逆向工具