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