kosikowski/metal-shader-list-plugin

Generate Swift enums from your Metal shader functions — automatically!

What does this plugin do?

ShaderListPlugin is a Swift Package Plugin that scans your target's .metal shader source files, parses all top-level Metal shader functions, and generates type-safe Swift enums for you to access those shaders in your code. No more hardcoding shader function names as strings, or copy–pasting boilerplate! All shader functions are grouped by type (vertex, fragment, kernel, compute) or by custom group comments in your Metal source. Each enum also gets a convenience extension for MTLLibrary.

How to Use

With Swift Package Manager (SPM):

Add ShaderListPlugin to your `Package.swift`:

.package(url: "https://github.com/Kosikowski/metal-shader-list-plugin.git", from: "1.0.0")

Add the plugin to your project and target:

.target(
    name: "YourTarget",
    dependencies: [ /* ... */ ],
    plugins: [
        .plugin(name: "ShaderListPlugin")
    ]
)

Place your .metal files in your target's sources.

Build your package. The plugin generates enums and extensions in Generated/YourTargetShaderEnums.generated.swift under the plugin work directory. Use them directly in your code:

let shader = YourTargetMTLShaders.MTLFragmentShader.yourShaderFunctionNameHereAsEnumForTypeSafety
let function = library.makeFunction(shader)

or simply:

let function = library.makeFunction(.yourShaderFunctionNameHereAsEnumForTypeSafety)

With Xcode:

The plugin also works in Xcode via the Xcode Project Plugin interface. After adding the package and plugin, it runs automatically whenever you build your project.

Customizing Groups

You can assign custom groups to your shader functions by preceding them with special comments in your Metal source:

// MTLShaderGroup: SpecialEffects
fragment float4 sparkle_fragment() { ... }

Shader Group Name Validation

Shader group names must contain only A-Z and a-z characters. Invalid characters (including hyphens, underscores, numbers, spaces, and special symbols) will cause the build to fail with a clear error message.

Valid examples:

// MTLShaderGroup: Lighting
// MTLShaderGroup: Rendering
// MTLShaderGroup: PostProcessing

Invalid examples (will cause build errors):

// MTLShaderGroup: Lighting-3D     // ❌ Contains hyphen
// MTLShaderGroup: Post_Processing  // ❌ Contains underscore
// MTLShaderGroup: 123Invalid       // ❌ Starts with number

Open Source Contributions

Everyone is welcome to contribute to this project! Whether you find bugs, want to add features, or improve documentation, PRs and issues are encouraged. Please fork, propose changes, or start discussions.

Package Metadata

Repository: kosikowski/metal-shader-list-plugin

Default branch: main

README: README.md