wesl

README

wesl-go

A Go implementation of the WESL compiler — a superset of WGSL that adds a module system with cross-file imports and compile-time @if conditionals. It takes one or more WESL source files and produces a single, flat WGSL output suitable for use with the WebGPU API.

Usage

import "github.com/bluescreen10/wesl-go"

// Create a compiler instance.
c := wesl.New()

// Register source files. Paths are stored relative to the FS root so that
// package:: imports resolve correctly.
c.ParseFS(os.DirFS("./shaders"), "**/*.wesl")

// Compile an entry-point file, optionally passing compile-time feature flags.
wgsl, err := c.Compile("main.wesl", map[string]bool{"MY_FEATURE": true})
if err != nil {
    log.Fatal(err)
}
fmt.Println(wgsl)

Credits

Test cases are adapted from the WESL Test Suite maintained by the WebGPU Shading Language tooling working group.

Documentation

Overview

Package wesl implements a compiler for WESL (WebGPU Shading Language Extended), a superset of WGSL that adds a module system with cross-file imports and compile-time @if conditionals.

The typical workflow is:

1. Create a Compiler with New.
2. Register source files using Compiler.Parse, Compiler.ParseFile, Compiler.ParseFS, or Compiler.ParseGlob.
3. Call Compiler.Compile with the entry-point filename and any active feature flags to obtain a resolved, flat WGSL string.

Files are stored under a sanitized key: the file extension is stripped and any leading "./" is removed (e.g. "./shaders/main.wesl" → "shaders/main"). If two registrations produce the same key the last one wins.

Index

• type Compiler
  • func New() *Compiler
  • func (c *Compiler) Compile(filename string, defines map[string]bool) (string, error)
  • func (c *Compiler) Parse(name, src string) error
  • func (c *Compiler) ParseFS(fsys fs.FS, patterns ...string) error
  • func (c *Compiler) ParseFile(path string) error
  • func (c *Compiler) ParseGlob(root, pattern string) error

Types

type Compiler

type Compiler struct {
	// contains filtered or unexported fields
}

Compiler parses and compiles WESL source files into WGSL. It is safe for concurrent use; multiple goroutines may call Parse* methods simultaneously.

func New

func New() *Compiler

New returns a new, empty Compiler ready to accept source files.

func (*Compiler) Compile

func (c *Compiler) Compile(filename string, defines map[string]bool) (string, error)

Compile resolves all imports reachable from the named entry-point file and returns the merged WGSL source. filename is sanitized the same way as in Compiler.Parse. defines is the set of active compile-time feature flags used to evaluate @if conditionals; a nil map means no flags are set. It returns an error if the entry-point has not been registered or if resolution fails.

func (*Compiler) Parse

func (c *Compiler) Parse(name, src string) error

Parse parses src as WESL source and registers it under name. name is sanitized (extension stripped, leading "./" removed) before storage. If a file with the same sanitized name was registered before, it is replaced.

func (*Compiler) ParseFS

func (c *Compiler) ParseFS(fsys fs.FS, patterns ...string) error

ParseFS walks fsys recursively and registers every file whose path matches at least one of the given patterns. Patterns follow the syntax of path.Match. If no patterns are supplied every file in the FS is registered. Files are keyed by their path relative to the root of fsys.

func (*Compiler) ParseFile

func (c *Compiler) ParseFile(path string) error

ParseFile reads the file at path and registers it under its base name (directory components are stripped). It is intended for single-file use where cross-module imports are not required. For projects with a module hierarchy use Compiler.ParseFS instead.

func (*Compiler) ParseGlob

func (c *Compiler) ParseGlob(root, pattern string) error

ParseGlob reads all files under root that match pattern and registers them under paths relative to root. It is equivalent to ParseFS(os.DirFS(root), pattern). pattern follows the syntax of path.Match.