OA0

OA0 是一个探索 AI 的社区

现在注册

已注册用户请登录

= OpenCL^(TM)^ 规范构建说明与注意事项
:toc2:
:toclevels: 1

[NOTE]
.注意
====
本文档最有用的部分是 <>、<> 以及关于安装 <> 的说明。
====

[NOTE]
.注意
====
此仓库的默认分支已从 master 更改为 main。
====

[[intro]]
== 引言

本仓库包含用于生成正式的 OpenCL API、OpenCL C、OpenCL 扩展、OpenCL SPIR-V 环境、OpenCL C++ 规范，以及 OpenCL 参考页和 C++ for OpenCL 内核语言文档的源代码和工具链。

本文档描述了所需的仓库结构、工具和构建说明。

[[source]]
== 源代码

OpenCL 规范由 Khronos Group 的 OpenCL 工作组维护，位于 https://github.com/KhronosGroup/OpenCL-Docs[OpenCL-Docs Github 仓库]。所有文档均采用 https://asciidoctor.org/[Asciidoctor] 格式。

欢迎通过 Github 上的 Pull Request 进行贡献。Pull Request 必须按照与规范源代码相同的 <> 提供。在提交 Pull Request 或其他贡献到 GitHub 时，系统会提示您签署一次性的“点击即同意”贡献者许可协议（CLA）。

我们打算在 GitHub 的 main 分支上保持线性历史记录。

[[repo]]
== 仓库结构

[[building]]
== 构建规范与参考页

如果已安装所有 <>，您应该能够通过以下命令为所有规范构建 HTML 和 PDF 输出：

$ make

Makefile 还提供了其他目标，用于为每个规范构建不同的输出：

规范目标生成在 out/html/（HTML 目标）和 out/pdf/（PDF 目标）目录下。参考页目标生成在 out/man/html/ 目录下。如果需要不同的输出目录，可以在命令行设置 Makefile 变量 OUTDIR。例如：

make OUTDIR=/tmp apihtml

将创建 /tmp/html/OpenCL_API.html。

这些目标在 Makefile 变量 $(OUTDIR) 指定的目录（默认为 out）中生成各种输出文档。

一旦基本构建工作正常，使用适当的并行化选项（例如 make -j 6）可能会显著加快构建多个规范的速度。asciidoctor HTML 构建非常快，即使对于整个规范也是如此，但 PDF 构建可能需要几分钟。

[[building-extensions]]
== 包含扩展的构建

不带额外参数调用 make 将构建仅包含核心 API 和功能的 OpenCL API 和 OpenCL C 语言规范。要构建包含扩展语言的这些规范版本，应使用 makeSpec 脚本。makeSpec 是一个 Python 脚本，接受以下参数：

-spec variant - variant 可以是 core、khr 或 all，分别构建仅包含核心、核心 + 所有 KHR 扩展以及核心 + 所有扩展的规范。目前，all 等同于 khr，因为规范源代码中只包含 khr 扩展。
-ext name - 将指定的扩展 name 及其依赖项添加到构建中。
-clean - 在构建前清理生成的文件。
-registry path - 使用指定的 API XML 文件，而不是默认的 xml/cl.xml。
-v - 详细模式，在执行操作前打印它们。
-n - 试运行模式，打印操作但不执行。
无法识别的选项会传递给 make，因此必须是有效的 Makefile 目标或 make 选项，例如 -j。

makeSpec --help 报告的任何其他选项尚未实现，不应使用。

例如，要使用所有 khr 扩展进行构建，可以使用：

[source,sh]

$ makeSpec -clean -spec khr -j html refpages

makeSpec 是一个包装器，在包含扩展构建时构造选项并调用 make，这只影响构建 API（包括参考页）和 C 语言规范。makeSpec 从指定的注册表 XML 路径中的元数据确定扩展依赖关系。

[[refpage-install]]
== 参考页安装

大多数参考页是从 OpenCL API 和 OpenCL C 规范中提取的，尽管有些是静态的。虽然任何人都可以为自己生成参考页集，但 Khronos 通过 https://www.khronos.org/registry/OpenCL/sdk/3.0/docs/man/[OpenCL Registry] 的 main 分支发布它们。

当 OpenCL 规范编辑更新已发布的参考页时，最简单的方法是拥有此仓库（OpenCL-Docs）以及 OpenCL-Registry 的本地仓库克隆。通过以下命令在本地注册表克隆中更新页面：

make -j 6 OUTDIR=path-to-registry-repo/sdk/3.0/docs manhtmlpages

这将在 sdk/3.0/docs/man/html 下创建 HTML 输出页面，并将 KaTeX 包复制到 sdk/3.0/docs/katex。要发布，请将这些更改提交到注册表仓库并将其推送到 github。

[[styles]]
== 样式表

我们使用 Asciidoctor 'colony' 主题的修改版本。该主题在 Khronos 内部维护，生成的 CSS 位于 config/khronos.css。

[[equations]]
== 嵌入方程式

在可能的情况下，应使用 asciidoc 标记和 eq 角色来编写方程式。这涵盖了许多常见的方程式，并且比替代方案更快。

对于更复杂的方程式，例如多情况语句、矩阵和复杂分数，应使用 latexmath: 内联和块宏来编写方程式。latexmath: 块的内容应为 LaTeX 数学符号。LaTeX 数学标记分隔符现在由 asciidoctor 工具链插入。

LaTeX 数学原样传递到所有 HTML 输出形式，随后在加载 HTML 时由 KaTeX 引擎渲染。KaTeX 发布的本地副本保存在 katex/ 中，并在规范生成期间复制到 HTML 输出目录。数学通过 asciidoctor-mathematical 处理为 SVG 用于 PDF 输出。

以下注意事项适用：

特殊字符 <、> 和 & 目前只能在 +++[latexmath]+++ 块宏中使用，不能在 +++latexmath:[]+++ 内联宏中使用。应分别使用 \lt、\leq、\gt 和 \geq 代替 <、<=、> 和 >=。& 是多行方程式的对齐结构，无论如何只应出现在块宏中。
AMSmath 环境（例如 pass:[\begin{equation}]、pass:[{align}] 等）目前不能在 KaTeX 中使用，已替换为 KaTeX 支持的构造，例如 pass:[{aligned}]。
不能使用任意的 LaTeX 构造。KaTeX 和 asciidoctor-mathematical 只是方程式渲染器，不是完整的 LaTeX 引擎。嵌入像 \Large 或 pass:[\hbox{\tt\small VK_FOO}] 这样的 LaTeX 可能在任何后端都无法工作，应避免使用。

有关我们工具链中支持的 LaTeX 数学构造的更多详细信息，请参阅 https://www.khronos.org/registry/vulkan/specs/1.0/styleguide.html[Khronos Vulkan Registry] 中的“Vulkan Documentation and Extensions”文档。

[[anchors]]
== Asciidoc 锚点与交叉引用

在 asciidoctor 中，可以使用以下语法为章节应用锚点（标签）：

[[spirv-il]]
== SPIR-V 中间语言

通常，锚点应紧接在章节或节标题之前，并采用 '+++[[chapter-section-label]]+++' 的形式。

然后可以使用以下方式生成指向这些锚点的交叉引用，例如：

有关 SPIR-V 中间语言的讨论，请参见 <> 节。

您还可以使用类似的命名方案在任意段落上添加锚点。

[[depends]]
== 软件依赖

本节描述了 OpenCL 规范工具链使用的软件组件。指定的版本已知可以工作。后续的兼容版本很可能也可以工作。

在构建 OpenCL 规范之前，必须安装以下工具：

GNU make（make 版本：4.0.8-1；更早版本可能也可以）
Python 3（python，版本：3.4.2）
Ruby（ruby，版本：2.3.3）
** 在某些环境中，可能还需要 Ruby 开发包（ruby-dev）。
Git 命令行客户端（git，版本：2.1.4）。没有 Git 客户端也可以进行构建，但构建中将省略分支/提交信息。支持以下操作的任何版本都应该可以工作：
** git symbolic-ref --short HEAD
** git log -1 --format="%H"
ttf 字体。这些是 PDF 构建中用于 latexmath 渲染所必需的。请参阅 https://github.com/asciidoctor/asciidoctor-mathematical/blob/master/README.md#dependencies[asciidoctor-mathematical 的字体依赖]。

还必须安装以下 Ruby Gems 和平台包依赖项。此过程在下面针对各个平台和环境管理器有更详细的描述。在尝试安装之前，请完整阅读本文档的其余部分（除了您不使用的平台特定部分）。

Asciidoctor（asciidoctor，版本：2.0.16）
Coderay（coderay，版本：1.1.1）
hexapdf（版本：0.27.0）
rouge（rouge，版本 3.19.0）
ttfunk（ttfunk，版本：1.5.1）
Asciidoctor PDF（asciidoctor-pdf，版本：1.5.0）
Asciidoctor Mathematical（asciidoctor-mathematical，版本 0.3.5）
https://github.com/asciidoctor/asciidoctor-mathematical#dependencies[asciidoctor-mathematical 的依赖项]（有很多！）
KaTeX 发行版（版本 0.7.0，来自 https://github.com/Khan/KaTeX）。这缓存在 katex/ 下，无需从 github 安装。

如果您不打算构建规范和支撑文档的 PDF 版本，则只需要 asciidoctor、coderay 和 rouge gems。

[NOTE]
.注意
====
虽然仅安装 HTML 构建的工具链组件更容易，但提交对规范有实质性更改的 MR 的人员有责任验证其分支能够构建 both html 和 pdf 目标。
====

以下是平台特定的工具链说明：

<>
** <>。由于速度、与 Linux 工具链的相似性以及所需包更可能保持最新，如果可能，建议在 Windows 构建中使用 Windows 10 Ubuntu 子系统，而不是 MinGW 和 Cygwin。
** <>（PDF 构建未测试）
** <>
<>
<>

[[depends-windows]]
=== Windows（通用）

Linux 包上的大多数依赖项都很轻量，因此可以在 Windows 中原生构建规范，但这意味着要绕过 makefile 并直接调用函数。这可能在将来得到解决。目前，Windows 用户有三种选择：Ubuntu / Windows 10、MinGW 或 Cygwin。

[[depends-ubuntu]]
==== Ubuntu / Windows 10

使用 Windows 10 的“Ubuntu 子系统”时，大多数依赖项可以通过 apt-get 安装：

sudo apt-get -qq -y install build-essential python3 git cmake bison flex \
libffi-dev libgmp-dev libxml2-dev libgdk-pixbuf2.0-dev libcairo2-dev \
libpango1.0-dev fonts-lyx gtk-doc-tools ghostscript

Ubuntu 上默认的 ruby 包相当陈旧。Ubuntu 只提供 ruby 和 ruby2.0——后者比当前稳定版落后多个版本，并且需要费力才能让 makefile 与之配合工作。

幸运的是，有更好的选择；建议使用 https://rvm.io[rvm] 或 https://github.com/rbenv/rbenv[rbenv] 来安装更新的版本。

[NOTE]
.注意
====
* 如果您是 Ruby 新手，在首次尝试使用 rvm 或 rbenv 之前，应完全删除（通过包管理器，例如 sudo apt-get remove *packagename*）机器上所有现有的 Ruby 和 asciidoctor 基础设施。dpkg -l | egrep 'asciidoctor|ruby|rbenv|rvm' 将为您提供要删除的候选包名称列表。
** 如果您已经有喜欢的 Ruby 包管理器，请忽略此建议，只需安装所需的操作系统包和 gems。
* 此外，rvm 和 rbenv 是互不兼容的。它们都依赖于在您的 bash shell 中插入垫片和修改 $PATH。如果您已经安装了其中一个并且熟悉它，最好坚持使用那个。一位编辑是 Ruby 新手，发现 rbenv 比 rvm 更容易理解。另一位编辑更喜欢 rvm。
** rvm 和 rbenv 在从非 Bash shell（如 tcsh）调用时，默认情况下都无法工作。这可以通过基于 bash 环境设置正确的环境变量和 PATH 添加来临时解决。
* Bash for Windows 上的大多数工具对 Windows 行尾（CR LF）都很适应，但 bash 脚本期望 Unix 行尾（LF）。1.0 分支中 Vulkan 树顶层的 .gitattributes 文件强制此类脚本在非 Linux 平台上以正确的行尾检出。如果您添加名称不以 .sh 结尾的新脚本，也应将它们包含在 .gitattributes 中。
====

[[depends-ubuntu-rbenv]]
===== Ubuntu/Windows 10 使用 Rbenv

Rbenv 是一个比 rvm 功能更轻量级的 Ruby 环境管理器。它的主要任务是管理不同的 Ruby 版本，而 rvm 具有额外的功能，例如管理与我们需求无关的“gemsets”。

以下是在 Ubuntu for Windows 上安装工具链的完整脚本，是在基本全新的环境中开发的。如果您尝试此操作，请不要一次执行整个脚本。逐步执行每个步骤，以防我们未遇到的错误。

安装 `ruby_build` 和工具链组件所需的包。

参见 https://github.com/rbenv/ruby-build/wiki 和

https://github.com/asciidoctor/asciidoctor-mathematical#dependencies

sudo apt-get install autoconf bison build-essential libssl-dev \
libyaml-dev libreadline6-dev zlib1g-dev libncurses5-dev \
libffi-dev libgdbm3 libgdbm-dev cmake libgmp-dev libxml2 \
libxml2-dev flex pkg-config libglib2.0-dev \
libcairo-dev libpango1.0-dev libgdk-pixbuf2.0-dev \
libpangocairo-1.0

从 https://github.com/rbenv/rbenv 安装 rbenv

git clone https://github.com/rbenv/rben

项目地址：https://github.com/KhronosGroup/OpenCL-Docs

28 次点击 ∙ 0 人收藏

登录后收藏

0 条回复

OpenCL — 异构计算框架