OpenVX™规范构建说明和注释
OpenVX™规范构建说明和注释
https://github.com/KhronosGroup/OpenVX-api-docs
目录
介绍
构建规范
更新规范中的标记ID
构建扩建
样式表
嵌入方程式
Asciidoc定位点和外部参照
软件相关性
修订历史记录
笔记
这是基于Vulkan描述文件，尚未针对OpenVX对构建过程的特定更改进行完全更新。最有用的部分是简介、构建规范以及关于安装软件依赖项的说明。
介绍
本描述描述了正确构建OpenVX API规范和参考页面的重要内容。
构建规范
一旦安装了所有正确的工具（请参阅下面的软件依赖项），请转到……-to-git-repo/docs/specification的路径。
$ make
或者使各个目标为html和pdf。
这些目标在Makefile变量$（OUTDIR）（默认情况下为out）指定的目录中生成各种输出文档。签入的文件../../../out/1.0/index.html链接到所有这些目标，或者可以单独找到它们，如下所示：
API规范：
html- Single-file HTML5 in$(OUTDIR)/html/vkspec.htmlpdf- PDF in$(OUTDIR)/pdf/vkspec.pdf
更新规范中的标记ID
要在规范中插入标记，请使用以下文本模式。不要忘记在标记前添加空格。这标记了一个没有数字ID的标记。config/spec-tags.py将有助于为标记添加唯一的数字ID。
`[*REQ*]`
要在新标记中自动插入唯一的数字ID，请使用以下脚本：
% python config/spec-tags.py update OpenVX_Specification.adoc
有关更多详细信息，请使用% python config/spec-tags.py -help。
构建扩展
树中的所有扩展（完整或其他）都转换为ASCII标记，并且可以构建。API规范的源位于OpenVX_specification.txt中，而每个扩展位于vx_extension_name.txt中。通过传递SPECBASE=vx_extension_ name来生成扩展，例如。
make SPECBASE=vx_khr_nn html
辅助脚本makeAllSpecs可以调用为
makeAllSpecs html (or pdf, or both)
备用和测试构建
如果只是在测试ASCII格式、宏、样式表等，可能需要编辑OpenVX_Specification.txt以仅包含测试代码。asciidoctor HTML构建非常快，即使对于整个规范也是如此，但PDF构建需要几分钟时间。
重建生成的图像
图像/目录中有一些图像以一种格式保存，但需要转换为另一种格式以进行相应类型的输出。大多数是SVG转换为PDF，有些是PPT转换为PDF转换为SVG。所有构建都需要SVG。
Makefile不会自动转换这些文件。相反，所需的所有输出表单都会检查到images/中。在极少数情况下，有人更改源文档并需要重新生成其他表单：
cd images ; make
样式表
使用了Asciiddoctor colony主题的修改版本，修改后更像Doxygen样式表。
嵌入方程式
在可能的情况下，应该使用eq角色使用直接的asciidoc标记来编写公式。这涵盖了许多常见的方程，并且比备选方案更快。
对于更复杂的方程，如多事例语句、矩阵和复数分数，应使用latexmath: inline和block宏编写方程。latexmath: blocks的内容应该是LaTeX数学表示法。LaTeX数学标记分隔符现在由ascidictor工具链插入。
LaTeX数学被未经修改地传递到所有HTML输出表单，随后在加载HTML时使用KaTeX引擎进行渲染。KaTeX版本的本地副本保存在doc/specs/vulkan/KaTeX中，并在规范生成期间复制到HTML输出目录中。数学通过用于PDF输出的asciidoctor数学处理为SVG。
以下注意事项适用：
特殊字符<、>和&当前只能在[latexmath]块宏中使用，而不能在latexmath:[]内联宏中使用。请使用\lt、\leq、\gt和\geq分别表示<、⇐、>和>=。&是多行方程式的对齐构造，无论如何都应该只出现在块宏中。
AMSmath环境（例如\ begin｛equipment*｝、｛align*｝等）目前无法在KaTeX中使用，已被KaTeX支持的结构（如｛aligned｝）所取代。
不能使用任意的LaTeX构造。KaTeX和asciidoctor数学只是方程渲染器，而不是完整的LaTeX引擎。嵌入类似LaTeX的\Large或\hbox｛\t\small VK\_FOO｝可能在任何后端都不起作用，应该避免。
有关支持的LaTeX数学结构的更多详细信息，请参阅OpenVX文档和扩展文档。
Asciidoc定位点和外部参照
在API规范中，节可以使用以下语法应用锚（标签）。一般情况下，锚点应紧跟在章节或章节标题之前，并应使用[[章节-章节标签]]的形式。例如
例如，根据Vulkan规范，有：
[[synchronization-primitives]]
Synchronization Primitives
对这些锚的交叉引用然后可以用例如，
See the <<synchronization-primitives>> section for discussion of fences,
semaphores, and events.
也可以使用类似的命名方案在任意段落上添加锚点。
任何定义来自自动生成的API之一的文件（目录API/basetypes、API/enums、API/flags、apifuncpointers、API/handles、API/protos和API/structs中的.txt文件）都有一个相应的锚，其名称是所定义的函数、结构等的名称。因此，可以这样说：
Fences are used with the +++<<vkQueueSubmit>>+++ command...
软件相关性
本节介绍OpenVX规范工具链所使用的软件组件。
在构建OpenVX规范之前，必须安装以下工具：
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"
Ghostscript（Ghostscript，版本：9.10）。这是针对PDF构建的，如果没有它，它仍然可以继续。Ghostscript用于优化PDF的大小，因此如果包含它，它会小得多。
还必须安装以下Ruby Gems和平台包依赖项。每个gem都列出了已知有效的版本。早期版本在某些方面可能也可能无法正常工作。
下面将针对各个平台和环境管理器更详细地描述安装gem和包依赖项。在尝试安装之前，请完整阅读本文档的其余部分（您不使用的特定于平台的部分除外）。
Asciidoctor (asciidoctor, version: 1.5.8)
Coderay（Coderay，1.1.1版）
JSON模式（JSON模式，版本2.8.1）
Asciidoctor PDF（asciidoctorPDF，版本：1.5.0.alpha16）
Asciidoctor数学（asciidoctors数学，版本0.2.2）
asciidoctor数学依赖项（有很多！）
KaTeX发行版（0.7.0版本来自https://github.com/Khan/KaTeX . 它缓存在doc/specs/vulkan/katex/下，不需要从github安装。
腹水图(https://asciidoctor.org/docs/asciidoctor-diagram/，版本：1.5.11）
如果您不打算构建规范和支持文档的PDF版本，则只需要ascidictor和coderay gem。
json模式仅用于验证有效用法提取脚本到json文件的输出。如果未安装，则在构建JSON时将跳过验证。
笔记
虽然只安装HTML构建的工具链组件更容易，但提交对规范进行重大更改的MR的人有责任验证他们的分支是否同时构建了HTML和pdf目标。
平台特定的工具链说明如下：
Microsoft Windows
Ubuntu / Windows 10
MinGW (PDF builds not tested)
Cygwin
Mac OS X
Linux (Debian, Ubuntu, etc.)
Windows（常规）
Linux软件包上的大多数依赖项都很轻，因此可以在Windows中本地构建规范，但这意味着绕过makefile并直接调用函数。这个问题将来可能会得到解决。目前，Windows用户有三种选择：Ubuntu/Windows10、MinGW或Cygwin。
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 ttf-lyx gtk-doc-tools ghostscript
Ubuntu上默认的ruby包已经过时了。Ubuntu只提供ruby和ruby2.0，后者比当前的稳定分支有多个修订版，需要进行争论才能使makefile正常工作。
幸运的是，还有更好的选择；建议使用rvm或rbenv安装更新的版本。
笔记
如果是Ruby的新手，在第一次尝试使用rvm或rbenv之前，应该完全删除（通过包管理器，例如sudo apt-get-remove-packagename）机器上所有现有的Ruby和ascidictor基础设施。dpkg-l|egrep“asciidoctor|rube|rbenv|rvm”提供一个要删除的候选包名称列表。
如果已经有了最喜欢的Ruby软件包管理器，请忽略此建议，只需安装所需的操作系统软件包和gem。
此外，rvm和rbenv是相互不兼容的。它们都依赖于在bash shell中插入垫片和$PATH修改。如果你已经安装了其中一个，并且对它很熟悉，那么最好还是使用它。其中一位编辑是Ruby的新手，发现rbenv比rvm更容易理解。另一位编辑更喜欢rvm。
当从非Bash shell（如tcsh）调用时，rvm和rbenv都不能开箱即用。这可以通过设置正确的环境变量和基于bash环境的PATH添加来破解。
Bash for Windows上的大多数工具都对Windows的行尾（CR LF）非常满意，但Bash脚本需要Unix的行尾。1.0分支中vulkan树顶部的文件.gitattributes强制在非Linux平台上使用正确的行尾签出此类脚本。如果添加名称不以.sh结尾的新脚本，它们也应该包含在.gitattributes中。
Ubuntu/Windows 10使用Rbenv
Rbenv是一个比rvm功能更少的轻量级Ruby环境管理器。它的主要任务是管理不同的Ruby版本，而rvm还有其他功能，比如管理与需求无关的“gemset”。
以下是在开箱即用的环境中开发的Ubuntu for Windows工具链的完整安装脚本。如果你尝试这样做，不要试图同时执行整个过程。如果出现我们没有遇到的错误，请分别执行每一步。
# Install packages needed by `ruby_build` and by toolchain components.
# See https://github.com/rbenv/ruby-build/wiki and
# 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
# Install rbenv from https://github.com/rbenv/rbenv
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
# Set path to shim layers in .bashrc
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> .bashrc
~/.rbenv/bin/rbenv init
# Set .rbenv environment variables in .bashrc
echo 'eval "$(rbenv init -)"' >> .bashrc
# Restart your shell (e.g. open a new terminal window). Note that
# you do not need to use the `-l` option, since the modifications
# were made to .bashrc rather than .bash_profile. If successful,
# `type rbenv` should print 'rbenv is a function' followed by code.
# Install `ruby_build` plugin from https://github.com/rbenv/ruby-build
git clone https://github.com/rbenv/ruby-build.git
~/.rbenv/plugins/ruby-build
# Install Ruby 2.3.3
# This takes in excess of 20 min. to build!
# https://github.com/rbenv/ruby-build/issues/1054#issuecomment-276934761
# suggests:
# "You can speed up Ruby installs by avoiding generating ri/RDoc
# documentation for them:
# RUBY_CONFIGURE_OPTS=--disable-install-doc rbenv install 2.3.3
# We have not tried this.
rbenv install 2.3.3
# Configure rbenv globally to always use Ruby 2.3.3.
echo "2.3.3" > ~/.rbenv/version
# Finally, install toolchain components.
# asciidoctor-mathematical also takes in excess of 20 min. to build!
# The same RUBY_CONFIGURE_OPTS advice above may apply here as well.
gem install asciidoctor coderay json-schema
gem install --pre asciidoctor-pdf
MATHEMATICAL_SKIP_STRDUP=1 gem install asciidoctor-mathematical
Ubuntu/Windows 10使用RVM
以下是使用rvm安装2.3.x版本的（稀疏）说明：
gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3
\curl -sSL https://get.rvm.io | bash -s stable --ruby
source ~/.rvm/scripts/rvm
rvm install ruby-2.3
rvm use ruby-2.3
笔记
Windows10Bash需要在启动时附加“-l”选项，以便运行登录shell；否则RVM将无法在未来的发射中正常工作。
buntu 16.04使用系统Ruby
Ubuntu 16.04.1默认Ruby安装（2.3.1版）似乎足够更新，可以运行所有必需的gem，但也需要通过包管理器安装Ruby-dev包。
此外，必须将库/var/lib/gems/2.3.0/gems/mathematical-1.6.7/ext/mathmatical/lib/liblasem.so复制或链接到加载程序可以找到它的目录中。这一要求似乎是由于asciictor数学构建过程中的问题。
工具链
MinGW可以在这里获得：http://www.mingw.org/
一旦安装程序运行了初始设置，按照网站上的说明，您应该安装mingw开发人员工具、mingw-base和msys-base包。msys基本包允许您使用windows中的bash终端，以及MinGW安装的unix工具。
在本机Windows环境中，还应安装以下本机软件包：
Python 3.x(https://www.python.org/downloads/)
Ruby 2.x(https://rubyinstaller.org/)
Git命令行客户端(https://git-scm.com/download)
一旦设置好了，并且安装了必要的Ruby Gems，就启动msys bash shell，并导航到规范Makefile。从那里开始，在执行make命令之前，您需要将PYTHON=设置为版本3.x的PYTHON可执行文件的位置，但除此之外，除了pdf构建之外的所有内容都应该正常工作。
笔记
通过此路径构建PDF规范尚未经过测试，但这是可能的——liblasem是主要问题，看起来现在有一个mingw32版本可用。
Cygwin
安装Cygwin时，应通过安装程序安装以下软件包：
// "curl" is only used to download fonts, can be done in another way
autoconf
bison
cmake
curl
flex
gcc-core
gcc-g++
ghostscript
git
libbz2-devel
libcairo-devel
libcairo2
libffi-devel
libgdk_pixbuf2.0-devel
libgmp-devel
libiconv
libiconv-devel
liblasem0.4-devel
libpango1.0-devel
libpango1.0_0
libxml2
libxml2-devel
make
python3
ruby
ruby-devel
笔记
其中一些包的本机版本是可用的，但应注意与cygwin的各个部分（例如路径）不兼容。Ruby尤其无法通过本机版本正确解析Windows路径。可以使用Python和Git for Windows，但对于Python，在调用make之前，您需要通过Python环境变量设置其路径。
在安装数学ruby gem时，有两件事需要进行调整才能使其正常工作。首先，不要：
MATHEMATICAL_SKIP_STRDUP=1 gem install asciidoctor-mathematical
应该使用
MATHEMATICAL_USE_SYSTEM_LASEM=1 gem install asciidoctor-mathematical
后者导致它使用已经安装的lasem包，而不是试图构建一个新的包。
数学gem还查找“liblasem”，而不是lasem0.4-devel软件包安装的“liblasem0.4”，因此有必要使用以下方法将符号链接添加到/lib目录：
ln -s /lib/liblasem-0.4.dll.a /lib/liblasem.dll.a
uby Gems通常不会安装到路径中的位置。宝石被安装到~/bin/-在调用make之前，应该将其添加到路径中：
export PATH=~/bin:$PATH
最后，需要通过以下命令手动安装lasem的字体：
mkdir /usr/share/fonts/truetype cd /usr/share/fonts/truetype
curl -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmex10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmmi10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmr10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmsy10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/esint10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/eufm10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msam10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msbm10.ttf
Mac OS X
Mac OS X应该以与ubuntu相同的方式工作，使用Homebrew软件包管理器，只是可以简单地通过brew安装ruby软件包，而不是使用特定于ruby的版本管理器。
可能还需要通过数学为PDF构建安装其他字体，可以使用以下方法：
cd ~/Library/Fonts
curl -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmex10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmmi10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmr10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmsy10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/esint10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/eufm10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msam10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msbm10.ttf
然后安装所需的Ruby Gems。
Linux（Debian、Ubuntu等）
Ubuntu/Windows 10的安装说明通常适用于使用Debian软件包的本地Linux环境，如Debian和Ubuntu，尽管要安装的软件包的确切列表可能有所不同。其他使用不同包管理器的发行版，如RPM（Fedora）和Yum（SuSE），将有不同的要求。
使用rbenv或rvm是必要的，因为系统Ruby包通常已经过时了。
一旦安装了环境管理器、Ruby和Ruby_build，就可以安装所需的RubyGems。
Ruby
一旦平台设置好，可以通过geminstall命令直接安装以下ruby gem：
gem install rake asciidoctor coderay json-schema
# Required only for pdf builds
MATHEMATICAL_SKIP_STRDUP=1 gem install asciidoctor-mathematical
gem install --pre asciidoctor-pdf
gem install --pre asciidoctor-diagram
为了确保安装了最新版本的gem，请定期执行
gem update
脚本
使用%python-config/check-mising-apis.py根据adoc文件检查头文件中是否缺少函数。使用%python-config/check-mising-apis.py-v获取更多详细信息。
参考文献链接
https://github.com/KhronosGroup/OpenVX-api-docs
