HLSLBuildPlugin

A Swift Package Manager build tool plugin that compiles .hlsl sources into platform-appropriate binaries:

• Apple platforms: uses dxc -metal to emit .metallib.
• Linux/Windows: uses dxc -spirv -fspv-target-env=vulkan1.2 to emit .spv.

The plugin is intended to be attached to your shader or resource target so generated outputs are available alongside your package/app resources.

Requirements

• dxc available at /opt/dxc/bin/dxc, in PATH, or via DXC_PATH.
• On Apple: dxc built with Metal support and metal-shaderconverter installed.

Adding the plugin

// Package.swift (consumer)
.package(url: "https://github.com/openorbit/spm-hlsl-plugin.git", branch: "main"),

.target(
    name: "GameShaders",
    resources: [.process("Shaders")], // where your .hlsl files live
    plugins: [.plugin(name: "HLSLBuildPlugin", package: "spm-hlsl-plugin")]
)

Place your .hlsl files anywhere inside the target (e.g. Shaders/triangle.hlsl). The plugin emits generated binaries into its work directory and SwiftPM treats them as generated resources, so you can load them from Bundle.module using the output names.

Configuring per-shader options

Defaults:

• Entry point: main or HLSL_ENTRY_POINT.
• Target profile: HLSL_TARGET_PROFILE or a heuristic based on the filename (*_vs* -> vs_6_0, *_ps* -> ps_6_0, *_cs* -> cs_6_0).
• Extra args: split from HLSL_EXTRA_ARGS.
• Output extension: .metallib on Apple, .spv elsewhere.

Override per file by adding a sidecar JSON file next to the shader (e.g. Shaders/triangle.hlsl.json):

{
  "entryPoint": "vsMain",
  "targetProfile": "vs_6_6",
  "outputName": "triangle.metallib",
  "outputExtension": "metallib",
  "extraArgs": ["-O3", "-DDEBUG=0"]
}

Notes

• If dxc cannot be found the build fails with a clear error; set DXC_PATH to point at your compiler if needed.
• On Apple, -metal is passed so dxc will invoke metal-shaderconverter automatically when available.
• On non-Apple platforms, SPIR-V output targets Vulkan 1.2 by default. Adjust with HLSL_EXTRA_ARGS or sidecar extraArgs if you need a different profile or options.