mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-12 06:54:14 +00:00
e2d981c029
* Bump API patch number and header version number to 20 for this
update.
Github Issues:
* Replaced existing reference pages by text automatically extracted
from the specification source, or generated from vk.xml in some
cases. This isn't a complete solution for the reference pages, but
puts them in a much better state. The ref pages (only) are now
placed under a CC BY open source license, which is more current than
the obsolete license previously used.
Further improvements to the pages should not edit them directly, but
instead concentrate on the specification source from which the ref
pages are being extracted (public issues 44, 55, 160; internal issue
389).
349 lines
13 KiB
Makefile
349 lines
13 KiB
Makefile
# Copyright (c) 2014-2016 The Khronos Group Inc.
|
|
# Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
|
|
|
# Vulkan Specification makefile
|
|
#
|
|
# Default targets:
|
|
# - XHTML, XHTML chunked, and PDF specs ('allspecs')
|
|
# - HTML single-document reference pages ('manhtml' and 'manpdf')
|
|
# - HTML and nroff separate reference pages ('manpages' and 'manhtmlpages')
|
|
# - Validator scripts ('allchecks')
|
|
#
|
|
# The 'html' target is deprecated but still supported, for now. It uses
|
|
# a different toolchain than XHTML/PDF outputs, isn't quite compatible,
|
|
# and will not be published, but is faster to generate for quick tests.
|
|
|
|
all: alldocs allchecks
|
|
|
|
alldocs: allspecs allman
|
|
|
|
allspecs: xhtml chunked pdf
|
|
|
|
allman: manhtml manpdf manpages manhtmlpages
|
|
|
|
allchecks: checkinc checklinks
|
|
|
|
# Note that the := assignments below are immediate, not deferred, and
|
|
# are therefore order-dependent in the Makefile
|
|
|
|
QUIET?=@
|
|
ASCIIDOC ?= asciidoc.py
|
|
A2X ?= a2x.py
|
|
DBLATEX ?= dblatex
|
|
# DBLATEXPREFIX can be overriden by setting it as an environment variable,
|
|
# if not installed in the standard location on your distribution
|
|
DBLATEXPREFIX ?= /etc/asciidoc/dblatex
|
|
RM=rm -f
|
|
RMRF=rm -rf
|
|
MKDIR=mkdir -p
|
|
CP=cp
|
|
ECHO:=echo
|
|
# Target directories for output files
|
|
# HTMLDIR - 'html' target
|
|
# XHTMLDIR - 'xhtml' target
|
|
# PDFDIR - 'pdf' target
|
|
# CHECKDIR - 'allchecks' target
|
|
OUTDIR := ../../../out/1.0
|
|
HTMLDIR := $(OUTDIR)/html
|
|
XHTMLDIR := $(OUTDIR)/xhtml
|
|
PDFDIR := $(OUTDIR)/pdf
|
|
CHECKDIR := $(OUTDIR)/checks
|
|
# Images used in the API spec
|
|
IMAGEPATH :=images
|
|
ICONPATH :=$(IMAGEPATH)/icons
|
|
PDFXSL :=config/vkspec-dblatex.xsl
|
|
PDFSTY :=config/vkspec-dblatex.sty
|
|
PYTHON ?= python3
|
|
|
|
# Set VERBOSE to -v to see what asciidoc is doing.
|
|
# Set KEEP to -d to retain intermediate dblatex files
|
|
VERBOSE =
|
|
KEEP =
|
|
|
|
# asciidoc / a2x attributes to set.
|
|
# XMLLINT normally unset - to detect problems with intermediate files
|
|
# NOTEOPTS sets options controlling which NOTEs are generated
|
|
# ATTRIBOPTS sets the api revision and enables MathJax generation
|
|
# VKCONF contains Vulkan-specific Asciidoc macros
|
|
# ADOCOPTS options for asciidoc->HTML output
|
|
# ADOCPDFOPTS options for asciidoc->PDF output via dblatex (not using a2x)
|
|
# A2XOPTS options for a2x->{HTML,PDF} output
|
|
XMLLINT = --no-xmllint
|
|
NOTEOPTS = -a editing-notes -a implementation-guide
|
|
ATTRIBOPTS = -a apirevision="$(SPECREVISION)" -a mathjax
|
|
VKCONF = config/vkspec.conf
|
|
ADOCOPTS = $(ATTRIBOPTS) $(NOTEOPTS) -f config/mathjax-asciidoc.conf \
|
|
-f $(VKCONF) $(VERBOSE)
|
|
ADOCPDFOPTS= $(ATTRIBOPTS) $(NOTEOPTS) -f config/mathjax-docbook.conf \
|
|
-f $(VKCONF) $(VERBOSE)
|
|
A2XOPTS = $(ATTRIBOPTS) $(NOTEOPTS) \
|
|
--asciidoc-opts="-f config/mathjax-docbook.conf -f $(VKCONF)" \
|
|
--xsltproc-opts="--param generate.consistent.ids 1" \
|
|
$(XMLLINT) $(VERBOSE) --icons
|
|
|
|
# XSL customizing Asciibook XSL to pass through equations and add
|
|
# MathJax. This varies depending on target type.
|
|
XHTMLXSL = config/docbook-xsl/xhtml.xsl
|
|
CHUNKEDXSL = config/docbook-xsl/chunked.xsl
|
|
|
|
# dblatex options passed two ways, directly to dblatex and via a2x.
|
|
DBLATEXOPTS := $(KEEP) -V -T db2latex -I. -I images -I images/icons -s $(DBLATEXPREFIX)/asciidoc-dblatex.sty
|
|
A2XDBLATEXOPTS := --dblatex-opts='$(DBLATEXOPTS)'
|
|
|
|
# Misc. files to clean up (see 'checkinc' target below)
|
|
DIRT = $(SPECVERSION)
|
|
|
|
.PHONY: directories $(MANHTMLDIR) $(MANPAGEDIR)
|
|
|
|
ICONFILES := \
|
|
$(ICONPATH)/caution.png \
|
|
$(ICONPATH)/example.png \
|
|
$(ICONPATH)/home.png \
|
|
$(ICONPATH)/important.png \
|
|
$(ICONPATH)/next.png \
|
|
$(ICONPATH)/note.png \
|
|
$(ICONPATH)/prev.png \
|
|
$(ICONPATH)/tip.png \
|
|
$(ICONPATH)/up.png \
|
|
$(ICONPATH)/warning.png
|
|
PNGFILES := $(ICONFILES) $(wildcard $(IMAGEPATH)/*.png)
|
|
# This is a horrible hack to avoid pulling in vulkantexture0.svg
|
|
SVGFILES := $(wildcard $(IMAGEPATH)/[A-Za-uw-z]*.svg)
|
|
PDFFILES := $(SVGFILES:.svg=.pdf)
|
|
# Some random directories and files that need to be copied into spec
|
|
# output directory
|
|
WEBIMAGES := $(SVGFILES:%=$(HTMLDIR)/%) $(PNGFILES:%=$(HTMLDIR)/%)
|
|
# File suffix for image targets for HTML and PDF Builds - Asciidoc {svgtype} attribute
|
|
SVGTYPEHTML := svg
|
|
SVGTYPEPDF := pdf
|
|
# Main (root) asciidoc spec source file
|
|
TOPDOC := vkspec.txt
|
|
# Files making up sections of the API spec. The wildcard expression
|
|
# should work in extension branches to pull in those files as well.
|
|
CHAPTERS := $(wildcard chapters/[A-Za-z]*.txt appendices/[A-Za-z]*.txt chapters/*/[A-Za-z]*.txt appendices/*/[A-Za-z]*.txt)
|
|
INCLUDES := $(wildcard protos/*.txt structs/*.txt flags/*.txt enums/*.txt funcpointers/*.txt validity/structs/*.txt validity/protos/*.txt)
|
|
# All non-format-specific dependencies
|
|
COMMONDOCS := $(CHAPTERS) $(INCLUDES)
|
|
# A generated included file with the spec version, date, and git commit
|
|
SPECVERSION = specversion.txt
|
|
SPECREVISION = 1.0.20
|
|
SPECREMARK =
|
|
|
|
# Spec targets
|
|
# There is some complexity to try and avoid short virtual targets like 'html'
|
|
# causing specs to *always* be regenerated.
|
|
|
|
html: $(HTMLDIR)/vkspec.html $(TOPDOC) $(COMMONDOCS) $(WEBIMAGES)
|
|
|
|
$(HTMLDIR)/vkspec.html: $(VKCONF) $(SPECVERSION) $(TOPDOC) $(COMMONDOCS) $(WEBIMAGES)
|
|
$(QUIET)if test ! -d $(HTMLDIR) ; then $(MKDIR) $(HTMLDIR) ; fi
|
|
$(QUIET)$(ASCIIDOC) -b html5 $(ADOCOPTS) -o $(HTMLDIR)/vkspec.html -a svgpdf=$(SVGTYPEHTML) $(TOPDOC)
|
|
|
|
xhtml: $(XHTMLDIR)/vkspec.html $(TOPDOC) $(COMMONDOCS)
|
|
|
|
$(XHTMLDIR)/vkspec.html: $(VKCONF) $(SPECVERSION) $(TOPDOC) $(COMMONDOCS)
|
|
$(QUIET)if test ! -d $(XHTMLDIR) ; then $(MKDIR) $(XHTMLDIR) ; fi
|
|
$(QUIET)$(A2X) $(A2XOPTS) -f xhtml $(TOPDOC) \
|
|
--xsl-file=$(XHTMLXSL) \
|
|
-a toc2 -a toclevels=2 --destination-dir=$(XHTMLDIR) \
|
|
-a svgpdf=$(SVGTYPEHTML)
|
|
|
|
chunked: $(OUTDIR)/vkspec.chunked/index.html $(TOPDOC) $(COMMONDOCS)
|
|
|
|
$(OUTDIR)/vkspec.chunked/index.html: $(VKCONF) $(SPECVERSION) $(TOPDOC) $(COMMONDOCS)
|
|
$(QUIET)if test ! -d $(OUTDIR)/chunked ; then $(MKDIR) $(OUTDIR) ; fi
|
|
$(QUIET)$(A2X) $(A2XOPTS) -f chunked $(TOPDOC) \
|
|
--xsl-file=$(CHUNKEDXSL) \
|
|
-a toc2 -a toclevels=2 --destination-dir=$(OUTDIR) \
|
|
-a svgpdf=$(SVGTYPEHTML)
|
|
|
|
pdf: $(PDFDIR)/vkspec.pdf
|
|
|
|
$(PDFDIR)/vkspec.pdf: $(PDFXSL) $(PDFSTY) $(PDFDIR)/vkspec.xml
|
|
$(QUIET)$(DBLATEX) -b pdftex $(DBLATEXOPTS) \
|
|
-p "$(DBLATEXPREFIX)/asciidoc-dblatex.xsl" \
|
|
-p $(PDFXSL) -s $(PDFSTY) \
|
|
$(PDFDIR)/vkspec.xml -O $(PDFDIR)
|
|
|
|
$(PDFDIR)/vkspec.xml: $(VKCONF) $(SPECVERSION) $(TOPDOC) $(COMMONDOCS) $(PDFDIR) $(PDFFILES)
|
|
$(QUIET)$(ASCIIDOC) --backend docbook $(ADOCPDFOPTS) \
|
|
-a a2x-format=pdf -a svgpdf=pdf \
|
|
--out-file $(PDFDIR)/vkspec.xml $(TOPDOC)
|
|
|
|
$(PDFDIR):
|
|
$(QUIET)if test ! -d $(PDFDIR) ; then $(MKDIR) $(PDFDIR) ; fi
|
|
|
|
# Generate Asciidoc attributes for spec version / date
|
|
GITHEAD := ../../../.git/logs/HEAD
|
|
ifeq ($(wildcard $(GITHEAD)),)
|
|
# If GITHEAD does not exist, don't include branch info.
|
|
$(SPECVERSION):
|
|
$(QUIET)echo ":revnumber: $(SPECREVISION)" > $@
|
|
$(QUIET)echo ":revdate: " `date` >> $@
|
|
$(QUIET)echo ":revremark: Git branch information not available" >> $@
|
|
else
|
|
# Could use `git log -1 --format="%cd"` to get branch commit date
|
|
# This used to be a dependency in the spec html/chunked/pdf targets,
|
|
# but that's likely to lead to merge conflicts. Just regenerate
|
|
# when pushing a new spec for review to the sandbox.
|
|
# The dependency on HEAD is per the suggestion in
|
|
# http://neugierig.org/software/blog/2014/11/binary-revisions.html
|
|
$(SPECVERSION): $(GITHEAD)
|
|
$(QUIET)echo ":revnumber: $(SPECREVISION)" > $@
|
|
$(QUIET)echo ":revdate: " `date` >> $@
|
|
$(QUIET)echo ":revremark: $(SPECREMARK) from git branch:" \
|
|
`git symbolic-ref --short HEAD` \
|
|
"commit:" `git log -1 --format="%H"` >> $@
|
|
endif
|
|
|
|
styleguide: $(OUTDIR)/styleguide.html
|
|
|
|
STYLESRC = style/styleguide.txt
|
|
$(OUTDIR)/styleguide.html: $(VKCONF) $(SPECVERSION) $(STYLESRC)
|
|
$(QUIET)$(ASCIIDOC) -b html5 $(ADOCOPTS) \
|
|
-o $(OUTDIR)/styleguide.html -a svgpdf=$(SVGTYPEHTML) \
|
|
$(STYLESRC)
|
|
|
|
clean: clean_html clean_pdf clean_chunked clean_checks clean_dirt clean_man
|
|
|
|
clean_man:
|
|
$(RM) $(MANHTML)
|
|
$(RMRF) $(MANHTMLDIR)
|
|
$(RM) $(MANPAGES)
|
|
$(RMRF) $(MANPAGEDIR)
|
|
|
|
clean_html:
|
|
$(QUIET)$(RMRF) $(HTMLDIR) $(XHTMLDIR)
|
|
$(QUIET)$(RM) $(OUTDIR)/apispec.html
|
|
|
|
clean_pdf:
|
|
$(QUIET)$(RM) $(PDFDIR)/vkspec.pdf $(PDFDIR)/vkspec.xml $(OUTDIR)/apispec.pdf
|
|
|
|
clean_chunked:
|
|
$(QUIET)$(RMRF) $(OUTDIR)/vkspec.chunked
|
|
|
|
clean_checks:
|
|
$(QUIET)$(RMRF) $(CHECKDIR)
|
|
|
|
clean_dirt:
|
|
$(QUIET)$(RM) $(DIRT)
|
|
|
|
# Ref page targets for individual pages
|
|
MANDIR := man
|
|
MANSECTION := 3
|
|
|
|
# These lists should be autogenerated
|
|
|
|
# Ref page sources, split up by core vs. author IDs
|
|
# CORESOURCES expansion will accidentally pull in macros defined by
|
|
# extensions. Hopefully that won't happen.
|
|
WSISOURCES := $(wildcard $(MANDIR)/*KHR.txt)
|
|
EXTSOURCES := $(wildcard $(MANDIR)/*EXT.txt)
|
|
CORESOURCES := $(filter-out $(WSISOURCES) $(EXTSOURCES) $(MANDIR)/vkman.css,$(wildcard $(MANDIR)/[Vv][Kk]* $(MANDIR)/PFN*txt))
|
|
MANSOURCES := $(CORESOURCES) $(WSISOURCES) $(EXTSOURCES)
|
|
|
|
MANCOPYRIGHT:= $(MANDIR)/khronoscopyright.txt $(MANDIR)/footer.txt
|
|
MANPAGEDIR := $(OUTDIR)/man/$(MANSECTION)
|
|
MANPAGES := $(MANSOURCES:$(MANDIR)/%.txt=$(MANPAGEDIR)/%.$(MANSECTION))
|
|
MANHTMLDIR := $(OUTDIR)/man/html
|
|
MANHTML := $(MANSOURCES:$(MANDIR)/%.txt=$(MANHTMLDIR)/%.html)
|
|
|
|
manpagesall: manpages manhtmlpages
|
|
|
|
manpages: $(MANPAGEDIR) $(MANPAGES)
|
|
|
|
manhtmlpages: $(MANHTMLDIR) $(MANHTML)
|
|
|
|
manhtmlpages: VKCONF=config/manpages.conf
|
|
|
|
# Automatic generation of ref pages. Needs to have a proper dependency
|
|
# causing the man page sources to be generated by running genRef (once),
|
|
# but adding $(MANSOURCES) to the targets causes genRef to run
|
|
# once/target.
|
|
man/apispec.txt: $(CHAPTERS) genRef.py reflib.py vkapi.py
|
|
$(PYTHON) genRef.py $(CHAPTERS)
|
|
|
|
# These dependencies don't take into account include directives
|
|
|
|
$(MANPAGEDIR)/%.$(MANSECTION): $(MANDIR)/%.$(MANSECTION)
|
|
$(QUIET)mv $< $@
|
|
|
|
$(MANDIR)/%.$(MANSECTION): $(MANDIR)/%.txt $(MANCOPYRIGHT) config/manpages.conf
|
|
$(QUIET)$(ECHO) Building $@
|
|
$(QUIET)$(A2X) -d manpage -f manpage --asciidoc-opts "-f config/manpages.conf" $(A2XOPTS) $<
|
|
|
|
$(MANHTMLDIR)/%.html: $(MANDIR)/%.txt $(MANCOPYRIGHT) config/manpages.conf
|
|
$(QUIET)$(ECHO) Building $@
|
|
$(QUIET)$(A2X) -d manpage -f xhtml --asciidoc-opts "-f config/manpages.conf" --stylesheet=vkman.css $(A2XOPTS) --destination-dir=$(@D) $<
|
|
|
|
$(MANHTMLDIR):
|
|
$(QUIET)$(MKDIR) $@
|
|
|
|
$(MANPAGEDIR):
|
|
$(QUIET)$(MKDIR) $@
|
|
|
|
# Man page targets for HTML and PDF single-file documents
|
|
|
|
manpdf: $(OUTDIR)/apispec.pdf
|
|
|
|
manhtml: $(OUTDIR)/apispec.html
|
|
|
|
$(OUTDIR)/apispec.pdf: $(CONFFILE) man/apispec.txt $(MANSOURCES) $(MANCOPYRIGHT) $(PDFXSL)
|
|
$(QUIET)if test ! -d $(OUTDIR) ; then $(MKDIR) $(OUTDIR) ; fi
|
|
$(QUIET)$(A2X) -f pdf $(A2XDBLATEXOPTS) $(A2XOPTS) --icons man/apispec.txt --destination-dir=$(OUTDIR)
|
|
|
|
$(OUTDIR)/apispec.html: $(CONFFILE) man/apispec.txt $(MANSOURCES) $(MANCOPYRIGHT) $(SVGFILES)
|
|
$(QUIET)if test ! -d $(OUTDIR) ; then $(MKDIR) $(OUTDIR) ; fi
|
|
$(QUIET)$(ASCIIDOC) -b html5 $(ADOCOPTS) -d book -b html --out-file=$(OUTDIR)/apispec.html man/apispec.txt
|
|
|
|
$(HTMLDIR)/images/%: images/%
|
|
$(QUIET)$(MKDIR) $(@D)
|
|
$(QUIET)$(CP) $< $@
|
|
|
|
# Automated (though heuristic) checks of consistency in the spec and
|
|
# ref page sources
|
|
|
|
# Validate includes in spec source vs. includes actually in the tree
|
|
# Generates file in $(CHECKDIR)
|
|
# $(NOTINSPEC) notInSpec.txt - include files only found in XML, not in spec
|
|
# Intermediate files removed after the run
|
|
# $(ACTUAL) - include files generated from vk.xml
|
|
# $(INSPEC) - include files referenced from the spec (not ref page) source
|
|
# Other files which could be generated but are basically useless
|
|
# include files only found in the spec source - comm -13 $(ACTUAL) $(INSPEC)
|
|
# include files both existing and referenced by the spec - comm -12 $(ACTUAL) $(INSPEC)
|
|
INCFILES = $(CHECKDIR)/incfiles
|
|
ACTUAL = $(CHECKDIR)/actual
|
|
INSPEC = $(CHECKDIR)/inspec
|
|
NOTINSPEC = $(CHECKDIR)/notInSpec.txt
|
|
checkinc:
|
|
$(QUIET)if test ! -d $(CHECKDIR) ; then $(MKDIR) $(CHECKDIR) ; fi
|
|
$(QUIET)ls $(INCLUDES) | sort > $(ACTUAL)
|
|
$(QUIET)cat $(CHAPTERS) | \
|
|
egrep '^include::\.\./' | tr -d '[]' | \
|
|
sed -e 's#^include::\.\./##g' | sort > $(INCFILES)
|
|
$(QUIET)echo "List of API include files repeatedly included in the API specification" > $(NOTINSPEC)
|
|
$(QUIET)echo "----------------------------------------------------------------------" >> $(NOTINSPEC)
|
|
$(QUIET)uniq -d $(INCFILES) >> $(NOTINSPEC)
|
|
$(QUIET)(echo ; echo "List of API include files not referenced in the API specification") >> $(NOTINSPEC)
|
|
$(QUIET)echo "-----------------------------------------------------------------" >> $(NOTINSPEC)
|
|
$(QUIET)comm -23 $(ACTUAL) $(INCFILES) >> $(NOTINSPEC)
|
|
$(QUIET)echo "Include files not found in the spec source are in $(CHECKDIR)/notInSpec.txt"
|
|
$(QUIET)$(RM) $(INCFILES) $(ACTUAL) $(INSPEC)
|
|
|
|
# Validate link tags in spec and ref page sources against vk.xml
|
|
# (represented in vkapi.py, which is autogenerated along with the
|
|
# headers and ref page includes).
|
|
# Generates files in $(CHECKDIR):
|
|
# specErrs.txt - errors & warnings in API spec
|
|
# manErrs.txt - errors & warnings in man pages
|
|
checklinks:
|
|
$(QUIET)if test ! -d $(CHECKDIR) ; then $(MKDIR) $(CHECKDIR) ; fi
|
|
$(QUIET)echo "Generating link checks for spec (specErrs.txt) and man pages (manErrs.txt)"
|
|
$(QUIET)$(PYTHON) checkLinks.py -follow man/[Vv][Kk]*.txt > $(CHECKDIR)/manErrs.txt
|
|
$(QUIET)$(PYTHON) checkLinks.py -follow $(CHAPTERS) > $(CHECKDIR)/specErrs.txt
|
|
|
|
# README file with build instructions
|
|
README.html: README.txt
|
|
$(ASCIIDOC) -b html5 README.txt
|