ROCm Ubuntu 版本选择器机制解析：从条件化文档指令到 apt 安装实战
【免费下载链接】legacy-rocm-buildAMD ROCm™ Software - GitHub Home项目地址: https://gitcode.com/GitHub_Trending/ro/legacy-rocm-build
本文以 AMD ROCm 官方文档仓库（legacy-rocm-build）中的 ubuntu-ver-selector.rst 为切入点，剖析 ROCm 安装文档中"按 GPU 型号与设备家族动态呈现 Ubuntu 版本选项"的条件化文档机制，并延伸到仓库中真实的安装命令、仓库源配置与 Python 版本要求。读完本文，你将理解这套选择器的指令语法、状态流转与持久化原理，并能据此为不同 Ubuntu 版本（26.04 / 24.04 / 22.04）的 ROCm 环境完成从仓库注册到apt install amdrocm7.14的完整安装。
Ubuntu 版本选择器在 ROCm 安装流程中的位置
ROCm 的安装主文档 rocm.rst 通过一系列include指令将选择器拆分为多个独立文件，组装成一个层层递进的交互式安装向导：
- 设备家族（Device family）：
fam（instinct/radeon/ryzen/all），见 fam-multi-arch-selector.rst； - 操作系统发行版（Linux distribution）：
os（ubuntu/debian/rhel等），见 os-selector.rst； - GPU 型号：
gpu（如mi355x、mi300x、rx-9070-xt等），见 gpu-selector.rst； - Ubuntu 版本（本文主角）：
ubuntu-ver，即 ubuntu-ver-selector.rst； - 安装方式：
i（pkgman/pip/tar/runfile），见 install-method-selector.rst。
也就是说，ubuntu-ver是用户选定"操作系统 = Ubuntu"之后的下一个细分维度，其最终选择结果会反过来驱动安装章节（200-install.rst）中仓库源 URL、内核驱动与 Python 版本等内容的显隐。
条件化指令语法：selected/selector/selector-option
ubuntu-ver-selector.rst全部由三个 Sphinx 自定义指令构成，它们在 selector/init.py 中注册并渲染：
.. selected:: 条件：声明"仅当条件满足时，其内部内容才可见"。os=ubuntu与fam=instinct可以嵌套，形成os=ubuntu且fam=instinct的叠加条件；.. selector:: 标题：渲染一个选择器组（一组可点击的选项块），核心参数：:key:：该组选项写入全局状态所用的键名。这里统一为ubuntu-ver，经 utils.py 的normalize_key()处理：空格转下划线、转小写、去首尾空白；:show-cond:：该组整体何时可见，例如gpu=mi355x gpu=mi350x ...（空格分隔的多值即"任一匹配"）；
.. selector-option:: 显示文本：单个可选项，常用参数：:value:：选择后写入状态的值（如26.04、24.04、22.04）；:show-cond:：该选项的显示条件；:width:：选项块的栅格宽度，可为 1–12 的整数（对应 Bootstrapcol-N）或百分比字符串（如50%）。源码中_parse_width()（selector/init.py）负责校验：整数越界或百分比不在 (0,100] 时会告警并回退到默认值 6。
关键语义：show-cond的多值匹配
指令中形如:show-cond: gpu=mi355x gpu=mi350x gpu=mi325x的写法，会被 utils.py 的kv_to_data_attr()解析为 JSON 对象：
{"gpu": ["mi355x", "mi350x", "mi325x"]}并写入data-show-cond属性。前端 selector.js 的matchesConditions()在匹配数组值时采用"任一命中即满足"的语义，因此该条件等价于"GPU 属于 mi355x / mi350x / mi325x 之一时显示"。
不同设备家族下的 Ubuntu 版本矩阵
把 ubuntu-ver-selector.rst 按selected分支拆解，可以得到完整的版本矩阵：
| 设备家族分支 | 可见 GPU 条件 | 可选 Ubuntu 版本 |
|---|---|---|
fam=instinct（第一组） | mi355x / mi350x / mi325x / mi300x / mi300a / mi250x / mi250 / mi210 / mi100 | 26.04、24.04.4（24.04）、22.04.5（22.04） |
fam=instinct（mi350p 专属） | gpu=mi350p | 26.04、24.04.4 |
fam=radeon/fam=all（图形工作负载w=graphics） | — | 26.04、24.04.4 |
fam=radeon/fam=all（计算工作负载w=compute） | — | 26.04、24.04.4、22.04.5 |
fam=ryzen | — | 26.04、24.04 |
os=wsl（WSL2 分支） | fam=radeon | Ubuntu 26.04 / 24.04 / 22.04 |
os=wsl（WSL2 分支） | fam=ryzen | Ubuntu 26.04 / 24.04 |
从矩阵可以归纳出三条值得注意的规则：
- 22.04 的适用范围最窄：它只出现在 Instinct 计算负载与 Radeon/All 的计算负载分支中，且从不出现在 Ryzen 与
mi350p分支——这反映旧版本 LTS 与较新硬件（如 MI350 系列）之间的支持边界； w=graphics与w=compute的版本集合不同：图形工作负载分支没有 22.04，而计算分支保留了三代 LTS 选项；- 同一
:key: ubuntu-ver在多个分支重复出现：前端源码中专门为"多个选择器组共享同一 key"（如gpu、ubuntu-ver）设计了处理逻辑，保证任一分支的选择都会统一写入同一个状态键。
版本选择如何传导到真实安装命令
选择器本身只是文档的"外壳"，其价值在于驱动 200-install.rst 中每个版本的差异化内容。以下是ubuntu-ver三个取值对应的真实仓库证据。
1. ROCm 软件仓库源（apt 源）按版本区分
选择 26.04 / 24.04 / 22.04 后，仓库注册命令中repo.amd.com的路径段分别变为ubuntu2604/ubuntu2404/ubuntu2204，例如 24.04（noble）：
# Download and install GPG key sudo mkdir --parents --mode=0755 /etc/apt/keyrings wget https://repo.amd.com/rocm/packages-multi-arch/gpg/rocm.gpg -O - | \ gpg --dearmor | sudo tee /etc/apt/keyrings/amdrocm.gpg > /dev/null sudo tee /etc/apt/sources.list.d/rocm.list << EOF deb [arch=amd64 signed-by=/etc/apt/keyrings/amdrocm.gpg] https://repo.amd.com/rocm/packages-multi-arch/ubuntu2404 stable main EOF sudo apt update26.04 对应ubuntu2604源，22.04 对应ubuntu2204源，命令结构完全一致，仅路径段不同。
2. 核心元包：amdrocm7.14
注册仓库后，安装命令与 GPU 型号（gfx状态）联动：
# fam=all（通用核心包） sudo apt install amdrocm7.14 # 按 GPU 架构安装对应元包（示例） sudo apt install amdrocm7.14-gfx942 # 对应 MI300 系列 sudo apt install amdrocm7.14-gfx90a # 对应 MI250 系列 sudo apt install amdrocm7.14-gfx1100 # 对应 Radeon RX 7000 系列 sudo apt install amdrocm7.14-gfx1151 # 对应 Ryzen AI APU3. pip 安装路径下的 Python 版本要求
若选择pip安装方式，100-prerequisites.rst 按ubuntu-ver给出不同的受支持 Python 版本：
| Ubuntu 版本 | 推荐 Python | 安装命令 |
|---|---|---|
| 26.04 | Python 3.14 | sudo apt install python3.14 python3.14-venv |
| 24.04 | Python 3.12 | sudo apt install python3.12 python3.12-venv |
| 22.04 | Python 3.11 | sudo apt install python3.11 python3.11-venv |
4. Ryzen APU 的 OEM 内核要求
对 Ryzen 家族且ubuntu-ver=24.04的安装，文档要求安装 OEM 内核 6.14：
sudo apt update && sudo apt install linux-oem-24.04c安装后必须重启系统。这一要求同时出现在计算负载与图形负载两个分支中，仅针对 24.04 生效。
5. 图形工作负载的amdgpu-install脚本
选择w=graphics且os=ubuntu时，需要先安装amdgpu-install脚本，其.deb包按 Ubuntu 版本使用不同的代号目录：26.04 对应resolute、24.04 对应noble、22.04 对应jammy（31.40.1版本示例）：
sudo apt update wget https://repo.radeon.com/amdgpu-install/31.40.1/ubuntu/noble/amdgpu-install_31.40.1.314001-1_all.deb sudo apt install ./amdgpu-install_31.40.1.314001-1_all.deb安装前必备项与 GPU 权限配置
无论选择哪个 Ubuntu 版本，100-prerequisites.rst 都要求完成两项准备工作：
安装依赖库：部分 ROCm 工具依赖
libatomic与libquadmath，在 Ubuntu 上执行：sudo apt install libatomic1 libquadmath0配置 GPU 访问权限，二选一：
组员方式（默认）：将当前用户加入
video与render组：sudo usermod -a -G render,video $LOGNAMEudev 规则方式（系统级、免用户组管理）：
sudo tee /etc/udev/rules.d/70-amdgpu.rules << EOF KERNEL=="kfd", GROUP="render", MODE="0666" SUBSYSTEM=="drm", KERNEL=="renderD*", GROUP="render", MODE="0666" EOF sudo udevadm control --reload-rules sudo udevadm trigger
修改后需重启系统使配置生效。
选择器引擎的源码级实现
这套交互式选择器并非静态文档，而是由仓库自研的 Sphinx 扩展（docs/extension/rocm_docs_custom/selector/）驱动。理解其实现有助于解释选择器行为的"为什么"。
指令层：setup()注册与节点渲染
selector/init.py 的setup()注册了 5 个指令：selector、selector-dropdown、selector-info、selector-option、selected-content（以及别名selected）。几个值得注意的实现细节：
- 默认选项自动兜底：若一组选项中没有显式标记
:default:，则第一个选项被自动设为默认（option_nodes[0]["default"] = True）； - 值可携带额外绑定：
selector-option的:value:支持"mi355x gfx=gfx950 arch=cdna3"这种"裸值 + 若干key=value"的写法，前者是选项自身值，后者在选择该选项时作为额外状态注入（代码注释明确解释了这一点）——这也是gpu等键会在多个选择器组间共享的机制基础； - 宽度校验：
_parse_width()接受 1–12 的整数或百分比，非法值回退为 6。
前端状态机：selector.js
selector/static/selector.js 实现了完整的客户端状态管理：
- 全局状态对象
state：以key → value保存所有选择器当前值； - 状态持久化与优先级：初始化时按
URL 查询参数 > localStorage > 默认值合并状态，因此"安装环境"的选择可以复制 URL 分享、也能跨页面记住；同时会把当前页面上不存在的陈旧状态键立即清除； - URL 同步：
syncStateToURL()通过history.replaceState把选择写入 URL 查询串（如?os=ubuntu&fam=instinct&gpu=mi300x&ubuntu-ver=24.04），方便搜索引擎与用户收藏精确的安装组合； - 可见性收敛循环：
updateVisibility()内使用MAX_VISIBILITY_CYCLES = 5防止无限循环，反复执行"按show-cond显示/隐藏 → 重新调和各组选中项 → 重算额外绑定"直到状态稳定； - 自动换选：
reconcileGroupSelections()保证每个可见组始终有一个合法选中项——当高层级选择使当前选中项被禁用/隐藏时，会按"持久化状态值 → 默认项 → 第一个可用项"的顺序自动替换； - 无障碍支持：选项块以
role="radiogroup"/role="radio"渲染，支持tabindex与 Enter/Space 键盘操作，隐藏元素带aria-hidden。
辅助工具：utils.py
utils.py 中的两个纯函数是所有指令的基石：
normalize_key(key)：key.replace(" ", "_").lower().strip()，保证所有键名规范统一；kv_to_data_attr(name, kv_str)：把"gpu=mi355x gpu=mi350x"这类空格分隔的键值对转换为 JSON 字符串并写入data-show-cond属性，供前端解析匹配。
小结
ubuntu-ver-selector.rst表面上是几十行选择器声明，实际上它是 ROCm 安装体验中"操作系统 → 版本"这一关键决策层的唯一事实来源。它的每个选项取值都精确映射到仓库注册路径（ubuntu2604/ubuntu2404/ubuntu2204）、元包名（amdrocm7.14*）、Python 版本（3.14/3.12/3.11）、OEM 内核乃至amdgpu-install脚本代号，实现了"一次选择、全链路联动"。而其背后的 Sphinx 扩展与前端状态机，则为这类大型产品文档提供了一个可复用、可分享、可检索的条件化文档范式——读者若需在自己的文档体系中复刻类似能力，可直接以本仓库 selector/init.py 与 selector.js 为参考实现。
【免费下载链接】legacy-rocm-buildAMD ROCm™ Software - GitHub Home项目地址: https://gitcode.com/GitHub_Trending/ro/legacy-rocm-build
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
