CLI Reference
Complete reference for the bwslc command-line compiler.
Turn the guide into code
Take the key idea from this page into the playground and validate it in a real shader instead of leaving it as theory.
Open PlaygroundThe bwslc command compiles .bwsl shader files to SPIR-V and can additionally emit Metal, HLSL, GLSL, and GLSL ES output.
Examples below use bwslc. In a source checkout, that binary is typically ./build/bwslc.
Basic Usage
bwslc <input.bwsl> [options]
Options
Core Options
| Option | Description |
|---|---|
-o <dir> | Output directory (default: current directory) |
-modules <dir> | Add a module search path (repeatable) |
-variant <k=v> | Specialize one named shader variant (repeatable) |
-dump-variant-space | Print variant reflection JSON and exit |
-pass <name> | Compile a specific pass (default: all passes) |
-stage <name> | Compile a specific stage: vertex, fragment, or compute |
Output Format Flags
SPIR-V is always generated. Use these flags to add more outputs:
| Flag | Description |
|---|---|
-metal | Generate Metal Shading Language output |
-hlsl | Generate HLSL output |
-glsl | Generate GLSL 450 output |
-gles | Generate GLSL ES 300 output |
-gles-direct | Generate GLSL ES directly from BWSL IR |
-webgl | Alias for -gles |
-bindings | Emit resolved resource binding JSON |
-all | Generate all supported outputs |
Debug Options
| Option | Description |
|---|---|
-v | Verbose output |
-timing | Print timing information |
-dump-ir | Dump BWSL IR |
-debug-names | Emit debug names in SPIR-V output |
-no-validate | Skip SPIR-V validation |
-internals | Write SPIR-V disassembly and IR dump to JSON |
-h, --help | Show help |
Examples
SPIR-V Only
bwslc shader.bwsl
SPIR-V + Metal
bwslc shader.bwsl -metal
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
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
Emit Internal Debug Data
bwslc shader.bwsl -internals -o build/shaders
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.
See Also
- Shader Variants - Declaring and specializing shader variant space
- Installation - Building or locating the compiler
- Quick Start - Write your first shader
- Integration - Engine and build-system integration