v_vulkan_bindings

Project portfolio

Generates the vulkan bindings for V from the current KhronosGroup API description.

Quick start

Requirements: Git, Python 3 with the venv module, and V if the generated files should be formatted. On Ubuntu or Debian, install the native prerequisites with:

sudo apt update
sudo apt install -y git python3 python3-venv

The setup script creates an isolated Python environment, checks out the Vulkan-Docs tag recorded by this generator checkout in VERSION, installs the Python dependency, and regenerates both binding files:

git clone https://github.com/antono2/v_vulkan_bindings.git
cd v_vulkan_bindings
./scripts/generate.sh

On Windows, run the equivalent PowerShell script:

git clone https://github.com/antono2/v_vulkan_bindings.git
Set-Location v_vulkan_bindings
.\scripts\generate.ps1

Pass a Vulkan-Docs tag to generate a different registry release:

./scripts/generate.sh v1.4.362

.\scripts\generate.ps1 v1.4.362

The script refuses to switch an existing vulkandocs checkout if it contains local changes. Generated files are written to src/vulkan.v and src/vulkan_video.v; review their diff before committing.

Platform extensions are selected with V compile flags derived from the registry's <platform> names. For example, -d vulkan_xlib includes the Xlib declarations and supplies VK_USE_PLATFORM_XLIB_KHR to the C compiler. XCB and Wayland have separate flags (vulkan_xcb and vulkan_wayland). The same rule applies to Android, Win32, Metal, and the other registry platforms. Extension name and spec-version constants remain available without the flag; platform types and commands require it and the platform's native development headers.

Manual generation

The generator imports helper modules from a vulkandocs checkout at the repository root:

git clone --depth 1 --branch "$(cat VERSION)" \
  https://github.com/KhronosGroup/Vulkan-Docs.git vulkandocs
python3 -m venv .venv
.venv/bin/python -m pip install -r .github/generator-requirements.txt
.venv/bin/python src/main.py -registry vulkandocs/xml/vk.xml vulkan.v
.venv/bin/python src/main.py -registry vulkandocs/xml/video.xml vulkan_video.v
v fmt -w src/vulkan.v src/vulkan_video.v

Example Setup using preinstalled vulkan registry

Working Directory: ~/workspace/v_vulkan_bindings

Script Name:        src/main.py
Params Vulkan:      -registry ../../../../usr/share/vulkan/registry/vk.xml vulkan.v
Params VulkanVideo: -registry ../../../../usr/share/vulkan/registry/video.xml vulkan_video.v

Publishing

update_bindings_and_push_to_vulkan.yml checks the newest numeric Vulkan-Docs tag each day, regenerates the bindings against that tag, and opens a generated pull request in antono2/vulkan. Merging that pull request creates the matching immutable version tag after the target repository's required checks pass. The proposal also copies the matching Vulkan and video C headers from the same Vulkan-Headers tag. The compile smoke test uses those bundled headers and the target module's pinned Volk sources. Registry downgrades are rejected. The generator checkout's own VERSION remains a reproducible local generation default; the scheduled workflow selects the newest tag independently.

When the registry tag is already published but the generator itself needs a compatibility correction, run the workflow manually with force_regenerate. It opens a compat/generated-<tag> pull request without changing VERSION or using the release-only generated/* branch namespace.

publish-compatibility-tags.yml is a manual maintenance workflow for old registry releases whose original generated layout is not accepted by current V. It publishes new +vcompat.N tags and never rewrites the historical tags.