Vulkan API 规范文档构建指南

Vulkan API 规范文档构建指南

概述

本文详细介绍了如何构建 Vulkan API 规范文档及其相关资源。Vulkan 是一个跨平台的图形和计算 API，其规范文档是开发者理解和使用 Vulkan 的重要参考资料。本文将指导您完成从环境配置到最终文档生成的完整流程。

构建环境准备

推荐方式：使用 Docker 镜像

Khronos 官方提供了预装所有必要工具的 Docker 镜像，这是最简便的构建方式：

1. 确保已安装 Docker 或 Podman
2. 从项目根目录运行以下命令之一：

   # 使用 Docker
   scripts/runDocker
   
   # 使用 Podman
   scripts/runPodman
   

进入容器后，执行构建命令：

cd /vulkan
./makeSpec -spec core html  # 构建基础 HTML 规范

非 Docker 环境构建

虽然不推荐，但您也可以在本地环境中安装所有依赖工具。需要的主要组件包括：

• Asciidoctor 及其相关扩展
• Python 3
• Ruby
• LaTeX（用于 PDF 生成）
• 其他辅助工具

构建目标详解

常用构建目标

Vulkan 规范支持多种输出格式：

• HTML 规范：单文件 HTML5 格式（html 目标）
• 分块 HTML：便于浏览的章节分割版本（chunked 目标）
• PDF 规范：适合打印的 PDF 版本（pdf 目标）
• 样式指南：Vulkan 文档编写规范（styleguide 目标）
• 参考页面：每个 API 的详细说明（manhtmlpages 目标）

构建不同 API 版本

默认构建 Vulkan 1.4 规范，如需构建其他版本：

VERSIONS="VK_VERSION_1_0 VK_VERSION_1_1" ./makeSpec html

构建 Vulkan SC 规范

Vulkan SC（安全关键）是 Vulkan 的安全关键版本，构建时需要指定 API 类型：

VULKAN_API="vulkansc" ./makeAllExts -version sc1.0 html

包含扩展

Vulkan 的扩展功能可以按需包含在规范中：

./makeSpec -clean -spec khr -extension VK_EXT_debug_report html

支持四种扩展集合：

• core：无扩展（默认）
• khr：所有 KHR 扩展
• ratified：所有已批准的扩展
• all：所有注册的扩展

高级构建技巧

验证脚本

allchecks 目标会运行一系列验证脚本，检查规范中的标记错误、缺失接口等问题：

./makeSpec -spec all allchecks

参考页面生成

参考页面是从规范中提取的 API 详细说明：

./makeSpec -spec all refpages  # 生成参考页面源文件
./makeSpec -spec all manhtmlpages  # 构建 HTML 参考页面

样式与宏

Vulkan 规范使用自定义的 Asciidoctor 宏和样式表：

• 宏定义在 config/spec-macros/extension.rb
• 样式基于 Asciidoctor 的 "colony" 主题修改
• 使用 Noto 字体家族确保跨平台一致性

常见问题解答

构建速度优化

对于大型构建（如包含所有扩展），可以使用并行构建加速：

./makeSpec -j 8 -spec all html

图像处理

规范中的所有图像均为 SVG 格式，建议使用 Inkscape 编辑，以确保与 PDF 生成的兼容性。

版本更新

当 Docker 镜像更新时，建议清理旧镜像以节省空间：

docker images  # 查看镜像列表
docker rmi -f <旧镜像ID>  # 删除不再需要的镜像

结语

本文涵盖了 Vulkan 规范构建的主要方面。使用官方 Docker 镜像可以避免大多数环境配置问题，是最推荐的构建方式。对于规范贡献者，理解扩展包含机制和验证脚本的使用尤为重要。规范的样式和宏系统确保了文档的一致性和可维护性。

如需更详细的编写规范，请参考 Vulkan 样式指南（通过 styleguide 目标生成）。