Integration

BWSL can be integrated in two common ways:

• run bwslc in your asset pipeline and ship generated shader output
• embed the compiler service or WASM build in editor tooling

CLI-Driven Integration

The CLI is the simplest integration path for builds and asset baking.

./build/bwslc shader.bwsl -modules ./modules -all

Typical inputs:

• a .bwsl source file
• a directory containing .bwsl source files
• a manifest file listing source files or directories
• zero or more module search paths

Typical outputs:

• optional SPIR-V sidecars for each compiled stage via -spv
• optional Metal, HLSL, GLSL, or GLSL ES output
• optional IR and SPIR-V disassembly via -internals
• optional machine-readable diagnostics via -errors-json
• optional parsed AST JSON via -ast-json

Use this path when your engine already has an asset build step and you want shader compilation to behave like any other imported asset.

Batch Asset Builds

Use batch mode when a build step needs to compile or check an entire shader tree:

./build/bwslc shaders/pipelines/ \
  -modules shaders/modules \
  -o build/shaders \
  -all \
  -errors-json

Batch mode is activated by multiple positional inputs, a directory input, or -manifest. It compiles every unit and returns all failures in one run, which makes it a better fit for CI and editor-wide validation than fail-fast single-file loops.

Useful behavior for build systems:

• directory inputs are scanned recursively for .bwsl files
• outputs mirror source subdirectories under -o
• overlapping inputs are deduplicated
• imported module files are resolved and read once per batch when possible
• -errors-json emits one aggregate report with a files array of per-file diagnostics

For explicit shader lists, keep a manifest next to the project or asset target:

# shaders.manifest
pipelines/
debug/overlay.bwsl
post/bloom.bwsl

./build/bwslc -manifest shaders.manifest -modules shaders/modules -check -errors-json

Manifest entries are resolved relative to the manifest file. Blank lines and # comments are ignored.

Hot Reload Watch Mode

Use -watch when an editor or engine wants a long-lived compiler process for live shader rebuilds:

./build/bwslc shaders/pipelines/ \
  -modules shaders/modules \
  -o build/shaders \
  -gles \
  -watch \
  -errors-json

Watch mode performs an initial build, then recompiles units whose source or imported module files changed. Directory and manifest inputs are rescanned on each tick, so added and removed shader files become part of the watched set without restarting the process.

With -errors-json, stdout is a stream of complete build-report JSON objects. Each report includes watch: true, event: "build", buildId, trigger paths, removed files, summary counts, elapsed time, and nested per-file diagnostics. Use this shape for engine hot reload, editor problem panes, and incremental asset workers.

The default poll interval is 250 ms:

./build/bwslc shaders/pipelines/ -watch -watch-interval 100

Engine Runtime Integration

The repository also contains compiler-service code intended for host-engine integration:

• bwsl_compiler_service_core.h for platform-agnostic compilation and variant caching
• bwsl_compiler_service.h for Metal-focused runtime integration
• middleware/ for backend-specific glue

This path is useful when the engine needs to compile or specialize shaders on demand.

Recommended Project Layout

shaders/
  pipelines/
    MaterialPreview.bwsl
  modules/
    Lighting.bwsl
    Noise.bwsl
preview/
  MaterialPreview.preview.json

Then compile with explicit module roots:

./build/bwslc shaders/pipelines/MaterialPreview.bwsl \
  -modules shaders/modules \
  -variant lighting=Forward \
  -all

Resources and Validation

Shader-visible resources are declared directly in the BWSL pipeline with a resources {} block, selected per pass with use resources { ... }, and accessed through resources.*.

• the compiler assigns bindings automatically
• the reflection output describes resolved bindings and stage metadata
• invalid stage/resource access is rejected during compilation

Host-only metadata such as preview targets, pass wiring, or app-specific binding data should live outside the language surface. In this docs app that metadata lives in preview JSON.

That means mismatches are usually found during compilation instead of surfacing later as backend-specific shader errors.

For build systems and CI, use -errors-json to receive schema-versioned diagnostics with BWSL... error codes, source locations, token details, and pass/stage context. See Diagnostics for the schema.

Modules

Imports are resolved from:

• embedded standard-library modules
• module search paths passed with -modules
• the input shader's directory

Example:

pipeline Demo {
    import Lighting, Noise
}

Imports can be aliased with as, and an already imported module can be opted into unqualified lookup with using:

pipeline Demo {
    import Lighting as L
    using L
}

Use using Alias = Type for scoped type aliases, including module-qualified types:

import PBR as BRDF
using Material = BRDF::PBRMaterial

Standard-library modules such as Math, Random, Noise, Color, Compression, Debug, Packing, PBR, Globals, PostFX, Sampling, SDF, and Spaces are embedded in the compiler. Importing one of those names does not require a -modules path. Files with the same module name cannot override the embedded module; rename local modules to a project-specific name instead.

Tooling and Playground

For browser tools or editors, the repo also ships a WASM build. That is the right fit for autocomplete, preview compilation, and playground-style workflows where calling the native CLI is inconvenient.

The repo also includes editor-support projects:

• tools/vscode-bwsl for VS Code syntax highlighting, language configuration, and snippets. Package it with npx --yes @vscode/vsce package --no-dependencies from that directory, then install the generated VSIX with code --install-extension.

The native and WASM compiler frontends both understand shader variants:

• use -variant name=value to specialize a concrete build
• use -dump-variant-space to inspect the legal variant space for tooling
• use compiler-service attribute masks when specializing optional vertex attributes at runtime

For IDEs, code browsers, documentation extraction, and other structural tooling, bwslc -ast-json parses the source and exits with a JSON AST instead of writing shader outputs. The top-level object includes schema: "bwsl.ast.v2", sourceFile, root, modules, pipelines, and nodeCounts. Nodes include source positions, and documented declarations can include a docs object parsed from /// or /** ... */ comments.

Next

• Installation
• CLI Reference
• Diagnostics
• Shader Variants
• Resources