BUILD.md
file in each repository for information on how to clone and build the projects.The first step of integrating Vulkan header updates is to checkout and build the desired Vulkan-Headers commit. Typically this is the latest tagged release.
Pull and build the dependent repositories
Update the Vulkan-Loader, Vulkan-ValidationLayers, and Vulkan-Tools known-good files
If the known-good of a repository needs to be updated, all repositories of interest that appear in its known-good files must be updated first using the procedure described in this wiki. See section 5. Update the Known Good Files for a list of dependencies per repository. The following list indicates the preferred known-good update order:
Notes:
master
branchNavigate to the directory of the project of interest and checkout the master
branch. Pull in the most recent commits.
scripts/generate_source.py
Using your favorite command prompt, navigate to the scripts
directory and run the generate_source.py
script. This script requires the specification of the location of the Vulkan-Headers/registry
directory on the system. An example of how to run this script:
./generate_source.py ../../Vulkan-Headers/registry/
genvk.py
changesAll Khronos repositories and LunarG/VulkanTools contain a flavor of Vulkan-Headers's genvk.py
. If genvk.py
in the Vulkan-Headers repository is modified, the same changes must be made to each version of the file in each repository as part of the header update.
In Vulkan-ValidationLayers, every time the generate_source.py
script is run a new VUID database is generated. When VUIDs are added, removed, or modified consistency testing must be performed. The vk_validation_stats.py
script found in the ValidationLayers scripts
directory can be used to report consistency warnings using the -c
option.
./vk_validation_stats.py ../../Vulkan-Headers/registry/validusage.json -c
All consistency warnings must be resolved and included in the pull request for the repository's known-good update.
Build the project, referring to the BUILD.md
file in the directory if necessary.
To test the Vulkan-Loader build, run the loader tests (run_all_tests.sh
) found in the build/tests
directory. Information on how to build and run the tests can be found in the Vulkan-Loader BUILD.md
file. Note: The VK_LAYER_PATH
environment variable must be set to point at the layers found in Vulkan-Loader/build/tests/layers
when running the loader tests.
To test the Vulkan-ValidationLayers build, run the validation layers tests (vk_layer_validation_tests
) found in the build/tests
directory. Information on how to build and run the tests can be found in the Vulkan-ValidationLayers BUILD.md
file.
To test the Vulkan-Tools build, run vkcube
and verify vulkaninfo
produces reasonable output. More information on how to use vulkaninfo
can be found here.
Every repository contains a scripts/known_good.json
file which contains information about the known good commits for each dependent repository. Some repositories require an additional known-good file to be updated for Android builds and are specified below. Known-good updates require updating only the “commit” values of the relevant JSON objects. Using an existing tag for this value is preferred over using a full commit id. If a tag does not exist, typically the most recent commit on master
is chosen for updating the known good. Note: Do not change commit values for repositories not listed below unless an update is absolutely required.
Vulkan-Loader: Update requires specifying a new Vulkan-Headers
commit in scripts/known_good.json
Vulkan-ValidationLayers: Update requires specifying a new Vulkan-Headers
commit in scripts/known_good.json
. Additionally, new Vulkan-Headers
and Vulkan-Tools
commits must be specified in the build-android/known_good.json
file.
Vulkan-Tools: Update requires specifying new Vulkan-Headers
and Vulkan-Loader
commits in scripts/known_good.json
. Additionally, a new Vulkan-Headers
commit must be specified in the vulkan-headers_revision_android
file.
Commit all changes (e.g., newly generated scripts, known-good files, etc.) in a single commit on a branch and push it up to the online repository. In Vulkan-ValidationLayers, VUID inconsistency resolutions can be included in a single commit with the known-good update or on the same branch in a separate commit.
Verify the branch with the proposed known-good commit is rebased on the tip of master
and create a pull request in the GitHub repository. The repository owner will assign someone with push rights and specify reviewers for the PR. Prior to approval, the proposed changes will be run through internal LunarG CI testing.
master
Once the known-good update PR is approved, the assignee will rebase the approved commits onto the master
branch.
Once approved and rebased onto master
, the known-good update commit must be marked with a version tag. For more information on the version tag format see the “Version Tagging Scheme” section of each repository's BUILD.md
file
Updating the Known-good files in LunarG repositories follows the same steps as updating the known-good files in the Khronos repositories.
BUILD.md
file.Vulkan-Headers
, Vulkan-Loader
, Vulkan-Tools
, and Vulkan-ValidationLayers
commits in scripts/known_good.json
. Additionally, the new Vulkan-Headers
commit must be specified in the build-android/vulkan-headers_revision_android
file and the new Vulkan-Tools
commit must be specified in the build-android/vulkan-tools_revision_android
file.Vulkan-Headers
and Vulkan-Loader
commits in scripts/known_good.json
.