Skip to content

index.md

Latest commit

 

History

History
349 lines (239 loc) · 30.9 KB

index.md

File metadata and controls

349 lines (239 loc) · 30.9 KB

Definitions for the Vulkan SDK Bazel rules.

glsl_shader

load("@rules_vulkan//vulkan:defs.bzl", "glsl_shader")

glsl_shader(name, src, hdrs, defines, includes, opts, stage, std, target_env, target_spv)

Rule to compile GLSL shader.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
src Input GLSL shader source to compile Label required
hdrs List of header file dependencies for shader compilation.

Each unique directory containing a header file automatically generates a -I flag, so the compiler can find headers included by filename (e.g. #include "common.h"). These files are also added as action inputs so that Bazel tracks them as dependencies and triggers rebuilds when they change.		 List of labels optional []
defines List of macro defines List of strings optional []
includes List of include search directories, resolved relative to the package.

Each entry produces two -I flags:

- Source tree path (e.g. foo/bar/common) — for headers checked into the repository, when the include path you need differs from the directory that hdrs would auto-derive. For example, with a header at pkg/common/nested/helper.h and #include "nested/helper.h", hdrs auto-derives -I pkg/common/nested but you actually need -I pkg/common. Adding includes = ["common"] provides that. - Bin directory path (e.g. bazel-out/.../bin/foo/bar/common) — same as above, but for headers generated by other rules (e.g. genrule), which are placed under the output directory rather than the source tree.

Paths are constructed by joining the package path with the entry value (e.g. an entry "common" in package foo/bar resolves to foo/bar/common).

Use this when the auto-derived paths from hdrs are not sufficient — for example, when the #include directive uses a path prefix that differs from the header file's immediate directory (e.g. #include "subdir/header.h" where the header is at pkg/subdir/header.h and -I pkg is needed).		 List of strings optional []
opts Additional arguments to pass to the compiler.

Flags from //vulkan/settings:glslc_opts are appended after these, so the global build setting takes precedence on conflicting flags.		 List of strings optional []
stage Shader stage (vertex, vert, fragment, frag, etc) String required
std Version and profile for GLSL input files.

Possible values are concatenations of version and profile, e.g. 310es, 450core, etc.		 String optional ""
target_env Set the target client environment, and the semantics of warnings and errors.

An optional suffix can specify the client version.		 String optional ""
target_spv Set the SPIR-V version to be used for the generated SPIR-V module.

The default is the highest version of SPIR-V required to be supported for the target environment. For example, default for vulkan1.0 is spv1.0.		 String optional ""

hlsl_shader

load("@rules_vulkan//vulkan:defs.bzl", "hlsl_shader")

hlsl_shader(name, src, hdrs, asm, def_root_sig, defines, entry, hash, includes, opts, reflect,
            target)

Rule to compile HLSL shaders using DirectXShaderCompiler.

The target outputs <name>.cso by default, or <name>.spv when -spirv is passed via opts or the global //vulkan/settings:dxc_opts build setting. Pass other DXC flags the same way — e.g. -HV 2021 for HLSL version, -enable-16bit-types, etc.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
src Input HLSL shader source file Label required
hdrs List of header file dependencies for shader compilation.

Each unique directory containing a header file automatically generates a -I flag, so the compiler can find headers included by filename (e.g. #include "common.h"). These files are also added as action inputs so that Bazel tracks them as dependencies and triggers rebuilds when they change.		 List of labels optional []
asm Output assembly code listing file to the specified path (-Fc ) String optional ""
def_root_sig Read root signature from a #define (-rootsig-define ) String optional ""
defines List of macro defines List of strings optional []
entry Entry point name String optional "main"
hash Output shader hash to the specified file (-Fsh ) String optional ""
includes List of include search directories, resolved relative to the package.

Each entry produces two -I flags:

- Source tree path (e.g. foo/bar/common) — for headers checked into the repository, when the include path you need differs from the directory that hdrs would auto-derive. For example, with a header at pkg/common/nested/helper.h and #include "nested/helper.h", hdrs auto-derives -I pkg/common/nested but you actually need -I pkg/common. Adding includes = ["common"] provides that. - Bin directory path (e.g. bazel-out/.../bin/foo/bar/common) — same as above, but for headers generated by other rules (e.g. genrule), which are placed under the output directory rather than the source tree.

Paths are constructed by joining the package path with the entry value (e.g. an entry "common" in package foo/bar resolves to foo/bar/common).

Use this when the auto-derived paths from hdrs are not sufficient — for example, when the #include directive uses a path prefix that differs from the header file's immediate directory (e.g. #include "subdir/header.h" where the header is at pkg/subdir/header.h and -I pkg is needed).		 List of strings optional []
opts Additional arguments to pass to the DXC compiler.

Pass -spirv here (or globally via //vulkan/settings:dxc_opts) to emit SPIR-V; the rule detects the flag and selects the .spv output extension accordingly. Otherwise the rule emits .cso (DXIL).

Flags from //vulkan/settings:dxc_opts are appended after these, so the global build setting takes precedence on conflicting flags.		 List of strings optional []
reflect Output reflection to the specified file (-Fre ) String optional ""
target Target profile (e.g., cs_6_0, ps_6_0, etc.) String required

shader_group

load("@rules_vulkan//vulkan:defs.bzl", "shader_group")

shader_group(name, deps, pkg_prefix)

shader_group is a rule to group multiple shaders together.

Similar to filegroup, but forwards providers to enable building shader libraries and databases. The motivation for this rule is described in this issue.

The rule expects dependencies from shader compiler targets such as hlsl_shader, glsl_shader, slang_shader, and spirv_cross. Shader groups can also depend on other shader groups, creating hierarchical structures. Each shader_group accumulates ShaderInfo structures from all its dependencies and returns a ShaderGroupInfo provider containing the collected shader information.

Common use cases include:

  • Grouping related shaders together (e.g. vertex + fragment shader pair).
  • Building large shader libraries or databases. See the e2e/smoke example for implementation details.

Example:

load("@rules_vulkan//vulkan:defs.bzl", "hlsl_shader", "glsl_shader", "shader_group")

hlsl_shader(
    name = "vertex_shader",
    src = "vertex.hlsl",
    entry = "VSMain",
    target = "vs_6_0",
)

glsl_shader(
    name = "fragment_shader",
    src = "fragment.glsl",
    stage = "frag",
)

shader_group(
    name = "graphics_shaders",
    deps = [
        ":vertex_shader",
        ":fragment_shader",
    ],
    pkg_prefix = "shaders/",
)

Rules_pkg Integration:

The shader_group rule integrates seamlessly with rules_pkg for creating shader archives. When pkg_prefix is specified, the rule provides PackageFilesInfo that can be consumed directly by pkg_zip and other packaging rules.

The shader group acts as a replacement for pkg_files, automatically bundling all shader outputs (compiled binaries, reflection data, assembly files, etc.) into the specified archive subdirectory. This eliminates the need to manually specify each shader output file when creating packages.

load("@rules_pkg//:pkg.bzl", "pkg_zip")

pkg_zip(
    name = "shader_database",
    srcs = [":graphics_shaders"],  # All shaders will be placed in shaders/ subdirectory
    out = "shaders.zip",
)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps List of shader targets to group together.

Accepts individual shader targets (HLSL, GLSL, Slang, or spirv_cross) and other shader_group targets for hierarchical grouping.		 List of labels optional []
pkg_prefix If using with rules_pkg, sub-directory in the destination archive String optional ""

slang_shader

load("@rules_vulkan//vulkan:defs.bzl", "slang_shader")

slang_shader(name, srcs, out, hdrs, defines, depfile, entry, includes, lang, opts, profile, reflect,
             stage, target)

Rule to compile Slang shaders.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
srcs Slang input shader files List of labels required
out Specify a path where generated output should be written (-o ) String optional ""
hdrs List of header file dependencies for shader compilation.

Each unique directory containing a header file automatically generates a -I flag, so the compiler can find headers included by filename (e.g. #include "common.h"). These files are also added as action inputs so that Bazel tracks them as dependencies and triggers rebuilds when they change.		 List of labels optional []
defines Insert a preprocessor macro List of strings optional []
depfile Save the source file dependency list in a file (-depfile .dep) String optional ""
entry Entry point name String optional ""
includes List of include search directories, resolved relative to the package.

Each entry produces two -I flags:

- Source tree path (e.g. foo/bar/common) — for headers checked into the repository, when the include path you need differs from the directory that hdrs would auto-derive. For example, with a header at pkg/common/nested/helper.h and #include "nested/helper.h", hdrs auto-derives -I pkg/common/nested but you actually need -I pkg/common. Adding includes = ["common"] provides that. - Bin directory path (e.g. bazel-out/.../bin/foo/bar/common) — same as above, but for headers generated by other rules (e.g. genrule), which are placed under the output directory rather than the source tree.

Paths are constructed by joining the package path with the entry value (e.g. an entry "common" in package foo/bar resolves to foo/bar/common).

Use this when the auto-derived paths from hdrs are not sufficient — for example, when the #include directive uses a path prefix that differs from the header file's immediate directory (e.g. #include "subdir/header.h" where the header is at pkg/subdir/header.h and -I pkg is needed).		 List of strings optional []
lang Set source language for the shader (slang, hlsl, glsl, cpp, etc) String optional ""
opts Additional arguments to pass to the compiler.

Flags from //vulkan/settings:slangc_opts are appended after these, so the global build setting takes precedence on conflicting flags.		 List of strings optional []
profile Shader profile for code generation (sm_6_6, vs_6_6, glsl_460, etc) String optional ""
reflect Emit reflection data in JSON format to a file String optional ""
stage Stage of an entry point function (vertex, pixel, compute, etc) String optional ""
target Format in which code should be generated (hlsl, dxil, dxil-asm, glsl, spirv, metal, metallib, etc). This field is optional when compiling to a Slang IR module with -emit-ir. When omitted, the target field in ShaderInfo will be None. String optional ""

spirv_cross

load("@rules_vulkan//vulkan:defs.bzl", "spirv_cross")

spirv_cross(name, src, out, backend, entry, opts, stage)

spirv-cross build target.

This rule allows invoking spirv-cross binary bundled with Vulkan SDK.

Additionally, it integrates with compiler rules (hlsl_shader, glsl_shader, etc) and can inherit entry point and stages from CompilerInfo.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
src Input file Label required
out Output artifact name. If not specified, will default to .out String optional ""
backend Select backend for spirv-cross String optional ""
entry Use a specific entry point String optional ""
opts Additional arguments to pass to the spirv-cross binary List of strings optional []
stage Forces use of a certain shader stage String optional ""

vulkan_toolchain

load("@rules_vulkan//vulkan:defs.bzl", "vulkan_toolchain")

vulkan_toolchain(name, dxc, env, glslc, slangc, spirv_cross)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
dxc Path to dxc Label required
env Environment to be passed to executables. Dictionary: String -> String optional {}
glslc Path to glslc Label required
slangc Path to slangc Label required
spirv_cross Path to spirv_cross Label required

ShaderGroupInfo

load("@rules_vulkan//vulkan:defs.bzl", "ShaderGroupInfo")

ShaderGroupInfo(list)

A collection of shader infos.

FIELDS

Name Description
list List of ShaderInfo structures

ShaderInfo

load("@rules_vulkan//vulkan:defs.bzl", "ShaderInfo")

ShaderInfo(binary, assembly, reflection, hash, depfile, entry, stage, defines, target)

Shader metadata returned by the shader targets during compilation.

This is useful for building all kind of shader databases.

FIELDS

Name Description
binary Binary output file containing the compiled shader bytecode
assembly Assembly output file (if generated, HLSL-specific)
reflection Reflection output file (if generated)
hash Hash output file (if generated, HLSL-specific)
depfile Dependency output file (if generated, Slang-specific)
entry Shader entry point function name
stage Shader stage
defines List of shader defines used during compilation
target Compilation target (note: this depends on compiler used)

download_sdk

load("@rules_vulkan//vulkan:defs.bzl", "download_sdk")

download_sdk(name, build_file, macos_components, urls, version, windows_components,
             windows_skip_runtime)

Downloads and installs the Vulkan SDK for the current platform (Windows, Linux, macOS).

These rely on command line installation described in "Getting started" docs on LunarG.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this repository. Name required
build_file - Label optional "@rules_vulkan//vulkan/private:template.BUILD"
macos_components Optional Vulkan SDK components to install on macOS.

These are passed to the installer after --confirm-command install.

Known components: com.lunarg.vulkan.usr, com.lunarg.vulkan.sdl2, com.lunarg.vulkan.glm, com.lunarg.vulkan.volk, com.lunarg.vulkan.vma, com.lunarg.vulkan.ios, com.lunarg.vulkan.kosmic.		 List of strings optional []
urls Custom URLs and SHA256 checksums for the Vulkan SDK.

This allows using a custom mirror for Vulkan SDKs instead of LunarG. When not specified, the SDK is downloaded from the default LunarG mirrors using the bundled versions.json.

A separate download URL and SHA256 checksum is required for each platform. LunarG currently uses the following platform keys: - windows - Windows x86-64 - warm - Windows ARM64 - mac - macOS - linux - Linux

Each entry must provide url and sha fields. On Windows platforms, runtime_url and runtime_sha can be used to provide URLs for the Vulkan runtime package.

Example: 
custom_urls = {
    "linux": {
        "url": "https://sdk.lunarg.com/sdk/download/1.4.313.0/linux/vulkansdk-linux-x86_64-1.4.313.0.tar.xz",&#10;        "sha": "4e957b66ade85eeaee95932aa7e3b45aea64db373c58a5eaefc8228cc71445c2",
    },
    "mac": {
        "url": "https://sdk.lunarg.com/sdk/download/1.4.313.0/mac/vulkansdk-macos-1.4.313.0.zip",&#10;        "sha": "782a966ef4d5d68acaa933ff45215df2e34f286df8f6077270202f218110dc20",
    },
    "windows": {
        "url": "https://sdk.lunarg.com/sdk/download/1.4.313.0/windows/vulkansdk-windows-X64-1.4.313.0.exe",&#10;        "sha": "b643ca8ab4aea5c47b9c4e021a0b33b3a13871bf1d8131e162a9e48c257c4694",
        "runtime_url": "https://sdk.lunarg.com/sdk/download/1.4.313.0/windows/VulkanRT-X64-1.4.313.0-Components.zip",&#10;        "runtime_sha": "e8d37913185142270a2bc1b3e1f8f498a4edf47405fddda666f2f38b30ca944b",
    },
    "warm": {
        "url": "https://sdk.lunarg.com/sdk/download/1.4.313.0/warm/vulkansdk-windows-ARM64-1.4.313.0.exe",&#10;        "sha": "b19a8683df982d302fec07c110962153f02a2e5cf1e5118ff72d8532aa5fc567",
        "runtime_url": "https://sdk.lunarg.com/sdk/download/1.4.313.0/warm/VulkanRT-ARM64-1.4.313.0-Components.zip",&#10;        "runtime_sha": "6335a8d6b7ab85861025c2546f5f52384ff18a6d9346d350c2a0bf3b7524829a",
    },
}
 Dictionary: String -> String optional {}
version Vulkan SDK version to download and install.

This expects a version in the format of 1.4.313.0 or 1.4.313. When 3 components are provided, .0 will be appended automatically to make it 4 components.		 String required
windows_components Optional Vulkan SDK components to install on Windows.

These are passed to the installer between --confirm-command install and copy_only=1.

Known components: com.lunarg.vulkan.sdl2, com.lunarg.vulkan.glm, com.lunarg.vulkan.volk, com.lunarg.vulkan.vma, com.lunarg.vulkan.debug.		 List of strings optional []
windows_skip_runtime Do not download and install Vulkan runtime package (e.g. vulkan-1.dll dependency) on Windows.

When True, the downloader will not put vulkan-1.dll into the repository root directory.

This is useful if there is a system-wide Vulkan runtime already installed, otherwise this might lead to link/runtime issues when building CC targets.		 Boolean optional False

install_sdk

load("@rules_vulkan//vulkan:defs.bzl", "install_sdk")

install_sdk(name, build_file, macos_components, urls, version, windows_components,
            windows_skip_runtime)

Downloads and installs the Vulkan SDK for the current platform (Windows, Linux, macOS).

These rely on command line installation described in "Getting started" docs on LunarG.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this repository. Name required
build_file - Label optional "@rules_vulkan//vulkan/private:template.BUILD"
macos_components Optional Vulkan SDK components to install on macOS.

These are passed to the installer after --confirm-command install.

Known components: com.lunarg.vulkan.usr, com.lunarg.vulkan.sdl2, com.lunarg.vulkan.glm, com.lunarg.vulkan.volk, com.lunarg.vulkan.vma, com.lunarg.vulkan.ios, com.lunarg.vulkan.kosmic.		 List of strings optional []
urls Custom URLs and SHA256 checksums for the Vulkan SDK.

This allows using a custom mirror for Vulkan SDKs instead of LunarG. When not specified, the SDK is downloaded from the default LunarG mirrors using the bundled versions.json.

A separate download URL and SHA256 checksum is required for each platform. LunarG currently uses the following platform keys: - windows - Windows x86-64 - warm - Windows ARM64 - mac - macOS - linux - Linux

Each entry must provide url and sha fields. On Windows platforms, runtime_url and runtime_sha can be used to provide URLs for the Vulkan runtime package.

Example: 
custom_urls = {
    "linux": {
        "url": "https://sdk.lunarg.com/sdk/download/1.4.313.0/linux/vulkansdk-linux-x86_64-1.4.313.0.tar.xz",&#10;        "sha": "4e957b66ade85eeaee95932aa7e3b45aea64db373c58a5eaefc8228cc71445c2",
    },
    "mac": {
        "url": "https://sdk.lunarg.com/sdk/download/1.4.313.0/mac/vulkansdk-macos-1.4.313.0.zip",&#10;        "sha": "782a966ef4d5d68acaa933ff45215df2e34f286df8f6077270202f218110dc20",
    },
    "windows": {
        "url": "https://sdk.lunarg.com/sdk/download/1.4.313.0/windows/vulkansdk-windows-X64-1.4.313.0.exe",&#10;        "sha": "b643ca8ab4aea5c47b9c4e021a0b33b3a13871bf1d8131e162a9e48c257c4694",
        "runtime_url": "https://sdk.lunarg.com/sdk/download/1.4.313.0/windows/VulkanRT-X64-1.4.313.0-Components.zip",&#10;        "runtime_sha": "e8d37913185142270a2bc1b3e1f8f498a4edf47405fddda666f2f38b30ca944b",
    },
    "warm": {
        "url": "https://sdk.lunarg.com/sdk/download/1.4.313.0/warm/vulkansdk-windows-ARM64-1.4.313.0.exe",&#10;        "sha": "b19a8683df982d302fec07c110962153f02a2e5cf1e5118ff72d8532aa5fc567",
        "runtime_url": "https://sdk.lunarg.com/sdk/download/1.4.313.0/warm/VulkanRT-ARM64-1.4.313.0-Components.zip",&#10;        "runtime_sha": "6335a8d6b7ab85861025c2546f5f52384ff18a6d9346d350c2a0bf3b7524829a",
    },
}
 Dictionary: String -> String optional {}
version Vulkan SDK version to download and install.

This expects a version in the format of 1.4.313.0 or 1.4.313. When 3 components are provided, .0 will be appended automatically to make it 4 components.		 String required
windows_components Optional Vulkan SDK components to install on Windows.

These are passed to the installer between --confirm-command install and copy_only=1.

Known components: com.lunarg.vulkan.sdl2, com.lunarg.vulkan.glm, com.lunarg.vulkan.volk, com.lunarg.vulkan.vma, com.lunarg.vulkan.debug.		 List of strings optional []
windows_skip_runtime Do not download and install Vulkan runtime package (e.g. vulkan-1.dll dependency) on Windows.

When True, the downloader will not put vulkan-1.dll into the repository root directory.

This is useful if there is a system-wide Vulkan runtime already installed, otherwise this might lead to link/runtime issues when building CC targets.		 Boolean optional False