• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Copyright 2014-2021 The Khronos Group Inc.
2#
3# SPDX-License-Identifier: Apache-2.0
4
5# Vulkan Specification makefile
6#
7# To build the spec with a specific version included, set the
8# $(VERSIONS) variable on the make command line to a space-separated
9# list of version names (e.g. VK_VERSION_1_2) *including all previous
10# versions of the API* (e.g. VK_VERSION_1_1 must also include
11# VK_VERSION_1_0). $(VERSIONS) is converted into asciidoc and generator
12# script arguments $(VERSIONATTRIBS) and $(VERSIONOPTIONS)
13#
14# To build the specification / reference pages (refpages) with optional
15# extensions included, set the $(EXTENSIONS) variable on the make
16# command line to a space-separated list of extension names.
17# $(EXTENSIONS) is converted into asciidoc and generator script
18# arguments $(EXTATTRIBS) and $(EXTOPTIONS).
19
20# If a recipe fails, delete its target file. Without this cleanup, the leftover
21# file from the failed recipe can falsely satisfy dependencies on subsequent
22# runs of `make`.
23.DELETE_ON_ERROR:
24
25VERSIONS := VK_VERSION_1_0 VK_VERSION_1_1 VK_VERSION_1_2
26VERSIONATTRIBS := $(foreach version,$(VERSIONS),-a $(version))
27VERSIONOPTIONS := $(foreach version,$(VERSIONS),-feature $(version))
28
29EXTS := $(sort $(EXTENSIONS) $(DIFFEXTENSIONS))
30EXTATTRIBS := $(foreach ext,$(EXTS),-a $(ext))
31EXTOPTIONS := $(foreach ext,$(EXTS),-extension $(ext))
32
33# APITITLE can be set to extra text to append to the document title,
34# normally used when building with extensions included.
35APITITLE =
36
37# IMAGEOPTS is normally set to generate inline SVG images, but can be
38# overridden to an empty string, since the inline option doesn't work
39# well with our HTML diffs.
40IMAGEOPTS = inline
41
42# The default 'all' target builds the following sub-targets:
43#  html - HTML single-page API specification
44#  pdf - PDF single-page API specification
45#  styleguide - HTML5 single-page "Documentation and Extensions" guide
46#  registry - HTML5 single-page XML Registry Schema documentation
47#  manhtml - HTML5 single-page reference guide - NOT SUPPORTED
48#  manpdf - PDF reference guide - NOT SUPPORTED
49#  manhtmlpages - HTML5 separate per-feature refpages
50#  allchecks - Python sanity checker for script markup and macro use
51
52all: alldocs allchecks
53
54alldocs: allspecs allman proposals
55
56allspecs: html pdf styleguide registry
57
58allman: manhtmlpages
59
60# check_spec_links.py looks for proper use of custom markup macros
61#   --ignore_count 0 can be incremented if there are unfixable errors
62# xml_consistency.py performs various XML consistency checks
63# check_undefined looks for untagged use of 'undefined' in spec sources
64# reflow.py looks for asciidoctor conditionals inside VU statements;
65#   and for duplicated VUID numbers, but only in spec sources.
66allchecks:
67	$(PYTHON) $(SCRIPTS)/check_spec_links.py -Werror --ignore_count 0
68	$(PYTHON) $(SCRIPTS)/xml_consistency.py
69	$(SCRIPTS)/ci/check_undefined
70	$(PYTHON) $(SCRIPTS)/reflow.py -nowrite -noflow -check FAIL -checkVUID FAIL $(SPECFILES)
71
72# Note that the := assignments below are immediate, not deferred, and
73# are therefore order-dependent in the Makefile
74
75QUIET	 ?= @
76VERYQUIET?= @
77PYTHON	 ?= python3
78ASCIIDOC ?= asciidoctor
79RUBY	 = ruby
80NODEJS	 = node
81PATCH	 = patch
82RM	 = rm -f
83RMRF	 = rm -rf
84MKDIR	 = mkdir -p
85CP	 = cp
86ECHO	 = echo
87GS_EXISTS := $(shell command -v gs 2> /dev/null)
88
89# Path to scripts used in generation
90SCRIPTS  = $(CURDIR)/scripts
91
92# Target directories for output files
93# HTMLDIR - 'html' target
94# PDFDIR - 'pdf' target
95# CHECKDIR - 'allchecks' target
96OUTDIR	  = $(GENERATED)/out
97HTMLDIR   = $(OUTDIR)/html
98VUDIR	  = $(OUTDIR)/validation
99PDFDIR	  = $(OUTDIR)/pdf
100CHECKDIR  = $(OUTDIR)/checks
101PROPOSALDIR = $(OUTDIR)/proposals
102
103# PDF Equations are written to SVGs, this dictates the location to store those files (temporary)
104PDFMATHDIR:=$(OUTDIR)/equations_temp
105
106# Set VERBOSE to -v to see what asciidoc is doing.
107VERBOSE =
108
109# asciidoc attributes to set (defaults are usually OK)
110# NOTEOPTS sets options controlling which NOTEs are generated
111# PATCHVERSION must equal VK_HEADER_VERSION from vk.xml
112# ATTRIBOPTS sets the API revision and enables KaTeX generation
113# VERSIONATTRIBS sets attributes for enabled API versions (set above
114#	     based on $(VERSIONS))
115# EXTATTRIBS sets attributes for enabled extensions (set above based on
116#	     $(EXTENSIONS))
117# EXTRAATTRIBS sets additional attributes, if passed to make
118# ADOCMISCOPTS miscellaneous options controlling error behavior, etc.
119# ADOCEXTS asciidoctor extensions to load
120# ADOCOPTS options for asciidoc->HTML5 output
121
122NOTEOPTS     = -a editing-notes -a implementation-guide
123PATCHVERSION = 198
124
125ifneq (,$(findstring VK_VERSION_1_2,$(VERSIONS)))
126SPECMINOR = 2
127else
128ifneq (,$(findstring VK_VERSION_1_1,$(VERSIONS)))
129SPECMINOR = 1
130else
131SPECMINOR = 0
132endif
133endif
134
135SPECREVISION = 1.$(SPECMINOR).$(PATCHVERSION)
136
137# Spell out ISO 8601 format as not all date commands support --rfc-3339
138SPECDATE     = $(shell echo `date -u "+%Y-%m-%d %TZ"`)
139
140# Generate Asciidoc attributes for spec remark
141# Could use `git log -1 --format="%cd"` to get branch commit date
142# This used to be a dependency in the spec html/pdf targets,
143# but that's likely to lead to merge conflicts. Just regenerate
144# when pushing a new spec for review to the sandbox.
145# The dependency on HEAD is per the suggestion in
146# http://neugierig.org/software/blog/2014/11/binary-revisions.html
147SPECREMARK = from git branch: $(shell echo `git symbolic-ref --short HEAD 2> /dev/null || echo Git branch not available`) \
148	     commit: $(shell echo `git log -1 --format="%H" 2> /dev/null || echo Git commit not available`)
149
150# Base path to SPIR-V extensions on the web.
151SPIRVPATH = https://htmlpreview.github.io/?https://github.com/KhronosGroup/SPIRV-Registry/blob/master/extensions
152
153# Some of the attributes used in building all spec documents:
154#   chapters - absolute path to chapter sources
155#   appendices - absolute path to appendix sources
156#   images - absolute path to images
157#   generated - absolute path to generated sources
158#   refprefix - controls which generated extension metafiles are
159#	included at build time. Must be empty for specification,
160#	'refprefix.' for refpages (see ADOCREFOPTS below).
161ATTRIBOPTS   = -a revnumber="$(SPECREVISION)" \
162	       -a revdate="$(SPECDATE)" \
163	       -a revremark="$(SPECREMARK)" \
164	       -a apititle="$(APITITLE)" \
165	       -a stem=latexmath \
166	       -a imageopts="$(IMAGEOPTS)" \
167	       -a config=$(CURDIR)/config \
168	       -a appendices=$(CURDIR)/appendices \
169	       -a chapters=$(CURDIR)/chapters \
170	       -a images=$(IMAGEPATH) \
171	       -a generated=$(GENERATED) \
172	       -a spirv="$(SPIRVPATH)" \
173	       -a refprefix \
174	       $(VERSIONATTRIBS) \
175	       $(EXTATTRIBS) \
176	       $(EXTRAATTRIBS)
177ADOCMISCOPTS = --failure-level ERROR
178# Non target-specific Asciidoctor extensions and options
179# Look in $(GENERATED) for explicitly required non-extension Ruby, such
180# as api.rb
181ADOCEXTS     = -I$(GENERATED) -r $(CURDIR)/config/spec-macros.rb -r $(CURDIR)/config/tilde_open_block.rb
182ADOCOPTS     = -d book $(ADOCMISCOPTS) $(ATTRIBOPTS) $(NOTEOPTS) $(VERBOSE) $(ADOCEXTS)
183
184# HTML target-specific Asciidoctor extensions and options
185ADOCHTMLEXTS = -r $(CURDIR)/config/katex_replace.rb \
186	       -r $(CURDIR)/config/loadable_html.rb \
187	       -r $(CURDIR)/config/vuid-expander.rb \
188	       -r $(CURDIR)/config/rouge-extend-css.rb
189
190# ADOCHTMLOPTS relies on the relative runtime path from the output HTML
191# file to the katex scripts being set with KATEXDIR. This is overridden
192# by some targets.
193# ADOCHTMLOPTS also relies on the absolute build-time path to the
194# 'stylesdir' containing our custom CSS.
195KATEXSRCDIR  = $(CURDIR)/katex
196KATEXDIR     = katex
197ADOCHTMLOPTS = $(ADOCHTMLEXTS) -a katexpath=$(KATEXDIR) \
198	       -a stylesheet=khronos.css \
199	       -a stylesdir=$(CURDIR)/config \
200	       -a sectanchors
201
202# PDF target-specific Asciidoctor extensions and options
203ADOCPDFEXTS  = -r asciidoctor-pdf \
204	       -r asciidoctor-mathematical \
205	       -r $(CURDIR)/config/asciidoctor-mathematical-ext.rb \
206	       -r $(CURDIR)/config/vuid-expander.rb
207ADOCPDFOPTS  = $(ADOCPDFEXTS) -a mathematical-format=svg \
208	       -a imagesoutdir=$(PDFMATHDIR) \
209	       -a pdf-fontsdir=config/fonts,GEM_FONTS_DIR \
210	       -a pdf-stylesdir=config/themes -a pdf-style=pdf
211
212# Valid usage-specific Asciidoctor extensions and options
213ADOCVUEXTS = -r $(CURDIR)/config/vu-to-json.rb
214ADOCVUOPTS = $(ADOCVUEXTS)
215
216.PHONY: directories
217
218# Images used by the spec. These are included in generated HTML now.
219IMAGEPATH = $(CURDIR)/images
220SVGFILES  = $(wildcard $(IMAGEPATH)/*.svg)
221
222# Top-level spec source file
223SPECSRC := vkspec.txt
224# Static files making up sections of the API spec.
225SPECFILES = $(wildcard chapters/[A-Za-z]*.txt chapters/*/[A-Za-z]*.txt appendices/[A-Za-z]*.txt)
226# Shorthand for where different types generated files go.
227# All can be relocated by overriding GENERATED in the make invocation.
228GENERATED      = $(CURDIR)/gen
229REFPATH        = $(GENERATED)/refpage
230APIPATH        = $(GENERATED)/api
231VALIDITYPATH   = $(GENERATED)/validity
232HOSTSYNCPATH   = $(GENERATED)/hostsynctable
233METAPATH       = $(GENERATED)/meta
234INTERFACEPATH  = $(GENERATED)/interfaces
235SPIRVCAPPATH   = $(GENERATED)/spirvcap
236PROPOSALPATH   = $(CURDIR)/proposals
237# timeMarker is a proxy target created when many generated files are
238# made at once
239APIDEPEND      = $(APIPATH)/timeMarker
240VALIDITYDEPEND = $(VALIDITYPATH)/timeMarker
241HOSTSYNCDEPEND = $(HOSTSYNCPATH)/timeMarker
242METADEPEND     = $(METAPATH)/timeMarker
243INTERFACEDEPEND = $(INTERFACEPATH)/timeMarker
244SPIRVCAPDEPEND = $(SPIRVCAPPATH)/timeMarker
245RUBYDEPEND     = $(GENERATED)/api.rb
246# All generated dependencies
247GENDEPENDS     = $(APIDEPEND) $(VALIDITYDEPEND) $(HOSTSYNCDEPEND) $(METADEPEND) $(INTERFACEDEPEND) $(SPIRVCAPDEPEND) $(RUBYDEPEND)
248# All non-format-specific dependencies
249COMMONDOCS     = $(SPECFILES) $(GENDEPENDS)
250
251# Script to add href to anchors
252GENANCHORLINKS = $(SCRIPTS)/genanchorlinks.py
253# Script to translate math on build time
254TRANSLATEMATH = $(NODEJS) $(SCRIPTS)/translate_math.js $(KATEXSRCDIR)/katex.min.js
255
256# Install katex in $(OUTDIR)/katex for reference by all HTML targets
257katexinst: KATEXDIR = katex
258katexinst: $(OUTDIR)/$(KATEXDIR)
259
260$(OUTDIR)/$(KATEXDIR): $(KATEXSRCDIR)
261	$(QUIET)$(MKDIR) $(OUTDIR)
262	$(QUIET)$(RMRF)  $(OUTDIR)/$(KATEXDIR)
263# We currently only need the css and fonts, but copy it whole anyway
264	$(QUIET)$(CP) -rf $(KATEXSRCDIR) $(OUTDIR)
265
266# Spec targets
267# There is some complexity to try and avoid short virtual targets like 'html'
268# causing specs to *always* be regenerated.
269
270CHUNKER = $(CURDIR)/scripts/asciidoctor-chunker/asciidoctor-chunker.js
271CHUNKINDEX = $(CURDIR)/config/chunkindex
272# Only the $(CHUNKER) step is required unless the search index is to be
273# generated and incorporated into the chunked spec.
274#
275# Dropped $(QUIET) for now
276# Should set NODE_PATH=/usr/local/lib/node_modules or wherever, outside Makefile
277# Copying chunked.js into target avoids a warning from the chunker
278chunked: $(HTMLDIR)/vkspec.html $(SPECSRC) $(COMMONDOCS)
279	$(QUIET)$(CHUNKINDEX)/addscripts.sh $(HTMLDIR)/vkspec.html $(HTMLDIR)/prechunked.html
280	$(QUIET)$(CP) $(CHUNKINDEX)/chunked.css $(CHUNKINDEX)/chunked.js \
281	    $(CHUNKINDEX)/lunr.js $(HTMLDIR)
282	$(QUIET)$(NODEJS) $(CHUNKER) $(HTMLDIR)/prechunked.html -o $(HTMLDIR)
283	$(QUIET)$(RM) $(HTMLDIR)/prechunked.html
284	$(QUIET)$(RUBY) $(CHUNKINDEX)/generate-index.rb $(HTMLDIR)/chap*html | \
285	    $(NODEJS) $(CHUNKINDEX)/build-index.js > $(HTMLDIR)/search.index.js
286
287# This is a temporary target while the new chunker is pre-release.
288# Eventually we will either pull the chunker into CI, or permanently
289# store a copy of the short JavaScript chunker in this repository.
290CHUNKERVERSION = asciidoctor-chunker_v1.0.0
291CHUNKURL = https://github.com/wshito/asciidoctor-chunker/releases/download/v1.0.0/$(CHUNKERVERSION).zip
292getchunker:
293	wget $(CHUNKURL) -O $(CHUNKERVERSION).zip
294	unzip $(CHUNKERVERSION).zip
295	mv $(CHUNKERVERSION)/* scripts/asciidoctor-chunker/
296	rm -rf $(CHUNKERVERSION).zip $(CHUNKERVERSION)
297
298html: $(HTMLDIR)/vkspec.html $(SPECSRC) $(COMMONDOCS)
299
300$(HTMLDIR)/vkspec.html: KATEXDIR = ../katex
301$(HTMLDIR)/vkspec.html: $(SPECSRC) $(COMMONDOCS) katexinst
302	$(QUIET)$(ASCIIDOC) -b html5 $(ADOCOPTS) $(ADOCHTMLOPTS) -o $@ $(SPECSRC)
303	$(QUIET)$(PYTHON) $(GENANCHORLINKS) $@ $@
304	$(QUIET)$(TRANSLATEMATH) $@
305
306diff_html: $(HTMLDIR)/diff.html $(SPECSRC) $(COMMONDOCS)
307
308$(HTMLDIR)/diff.html: KATEXDIR = ../katex
309$(HTMLDIR)/diff.html: $(SPECSRC) $(COMMONDOCS) katexinst
310	$(QUIET)$(ASCIIDOC) -b html5 $(ADOCOPTS) $(ADOCHTMLOPTS) \
311	    -a diff_extensions="$(DIFFEXTENSIONS)" \
312	    -r $(CURDIR)/config/extension-highlighter.rb --trace \
313	    -o $@ $(SPECSRC)
314	$(QUIET)$(TRANSLATEMATH) $@
315
316# PDF optimizer - usage $(OPTIMIZEPDF) in.pdf out.pdf
317# OPTIMIZEPDFOPTS=--compress-pages is slightly better, but much slower
318OPTIMIZEPDF = hexapdf optimize $(OPTIMIZEPDFOPTS)
319
320pdf: $(PDFDIR)/vkspec.pdf $(SPECSRC) $(COMMONDOCS)
321
322$(PDFDIR)/vkspec.pdf: $(SPECSRC) $(COMMONDOCS)
323	$(QUIET)$(MKDIR) $(PDFDIR)
324	$(QUIET)$(MKDIR) $(PDFMATHDIR)
325	$(QUIET)$(ASCIIDOC) -b pdf $(ADOCOPTS) $(ADOCPDFOPTS) -o $@ $(SPECSRC)
326	$(QUIET)$(OPTIMIZEPDF) $@ $@.out.pdf && mv $@.out.pdf $@
327	$(QUIET)rm -rf $(PDFMATHDIR)
328
329validusage: $(VUDIR)/validusage.json $(SPECSRC) $(COMMONDOCS)
330
331$(VUDIR)/validusage.json: $(SPECSRC) $(COMMONDOCS)
332	$(QUIET)$(MKDIR) $(VUDIR)
333	$(QUIET)$(ASCIIDOC) $(ADOCOPTS) $(ADOCVUOPTS) --trace \
334	    -a json_output=$@ -o $@ $(SPECSRC)
335
336# Vulkan Documentation and Extensions, a.k.a. "Style Guide" documentation
337
338STYLESRC = styleguide.txt
339STYLEFILES = $(wildcard style/[A-Za-z]*.txt)
340
341styleguide: $(OUTDIR)/styleguide.html
342
343$(OUTDIR)/styleguide.html: KATEXDIR = katex
344$(OUTDIR)/styleguide.html: $(STYLESRC) $(STYLEFILES) $(GENDEPENDS) katexinst
345	$(QUIET)$(MKDIR) $(OUTDIR)
346	$(QUIET)$(ASCIIDOC) -b html5 $(ADOCOPTS) $(ADOCHTMLOPTS) -o $@ $(STYLESRC)
347	$(QUIET)$(TRANSLATEMATH) $@
348
349
350# Vulkan API Registry (XML Schema) documentation
351# Currently does not use latexmath / KaTeX
352
353REGSRC = registry.txt
354
355registry: $(OUTDIR)/registry.html
356
357$(OUTDIR)/registry.html: $(REGSRC) $(GENDEPENDS)
358	$(QUIET)$(MKDIR) $(OUTDIR)
359	$(QUIET)$(ASCIIDOC) -b html5 $(ADOCOPTS) $(ADOCHTMLOPTS) -o $@ $(REGSRC)
360	$(QUIET)$(TRANSLATEMATH) $@
361
362# Build proposal documents
363PROPOSALSOURCES   = $(filter-out $(PROPOSALPATH)/template.asciidoc, $(wildcard $(PROPOSALPATH)/*.asciidoc))
364PROPOSALDOCS	  = $(PROPOSALSOURCES:$(PROPOSALPATH)/%.asciidoc=$(PROPOSALDIR)/%.html)
365proposals: $(PROPOSALDOCS) $(PROPOSALSOURCES)
366
367# Proposal documents are built outside of the main specification
368$(PROPOSALDIR)/%.html: $(PROPOSALPATH)/%.asciidoc
369	$(QUIET)$(ASCIIDOC) --failure-level ERROR -b html5 -o $@ $<
370	$(QUIET) if egrep -q '\\[([]' $@ ; then \
371	    $(TRANSLATEMATH) $@ ; \
372    fi
373
374# Reflow text in spec sources
375REFLOW = $(SCRIPTS)/reflow.py
376REFLOWOPTS = -overwrite
377
378reflow:
379	$(QUIET) echo "Warning: please verify the spec outputs build without changes!"
380	$(PYTHON) $(REFLOW) $(REFLOWOPTS) $(SPECSRC) $(SPECFILES) $(STYLESRC) $(STYLEFILES)
381
382# Clean generated and output files
383
384clean: clean_html clean_pdf clean_man clean_checks clean_generated clean_validusage
385
386clean_html:
387	$(QUIET)$(RMRF) $(HTMLDIR) $(OUTDIR)/katex
388	$(QUIET)$(RM) $(OUTDIR)/apispec.html $(OUTDIR)/styleguide.html \
389	    $(OUTDIR)/registry.html
390
391clean_pdf:
392	$(QUIET)$(RMRF) $(PDFDIR) $(OUTDIR)/apispec.pdf
393
394clean_man:
395	$(QUIET)$(RMRF) $(MANHTMLDIR)
396
397clean_checks:
398	$(QUIET)$(RMRF) $(CHECKDIR)
399
400# Generated directories and files to remove
401CLEAN_GEN_PATHS = \
402    $(APIPATH) \
403    $(HOSTSYNCPATH) \
404    $(VALIDITYPATH) \
405    $(METAPATH) \
406    $(INTERFACEPATH) \
407    $(SPIRVCAPPATH) \
408    $(REFPATH) \
409    $(GENERATED)/include \
410    $(GENERATED)/__pycache__ \
411    $(PDFMATHDIR) \
412    $(GENERATED)/api.py \
413    $(GENERATED)/api.rb \
414    $(GENERATED)/extDependency.*
415
416clean_generated:
417	$(QUIET)$(RMRF) $(CLEAN_GEN_PATHS)
418
419clean_validusage:
420	$(QUIET)$(RM) $(VUDIR)/validusage.json
421
422
423# Generated refpage sources. For now, always build all refpages.
424MANSOURCES   = $(filter-out $(REFPATH)/apispec.txt, $(wildcard $(REFPATH)/*.txt))
425
426# Generation of refpage asciidoctor sources by extraction from the
427# specification.
428#
429# Should have a proper dependency causing the man page sources to be
430# generated by running genRef (once), but adding $(MANSOURCES) to the
431# targets causes genRef to run once/target.
432#
433# Should pass in $(EXTOPTIONS) to determine which pages to generate.
434# For now, all core and extension refpages are extracted by genRef.py.
435GENREF = $(SCRIPTS)/genRef.py
436LOGFILE = $(REFPATH)/refpage.log
437refpages: $(REFPATH)/apispec.txt
438$(REFPATH)/apispec.txt: $(SPECFILES) $(GENREF) $(SCRIPTS)/reflib.py $(GENERATED)/api.py
439	$(QUIET)$(MKDIR) $(REFPATH)
440	$(PYTHON) $(GENREF) -genpath $(GENERATED) -basedir $(REFPATH) \
441	    -log $(LOGFILE) -extpath $(CURDIR)/appendices \
442	    $(EXTOPTIONS) $(SPECFILES)
443
444# These targets are HTML5 refpages
445#
446# The recursive $(MAKE) is an apparently unavoidable hack, since the
447# actual list of man page sources isn't known until after
448# $(REFPATH)/apispec.txt is generated. $(GENDEPENDS) is generated before
449# running the recursive make, so it doesn't trigger twice
450# $(SUBMAKEOPTIONS) suppresses the redundant "Entering / leaving"
451# messages make normally prints out, similarly to suppressing make
452# command output logging in the individual refpage actions below.
453SUBMAKEOPTIONS = --no-print-directory
454manhtmlpages: $(REFPATH)/apispec.txt $(GENDEPENDS)
455	$(QUIET) echo "manhtmlpages: building HTML refpages with these options:"
456	$(QUIET) echo $(ASCIIDOC) -b html5 $(ADOCOPTS) $(ADOCHTMLOPTS) \
457	    $(ADOCREFOPTS) -d manpage -o REFPAGE.html REFPAGE.txt
458	$(MAKE) $(SUBMAKEOPTIONS) -e buildmanpages
459
460# Build the individual refpages, then the symbolic links from aliases
461MANHTMLDIR  = $(OUTDIR)/man/html
462MANHTML     = $(MANSOURCES:$(REFPATH)/%.txt=$(MANHTMLDIR)/%.html)
463buildmanpages: $(MANHTML)
464	$(MAKE) $(SUBMAKEOPTIONS) -e manaliases
465
466# Asciidoctor options to build refpages
467#
468# ADOCREFOPTS *must* be placed after ADOCOPTS in the command line, so
469# that it can override spec attribute values.
470#
471# cross-file-links makes custom macros link to other refpages
472# refprefix includes the refpage (not spec) extension metadata.
473# isrefpage is for refpage-specific content
474# html_spec_relative is where to find the full specification
475ADOCREFOPTS = -a cross-file-links -a refprefix='refpage.' -a isrefpage \
476	      -a html_spec_relative='../../html/vkspec.html'
477
478# The refpage build process normally generates far too much output, so
479# use VERYQUIET instead of QUIET
480# Running translate_math.js on every refpage is slow and most of them
481# don't contain math, so do a quick search for latexmath delimiters.
482$(MANHTMLDIR)/%.html: KATEXDIR = ../../katex
483$(MANHTMLDIR)/%.html: $(REFPATH)/%.txt $(GENDEPENDS) katexinst
484	$(VERYQUIET)echo "Building $@ from $< using default options"
485	$(VERYQUIET)$(MKDIR) $(MANHTMLDIR)
486	$(VERYQUIET)$(ASCIIDOC) -b html5 $(ADOCOPTS) $(ADOCHTMLOPTS) $(ADOCREFOPTS) \
487	    -d manpage -o $@ $<
488	$(VERYQUIET)if egrep -q '\\[([]' $@ ; then \
489	    $(TRANSLATEMATH) $@ ; \
490	fi
491
492# The 'manhtml' and 'manpdf' targets are NO LONGER SUPPORTED by Khronos.
493# They generate HTML5 and PDF single-file versions of the refpages.
494# The generated refpage sources are included by $(REFPATH)/apispec.txt,
495# and are always generated along with that file. Therefore there's no
496# need for a recursive $(MAKE) or a $(MANHTML) dependency, unlike the
497# manhtmlpages target.
498
499manpdf: $(OUTDIR)/apispec.pdf
500
501$(OUTDIR)/apispec.pdf: $(SPECVERSION) $(REFPATH)/apispec.txt $(SVGFILES) $(GENDEPENDS)
502	$(QUIET)$(MKDIR) $(OUTDIR)
503	$(QUIET)$(MKDIR) $(PDFMATHDIR)
504	$(QUIET)$(ASCIIDOC) -b pdf -a html_spec_relative='html/vkspec.html' \
505	    $(ADOCOPTS) $(ADOCPDFOPTS) -o $@ $(REFPATH)/apispec.txt
506	$(QUIET)$(OPTIMIZEPDF) $@ $@.out.pdf && mv $@.out.pdf $@
507
508manhtml: $(OUTDIR)/apispec.html
509
510$(OUTDIR)/apispec.html: KATEXDIR = katex
511$(OUTDIR)/apispec.html: ADOCMISCOPTS =
512$(OUTDIR)/apispec.html: $(SPECVERSION) $(REFPATH)/apispec.txt $(SVGFILES) $(GENDEPENDS) katexinst
513	$(QUIET)$(MKDIR) $(OUTDIR)
514	$(QUIET)$(ASCIIDOC) -b html5 -a html_spec_relative='html/vkspec.html' \
515	    $(ADOCOPTS) $(ADOCHTMLOPTS) -o $@ $(REFPATH)/apispec.txt
516	$(QUIET)$(TRANSLATEMATH) $@
517
518# Create links for refpage aliases
519
520MAKEMANALIASES = $(SCRIPTS)/makemanaliases.py
521manaliases: $(GENERATED)/api.py
522	$(PYTHON) $(MAKEMANALIASES) -genpath $(GENERATED) -refdir $(MANHTMLDIR)
523
524# Targets generated from the XML and registry processing scripts
525#   $(GENERATED)/api.py - Python encoding of the registry
526# The $(...DEPEND) targets are files named 'timeMarker' in generated
527# target directories. They serve as proxies for the multiple generated
528# files written for each target:
529#   apiinc / proxy $(APIDEPEND) - API interface include files in $(APIPATH)
530#   hostsyncinc / proxy $(HOSTSYNCDEPEND) - host sync table include files in $(HOSTSYNCPATH)
531#   validinc / proxy $(VALIDITYDEPEND) - API validity include files in $(VALIDITYPATH)
532#   extinc / proxy $(METADEPEND) - extension appendix metadata include files in $(METAPATH)
533#
534# $(VERSIONOPTIONS) specifies the core API versions which are included
535# in these targets, and is set above based on $(VERSIONS)
536#
537# $(EXTOPTIONS) specifies the extensions which are included in these
538# targets, and is set above based on $(EXTENSIONS).
539#
540# $(GENVKEXTRA) are extra options that can be passed to genvk.py, e.g.
541# '-diag diag'
542
543REGISTRY   = xml
544VKXML	   = $(REGISTRY)/vk.xml
545GENVK	   = $(SCRIPTS)/genvk.py
546GENVKOPTS  = $(VERSIONOPTIONS) $(EXTOPTIONS) $(GENVKEXTRA) -registry $(VKXML)
547GENVKEXTRA =
548
549scriptapi: pyapi rubyapi
550
551pyapi $(GENERATED)/api.py: $(VKXML) $(GENVK)
552	$(PYTHON) $(GENVK) $(GENVKOPTS) -o $(GENERATED) api.py
553
554rubyapi $(GENERATED)/api.rb: $(VKXML) $(GENVK)
555	$(PYTHON) $(GENVK) $(GENVKOPTS) -o $(GENERATED) api.rb
556
557apiinc: $(APIDEPEND)
558
559$(APIDEPEND): $(VKXML) $(GENVK) $(GENERATED)/api.py
560	$(QUIET)$(MKDIR) $(APIPATH)
561	$(QUIET)$(PYTHON) $(GENVK) $(GENVKOPTS) -o $(APIPATH) -genpath $(GENERATED) apiinc
562
563hostsyncinc: $(HOSTSYNCDEPEND)
564
565$(HOSTSYNCDEPEND): $(VKXML) $(GENVK)
566	$(QUIET)$(MKDIR) $(HOSTSYNCPATH)
567	$(QUIET)$(PYTHON) $(GENVK) $(GENVKOPTS) -o $(HOSTSYNCPATH) hostsyncinc
568
569validinc: $(VALIDITYDEPEND)
570
571$(VALIDITYDEPEND): $(VKXML) $(GENVK)
572	$(QUIET)$(MKDIR) $(VALIDITYPATH)
573	$(QUIET)$(PYTHON) $(GENVK) $(GENVKOPTS) -o $(VALIDITYPATH) validinc
574
575extinc: $(METAPATH)/timeMarker
576
577$(METADEPEND): $(VKXML) $(GENVK)
578	$(QUIET)$(MKDIR) $(METAPATH)
579	$(QUIET)$(PYTHON) $(GENVK) $(GENVKOPTS) -o $(METAPATH) extinc
580
581interfaceinc: $(INTERFACEPATH)/timeMarker
582
583$(INTERFACEDEPEND): $(VKXML) $(GENVK)
584	$(QUIET)$(MKDIR) $(INTERFACEPATH)
585	$(QUIET)$(PYTHON) $(GENVK) $(GENVKOPTS) -o $(INTERFACEPATH) interfaceinc
586
587# This generates a single file, so SPIRVCAPDEPEND is the full path to
588# the file, rather than to a timeMarker in the same directory.
589spirvcapinc: $(SPIRVCAPDEPEND)
590
591$(SPIRVCAPDEPEND): $(VKXML) $(GENVK)
592	$(QUIET)$(MKDIR) $(SPIRVCAPPATH)
593	$(QUIET)$(PYTHON) $(GENVK) $(GENVKOPTS) -o $(SPIRVCAPPATH) spirvcapinc
594
595# Debugging aid - generate all files from registry XML
596# This leaves out $(GENERATED)/extDependency.sh intentionally as it only
597# needs to be updated when the extension dependencies in vk.xml change.
598
599generated: $(GENERATED)/api.py $(GENDEPENDS)
600
601# Extension dependencies derived from vk.xml
602# Both Bash and Python versions are generated
603
604extDependency: $(GENERATED)/extDependency.stamp
605$(GENERATED)/extDependency.sh: $(GENERATED)/extDependency.stamp
606$(GENERATED)/extDependency.py: $(GENERATED)/extDependency.stamp
607
608DEPSCRIPT = $(SCRIPTS)/make_ext_dependency.py
609$(GENERATED)/extDependency.stamp: $(VKXML) $(DEPSCRIPT)
610	$(QUIET)$(PYTHON) $(DEPSCRIPT) \
611	    -registry $(VKXML) \
612	    -outscript $(GENERATED)/extDependency.sh \
613	    -outpy $(GENERATED)/extDependency.py
614	$(QUIET)touch $@
615