README.md

# DTK Local Overrides

维护需要覆盖到 DTK 软件栈目录 `DTK_HOME=/opt/dtk` 中的修改版文件。目录下的相对路径一般来说和 `$DTK_HOME` 下的相对路径保持一致。

例如：

```text
./hip/lib/cmake/hip/hip-config.cmake
```

会覆盖容器中的：

```text
/opt/dtk/hip/lib/cmake/hip/hip-config.cmake
```

## 安装方式

把本目录下载到容器中，进入目录后执行：

```sh
./install.sh
```

安装前会为已存在的目标文件生成带时间戳的 `.bak.*` 备份。

## 可直接覆盖的文件

这部分记录可以直接覆盖到 DTK 软件栈中的文件，这些文件在目录中的相对路径和 `$DTK_HOME` 下的相对路径一致。

### `hip/lib/cmake/hip/hip-config.cmake`

| 类型 | 路径 |
| --- | --- |
| 来源文件 | `hip/lib/cmake/hip/hip-config.cmake` |
| 原始备份 | `hip/lib/cmake/hip/hip-config.cmake.orig` |
| 历史修正版 | `hip/lib/cmake/hip/hip-config.cmake.patched` |
| 目标文件 | `$DTK_HOME/hip/lib/cmake/hip/hip-config.cmake` |

> 参考：[ROCm 7 hipamd](https://github.com/ROCm/rocm-systems/tree/therock-7.13/projects/clr/hipamd)

修复内容：

1. 基于 ROCm 7 最新 `hip-config.cmake.in` 生成 `hip-config.cmake`。

   `.cmake.in` 中的 `@PACKAGE_INIT@`、安装路径、`HIP_INSTALLS_HIPCC` 等 configure-time 占位符按当前 DTK 容器布局展开。

2. 保留 ROCm 的平台检测入口。

   当前 DTK 的 `hipconfig --platform` 输出为 `amd`，因此主配置在 `HIP_PLATFORM STREQUAL "amd"` 分支中会加载适配后的子配置：

   ```text
   hip-config-amd.cmake
   ```

### `hip/lib/cmake/hip/hip-config-amd.cmake`

| 类型 | 路径 |
| --- | --- |
| 来源文件 | `hip/lib/cmake/hip/hip-config-amd.cmake` |
| ROCm 参考 | `rocm-references/hip-config-amd.cmake.in` |
| 目标文件 | `$DTK_HOME/hip/lib/cmake/hip/hip-config-amd.cmake` |

修复内容：

1. 按 DTK 容器布局设置默认 `ROCM_PATH`。

   ROCm 7 默认把 `ROCM_PATH` 设为 HIP package prefix。当前 DTK 中 HIP package prefix 是 `/opt/dtk/hip`，而 LLVM、device libs、`amdgpu-arch` 等组件位于 `/opt/dtk` 下。因此本文件在未显式设置 `ROCM_PATH` 时使用：

   ```text
   ${PACKAGE_PREFIX_DIR}/..
   ```

2. 不再硬编码多组 GPU targets。

   DTK 原始文件默认设置：

   ```text
   gfx906;gfx926;gfx928;gfx936;gfx938
   ```

   现在沿用 ROCm 逻辑：优先使用 `GPU_TARGETS`，兼容旧变量 `AMDGPU_TARGETS`；如果没有显式设置，则通过 `$ROCM_PATH/llvm/bin/amdgpu-arch` 自动检测。例如容器中该检测结果可能是 `gfx936`，避免 device link 阶段混入多组 target。

3. 限制 `hip::device` 的 HIP 编译选项只作用于 CXX 语言。

   DTK 原始文件将 `-xhip` 和 `--offload-arch=...` 无条件挂到 `hip::device` 的 `INTERFACE_COMPILE_OPTIONS` 上。Trilinos 通过 `Kokkos::kokkos -> roc::rocthrust -> roc::rocprim_hip -> hip::device` 继承这些选项后，legacy C target 也会带上 HIP 编译参数，导致 Ifpack/ML/Tpetra/Sacado 等 `.c` 文件被按 HIP/C++ 编译。

   现在沿用 ROCm 的 helper，通过 CMake 生成表达式把这些选项限制到 `CXX` 编译语言，避免污染 C target。

### `hip/lib/cmake/hip/hip-config-nvidia.cmake`

| 类型 | 路径 |
| --- | --- |
| 来源文件 | `hip/lib/cmake/hip/hip-config-nvidia.cmake` |
| ROCm 参考 | `rocm-references/hip-config-nvidia.cmake.in` |
| 目标文件 | `$DTK_HOME/hip/lib/cmake/hip/hip-config-nvidia.cmake` |

当前 DTK 适配不使用 NVIDIA 分支，但 `hip-config.cmake` 保留了 `HIP_PLATFORM STREQUAL "nvidia"` 时加载该文件的路径。为了便于和上游同步，本文件也随 overlay 一起安装。

该文件来自 ROCm 7 的 `hip-config-nvidia.cmake.in`，只将 `@PACKAGE_INCLUDE_INSTALL_DIR@` 展开为：

```text
${HIP_PACKAGE_PREFIX_DIR}/include
```

## 非直接覆盖的文件

这部分记录不能按相同相对路径直接覆盖的文件。例如源文件是本地工具脚本，安装时会生成 DTK 目录中的一个或多个命令入口。

### `tools/dtk-amdclang-wrapper`

| 类型 | 路径 |
| --- | --- |
| 来源文件 | `tools/dtk-amdclang-wrapper` |
| 目标文件 | `$DTK_HOME/llvm/bin/amdclang` |
| 目标文件 | `$DTK_HOME/llvm/bin/amdclang++` |

修复内容：

Spack ROCm/CMake HIP language 可能会给 `amdclang++` 传入：

```text
--gcc-toolchain=/opt/dtk/llvm
```

但 `/opt/dtk/llvm` 是 DTK LLVM/DCC 前缀，不是系统 GCC toolchain 前缀，这会导致 host 侧 C++ 标准库头文件查找失败，例如：

```text
fatal error: 'cmath' file not found
```

该 wrapper 安装为 `$DTK_HOME/llvm/bin/amdclang` 和 `$DTK_HOME/llvm/bin/amdclang++`，默认转发到：

```text
/opt/dtk/llvm/bin/dcc
```

转发时改写参数 `--gcc-toolchain=/opt/dtk/llvm` 为 `--gcc-toolchain=/usr`。