CLI Reference

The bwslc command compiles .bwsl shader files to SPIR-V internally and can emit SPIR-V, Metal, HLSL, GLSL, and GLSL ES artifacts.

Examples below use bwslc. In a source checkout, that binary is typically ./build/bwslc.

Basic Usage

bwslc <input.bwsl | directory> [more inputs...] [options]

Passing more than one input, a directory, or -manifest activates batch mode. Batch mode compiles every discovered unit and reports all failures together instead of stopping at the first failed file.

Options

Core Options

Output Format Flags

SPIR-V is generated internally for validation and cross-compilation. If no output format is requested, the CLI writes SPIR-V by default; when other formats are requested, use -spv to also write .spv sidecars.

Debug Options

Examples

SPIR-V Only

bwslc shader.bwsl

Use -spv when requesting other artifacts but still wanting SPIR-V files written:

bwslc shader.bwsl -spv -metal

SPIR-V + Metal

bwslc shader.bwsl -metal -spv

Multiple Output Formats

bwslc shader.bwsl -metal -hlsl -gles

All Outputs

bwslc shader.bwsl -all

Source-Declared Resources

bwslc shader.bwsl -all -bindings

Resources are declared in the shader with resources {} and selected per pass with use resources { ... }. The -bindings flag emits the resolved host binding metadata for those source-declared resources.

Specialize Shader Variants

bwslc shader.bwsl -variant skinning=true -variant lighting=Clustered -metal

Boolean variants accept true, false, 1, or 0. Enum variants accept either a bare member name or a qualified name such as LightingMode::Clustered.

Dump Variant Reflection

bwslc shader.bwsl -dump-variant-space

This prints JSON describing declared variants, implicit variants, legality rules, and the current selected values. See Shader Variants for the language-side model.

Custom Output Directory

bwslc shader.bwsl -o dist/shaders -all

Batch Compile Files

bwslc lighting.bwsl postfx.bwsl ui.bwsl -check

Every file is checked and the process exits nonzero if any file fails. Text output includes a batch summary; JSON mode emits one aggregate document with per-file diagnostics.

Batch Compile a Directory

bwslc shaders/ -o dist/shaders -metal -hlsl

Directory inputs are scanned recursively for .bwsl files. Outputs mirror the source subdirectories under -o, so files with the same stem in different folders do not overwrite each other.

Use a Manifest

bwslc -manifest shaders.txt -check -errors-json

Manifest files contain one file or directory per line:

# paths are relative to this manifest file
pipelines/
effects/bloom.bwsl
ui/hud.bwsl

Blank lines and # comments are ignored. Directory entries are scanned the same way as positional directory inputs, and overlapping entries are deduplicated.

Watch for Changes

bwslc shaders/ -modules modules/ -o dist/shaders -gles -watch

Watch mode performs an initial build, then recompiles changed units when a source file or imported module file changes. Directory and manifest inputs are rescanned on each polling tick, so added and removed .bwsl files are picked up without restarting the compiler.

Use -errors-json when an editor or engine hot-reload process wants one parseable JSON build report per rebuild:

bwslc shaders/ -modules modules/ -o dist/shaders -gles -watch -errors-json

Tune polling when needed:

bwslc shaders/ -watch -watch-interval 100

Compile a Specific Pass

bwslc shader.bwsl -pass MainPass

Compile a Specific Stage

bwslc shader.bwsl -pass Simulate -stage compute

Add Module Search Paths

bwslc shader.bwsl -modules ./modules -modules ./lib/shaders

Standard-library modules are embedded in the compiler, so imports such as import Math, import Debug, or import Sampling do not require a -modules path. Module search paths are still used for project modules. A disk module cannot override an embedded standard-library module name.

Emit JSON Diagnostics

bwslc shader.bwsl -errors-json

This prints schema-versioned diagnostic JSON with severities, phases, stable BWSL... error codes, source locations, token details, and source context when available. Use it for editor integrations, CI annotations, and build tools that should not parse human-readable compiler output.

See Diagnostics for the JSON schema and complete error-code table.

For batch inputs, -errors-json emits a single aggregate document with batch: true, summary counts, and a files array of normal per-file diagnostic documents. For watch mode, each rebuild emits one aggregate JSON document with watch: true and event: "build".

Emit AST JSON

bwslc shader.bwsl -ast-json

This parses the source and prints AST JSON for IDEs, code browsers, documentation tooling, and other structural integrations. The top-level object uses schema: "bwsl.ast.v2" and includes sourceFile, root, modules, pipelines, and nodeCounts.

AST nodes include id, type, index, line, column, and end positions when available. Variable declarations also expose typeLine, typeColumn, nameLine, and nameColumn. Declarations preceded by /// line comments or /** ... */ block comments can include a docs object with raw text, summary, @param entries, return text, and remaining tags.

Control SPIR-V Validation

bwslc shader.bwsl -validation strict

Validation modes:

Emit Internal Debug Data

bwslc shader.bwsl -internals -o build/shaders

Input Compatibility

Some modes intentionally stay single-input:

Output Notes

Each compiled pass emits one output per selected stage and target format into the chosen output directory. Graphics passes produce vertex and fragment outputs; compute passes produce compute outputs.

For single-pass shaders, stage outputs use the input basename directly, such as shader.vert, shader.frag, and matching sidecars like shader.vert.json or shader.vert.spv. For multi-pass shaders, the pass name is appended to the stem, such as shader_MainPass.vert and shader_PostFX.frag.

In batch mode, multiple explicit files write into the selected output directory. Directory inputs preserve relative subdirectories under -o.

See Also

• Shader Variants - Declaring and specializing shader variant space
• Diagnostics - Diagnostic JSON schema and error codes
• Installation - Building or locating the compiler
• Quick Start - Write your first shader
• Integration - Engine and build-system integration