Change log for May 15, 2020 Vulkan 1.2.141 spec update:

  * Update release number to 141 for this update.
  * *Note*: Using the default build options, specification outputs will now
    be created in `gen/out/` instead of `out/`, and header files will be
    created in `gen/include/vulkan` instead of `include/vulkan`. This can be
    overridden using the `-genpath` option to the frontend scripts like
    `makeAllExts` and `makeSpec`, or by specifying `GENERATED=*path*` on the
    make command line when invoking it directly.

Github Issues:

  * Assign new elink:VkDriverId and elink:VkVendorId enums for Mesa (public
    issue 1256).

Internal Issues:

  * Fix a typo in the <<fragops-stencil, Stencil Test>> section, removing a
    sentence fragment accidentally left over from an earlier merge conflict
    resolution (internal issue 2158).
  * Typo fixes for flink:vkGetRayTracingShaderGroupHandlesKHR and
    flink:vkGetRayTracingCaptureReplayShaderGroupHandlesKHR valid usage
    statements (internal merge request 3831).
  * Add a `requiredBy` dictionary to the generated `vkapi.py` showing which
    core versions or extensions require each API (internal merge request
    3832).
  * Allow specifying multiple API names for and tags in registry processing
    scripts. Update the registry schema documentation accordingly, and
    remove the redundant `xml_supported_name_of_api` method from the
    VulkanConventions object (internal merge request 3836).
  * Consolidate generated intermediate files and output documents into
    $(GENERATED) directory, add -genpath option to scripts requiring them,
    and modify Makefile accordingly. Add a new `makeSpec` script which
    combines and extends the functionality of the `makeExt`, `makeKHR`, and
    `makeAllExts` scripts (internal merge requests 3837, 3838, 3840, 3841).
  * Add "`runtime`" to style guide and use that spelling consistently
    (internal merge request 3843).

.gitlab-ci.yml

@@ -13,8 +13,8 @@ spec-generate:
     - export NODE_PATH
     # Internal self-test of the check_spec_links script
     - ( cd scripts && py.test-3 test*.py )
-    - mkdir -p out/checks
-    - scripts/check_spec_links.py --html=out/checks/problems.html > /dev/null || true
+    - mkdir -p gen/out/checks
+    - scripts/check_spec_links.py --html=gen/out/checks/problems.html > /dev/null || true
     # Breaking the build if # of errors increases. We should manually ratchet ignore_count down as errors get fixed.
     # If there are unfixable errors, add '--ignore_count #' where '#' is the
     # number of them. This is a slightly crude way of enforcing "don't add
@@ -28,10 +28,8 @@ spec-generate:
   artifacts:
     when: always
     paths:
-      - include/
       - src/
-      - out/
-      - gen/meta/
+      - gen/
     expire_in: 1 week
 
 # Generate the vulkan C++ header (vulkan.hpp)
@@ -73,8 +71,8 @@ h-compile:
   before_script:
   # Nothing, all prerequisites are in the Docker image
   script:
-    - gcc -c -std=c11 -Iinclude -Itests -Wall -Wextra -Werror tests/htest.c
-    - clang -c -std=c11 -Iinclude -Itests -Wall -Wextra -Werror tests/htest.c
+    - gcc -c -std=c11 -Igen/include -Itests -Wall -Wextra -Werror tests/htest.c
+    - clang -c -std=c11 -Igen/include -Itests -Wall -Wextra -Werror tests/htest.c
 
 # Compile a simple test program that uses vulkan.hpp
 hpp-compile:
@@ -85,6 +83,6 @@ hpp-compile:
   before_script:
     # Nothing, all prerequisites are in the Docker image
   script:
-    - g++ -c -std=c++11 -Iinclude -IVulkan-Hpp -Wall -Wextra -Werror tests/hpptest.cpp
-    - clang++ -c -std=c++11 -Iinclude -IVulkan-Hpp -Wall -Wextra -Werror tests/hpptest.cpp
+    - g++ -c -std=c++11 -Igen/include -IVulkan-Hpp -Wall -Wextra -Werror tests/hpptest.cpp
+    - clang++ -c -std=c++11 -Igen/include -IVulkan-Hpp -Wall -Wextra -Werror tests/hpptest.cpp
   allow_failure: true

.gitlab/issue_templates/EXT_release_checklist.md

@@ -1,3 +1,4 @@
+
 <!-- Vulkan EXT Extension Development Checklist Template -->
 
 <!--
@@ -9,9 +10,10 @@ extension should be created.
 
 As progress is made on work items, fill in the italicized fields with
 appropriate data. For example, when a merge request exists, edit it
-into the "API specification merged" line in place of _MR_. When the MR
-is merged and the WG agrees that it is stable, check off the item in
-the checklist. ("Specification stable" means that all discussions are
+into the "API specification ready" line in place of _MR_. When the WG
+agrees that it is ready for release, check off the item in
+the checklist.
+("Ready for release" implies that all discussions are
 resolved and there are no MRs in flight that modify behavior defined
 by the extension and its dependencies.)
 
@@ -26,29 +28,23 @@ non-abstaining vote are in favor.
 
 ## Preconditions for creating public release issue on GitHub
 
-<!--
-An EXT extension can be released when the working group agrees that
-these preconditions are satisfied or can be waived.
-Check off any requirements that are not relevant to
-the extension in question,
-
+<!-- 
 Check off any of the following preconditions that are not relevant to
 the extension in question. Enter target dates for software artifacts
 where indicated.
 -->
 
- - [ ] Vulkan API specification merged and stable in devel,
-       or approved to merge to master (_MR_)
+ - [ ] Vulkan API specification ready for release (_MR_)
  - [ ] VAP consulted to the extent the WG considers appropriate (_VAP issue, WG discussion, or email thread_)
  - [ ] API spec naming review complete (_date_)
  - [ ] CTS tests approved with three passing implementations (_CTS request issue_, _gerrit cl_)
- - [ ] SPIR-V specification merged and stable (_MR_)
- - [ ] GLSL specification merged and stable (_MR_)
- - [ ] Vulkan Guide entry approved (_MR_)
- - [ ] GLSLang implementation release schedule agreed: target _target-date_
- - [ ] Validation compatibility changes ready to release (_MR_)
- - [ ] Validation implementation ready (_MR_ or _Issue_ if deferred)
- - [ ] Loader support (for instance extensions) release schedule agreed: target _target-date_
+ - [ ] SPIR-V specification ready for release (_MR_)
+ - [ ] GLSL specification ready for release (_MR_)
+ - [ ] Developer guidance language approved (_date_)
+ - [ ] GLSLang implementation ready for release (_MR_)
+ - [ ] Validation compatibility changes ready for release (_MR_)
+ - [ ] Validation new VU changes ready for release (_MR_ or _request issue_ if deferred)
+ - [ ] Loader support (for instance extensions) release for release (_MR_)
  - [ ] HLSL mapping defined
  - [ ] HLSL glslang support release schedule agreed: target _target-date_
  - [ ] HLSL DXC support release schedule agreed: target _target-date_

.gitlab/issue_templates/KHR_release_checklist.md

@@ -10,11 +10,12 @@ extension should be created.
 
 As progress is made on work items, fill in the italicized fields with
 appropriate data. For example, when a merge request exists, edit it
-into the "API specification merged" line in place of _MR_. When the MR
-is merged and the WG agrees that it is stable, check off the item in
-the checklist. ("Specification stable" means that all discussions are
+into the "API specification ready" line in place of _MR_.  When the WG
+agrees that it ready for a ratification vote, check off the item in
+the checklist.
+("Ready for ratification" implies that all discussions are
 resolved and there are no MRs in flight that modify behavior defined
-by the extension and its dependencies.)
+by the extension or its dependencies.)
 
 Not all requirements are relevant to all extensions. For example, an
 extension that has no language dependencies will not need SPIR-V /
@@ -26,18 +27,19 @@ non-abstaining vote are in favor.
 
 ## Preconditions for Call for Votes (CfV)
 
-<!--
-A formal CfV is issued following agreement at a Tuesday meeting that a
-vote should be held at the following Tuesday meeting. Preconditions
-for a CfV are as follows: 
+<!-- 
+Check off any of the following preconditions that are not relevant to
+the extension in question. Enter target dates for software artifacts
+where indicated.
 -->
 
- - [ ] Vulkan API specification merged and stable in devel (_MR_)
+ - [ ] Vulkan API specification ready for ratification (_MR_)
  - [ ] VAP consulted to the extent the WG considers appropriate (_VAP issue, WG discussion, or email thread_)
  - [ ] API spec naming review complete (_date_)
  - [ ] CTS tests approved with three passing implementations (_CTS request issue_, _gerrit cl_)
- - [ ] SPIR-V specification merged and stable (_MR_)
- - [ ] GLSL specification merged and stable (_MR_)
+ - [ ] SPIR-V specification ready for ratification (_MR_)
+ - [ ] GLSL specification ready for release (_MR_)
+ - [ ] Developer guidance language approved (_date_)
 
 ## Preconditions for submission to Promoters
 
@@ -54,11 +56,10 @@ where indicated.
 
  - [ ] Vulkan specification ratified by Promoters (_date_)
  - [ ] SPIR-V specification ratified by Promoters (_date_)
- - [ ] Vulkan Guide entry approved (_MR_)
- - [ ] GLSLang implementation release schedule agreed: target _target-date_
- - [ ] Validation compatibility changes ready to release (_MR_)
- - [ ] Validation implementation ready (_MR_ or _Issue_ if deferred)
- - [ ] Loader support (for instance extensions) release schedule agreed: target _target-date_
+ - [ ] GLSLang implementation ready for release (_MR_)
+ - [ ] Validation compatibility changes ready for release (_MR_)
+ - [ ] Validation new VU changes ready for release (_MR_ or _request issue_ if deferred)
+ - [ ] Loader support (for instance extensions) ready for release (_MR_)
  - [ ] HLSL mapping defined
  - [ ] HLSL glslang support release schedule agreed: target _target-date_
  - [ ] HLSL DXC support release schedule agreed: target _target-date_

BUILD.adoc

@@ -113,6 +113,7 @@ may significantly speed up the reference page builds.
 
 If you encounter problems refer to the <<troubleshooting>> section.
 
+
 [[building-versions]]
 === Building Specifications For Different API Versions
 
@@ -144,38 +145,49 @@ Makefile variable `$(EXTENSIONS)`, usually set on the make command line.
 When changing the list of extensions, it is critical to remove all generated
 files using the `clean_generated` Makefile target, as the contents of
 generated files depends on `$(EXTENSIONS)`.
-There are several helper scripts which clean these files and then build one
-or more specified targets for specified extensions:
-
-  * `makeExt` -- generate outputs with one or more extensions enabled.
-    Usage is `makeExt extension-names target(s)`, where `extension-names` is
-    a space-separated list of extension names, such as
-    `VK_EXT_debug_report`.
-    If more than one extension is specified, `extension-names` must be
-    quoted on the command line.
-  * `makeKHR` -- generate outputs with all Khronos (`VK_KHR_*`) extensions
-    enabled.
-    Usage is `makeKHR target(s)`.
-  * `makeAllExts` -- generate outputs with all Vulkan extensions enabled.
-    Usage is `makeAllExts target(s)`.
+
+The `makeSpec` wrapper script can clean generated files and then build one
+or more specification targets for a set of explicitly specified extensions,
+including all implicit extension dependencies of that set.
+It accepts these options:
+
+  * -clean - remove generated targets before building
+  * -v - print actions as well as executing them
+  * -n - print actions without executing them
+  * -genpath *path* - specify path to generated files (default `gen`)
+  * -spec *type* - build with sepcified sets of extensions.
+    *type* may be
+  ** *core* - no extensions added (default if not specified)
+  ** *khr* - all KHR extensions added
+  ** *all* - all registered extensions added
+  * -extension *extname* - build with specified extension included,
+    as well as the set specified by `-spec`.
+    Can be given multiple times.
+  * All remaining targets are arbitrary `make` options or
+    targets in the Makefile.
 
 The `target(s)` passed to these scripts are arbitrary `make` options, and
 can be used to set Makefile variables and options, as well as specify actual
-build targets; you can, for example, do:
+build targets.
+For example, to build the HTML specification with all KHR extensions
+included as well as a single vendor extension:
 
 ----
-$ ./makeAllExts -j 8 VERSIONS="VK_VERSION_1_0" html
+$ ./makeSpec -clean -spec khr -extension VK_EXT_debug_report html
 ----
 
+The scripts `makeAllExts`, `makeKHR`, and `makeExt` set appropriate options
+and invoke `makeSpec`, for compatibility.
+
 The Makefile variable `$(APITITLE)` defines an additional string which is
 appended to the specification title.
 When building with extensions enabled, this should be set to something like
 `(with extension VK_extension_name)`.
 The `makeExt`, `makeKHR`, and `makeAllExts` scripts already do this.
 
-The reference pages (the `manhtmlpages` target) must be built using
-`makeAllExts`; there are markup and scripting issues which will probably
-cause any more restricted set of refpages to fail to build.
+The reference pages (the `manhtmlpages` target) must be built using the
+`-spec all` option; there are markup and scripting issues which will
+probably cause any more restricted set of refpages to fail to build.
 
 
 [[building-diff]]
@@ -229,6 +241,7 @@ We recommend using Inkscape to modify or create new images, as we've had
 problems using SVG files created by some other tools; especially in the PDF
 builds.
 
+
 [[validation-scripts]]
 === Validation Scripts
 
@@ -259,7 +272,7 @@ The tags used are described in the
 link:https://www.khronos.org/registry/vulkan/specs/1.1/styleguide.html[style
 guide] (generated from `styleguide.txt`).
 
-We (may) eventually tool up the spec and ref pages to the point that
+We (may) eventually tool up the spec and reference pages to the point that
 anywhere there's a type or token referred to, clicking on (or perhaps
 hovering over) it in the HTML view will take reader to the definition of
 that type/token.
@@ -277,30 +290,27 @@ The reference pages are extracted from the API Specification source, which
 has been tagged to help identify boundaries of language talking about
 different commands, structures, enumerants, and other types.
 A set of Python scripts extract and lightly massage the relevant tagged
-language into corresponding ref page.
-Pages without corresponding content in the API spec are generated
-automatically, when possible (e.g. for `Vk*FlagBits` pages).
+language into corresponding reference page sources.
 
-If for some reason you want to regenerate the ref page sources from scratch
-yourself, you can do so by
+To regenerate the reference page sources from scratch yourself, execute:
 
 ----
-rm man/apispec.txt
-make apispec.txt
+make refpages
 ----
 
 The `genRef.py` script will generate many warnings, but most are just
 reminders that some pages are automatically generated.
-If everything is working correctly, all the `man/*.txt` files will be
-regenerated, but their contents will not change.
+If everything is working correctly, all the `$(GENERATED)/refpage/*.txt`
+files will be regenerated, but their contents will not change.
 
 If you add new API features to the Specification in a branch, make sure that
-the commands have the required tagging and that ref pages are generated for
-them, and build properly.
+the commands have the required tagging and that reference pages are
+generated for them, and build properly.
 
 When executing the `manhtmlpages` target in the Makefile, after building
 HTML versions of all reference pages extracted from the spec, symbolic links
-from aliases to the refpage for the API they alias will also be created.
+from aliases to the reference page for the API they alias will also be
+created.
 
 
 [[styles]]
@@ -340,8 +350,8 @@ instructions up to date.
 [[depends-docker]]
 === Khronos-Provided Docker Image
 
-Going forward, Khronos has published a Docker image containing a Debian
-Linux distribution with the entire toolchain preinstalled.
+Khronos has published a Docker image containing a Debian Linux distribution
+with the entire toolchain preinstalled.
 
 We will occasionally update this image if needed, and we recommend people
 needing to build from this repository use the Docker image.

ChangeLog.txt

@@ -8,6 +8,46 @@ public pull requests that have been accepted.
 
 -----------------------------------------------------
 
+Change log for May 15, 2020 Vulkan 1.2.141 spec update:
+
+  * Update release number to 141 for this update.
+  * *Note*: Using the default build options, specification outputs will now
+    be created in `gen/out/` instead of `out/`, and header files will be
+    created in `gen/include/vulkan` instead of `include/vulkan`. This can be
+    overridden using the `-genpath` option to the frontend scripts like
+    `makeAllExts` and `makeSpec`, or by specifying `GENERATED=*path*` on the
+    make command line when invoking it directly.
+
+Github Issues:
+
+  * Assign new elink:VkDriverId and elink:VkVendorId enums for Mesa (public
+    issue 1256).
+
+Internal Issues:
+
+  * Fix a typo in the <<fragops-stencil, Stencil Test>> section, removing a
+    sentence fragment accidentally left over from an earlier merge conflict
+    resolution (internal issue 2158).
+  * Typo fixes for flink:vkGetRayTracingShaderGroupHandlesKHR and
+    flink:vkGetRayTracingCaptureReplayShaderGroupHandlesKHR valid usage
+    statements (internal merge request 3831).
+  * Add a `requiredBy` dictionary to the generated `vkapi.py` showing which
+    core versions or extensions require each API (internal merge request
+    3832).
+  * Allow specifying multiple API names for and tags in registry processing
+    scripts. Update the registry schema documentation accordingly, and
+    remove the redundant `xml_supported_name_of_api` method from the
+    VulkanConventions object (internal merge request 3836).
+  * Consolidate generated intermediate files and output documents into
+    $(GENERATED) directory, add -genpath option to scripts requiring them,
+    and modify Makefile accordingly. Add a new `makeSpec` script which
+    combines and extends the functionality of the `makeExt`, `makeKHR`, and
+    `makeAllExts` scripts (internal merge requests 3837, 3838, 3840, 3841).
+  * Add "`runtime`" to style guide and use that spelling consistently
+    (internal merge request 3843).
+
+-----------------------------------------------------
+
 Change log for May 3, 2020 Vulkan 1.2.140 spec update:
 
   * Update release number to 140 for this update.