Installation

The compiler repo supports these installation paths:

• prebuilt command-line compilers from GitHub Releases
• a native CLI compiler for local builds and asset pipelines
• a WebAssembly build for browser tools, editors, and playgrounds
• bundled editor support for VS Code

Download a Release

Prebuilt CLI binaries are published on the BWSL GitHub Releases page when a version is cut.

Choose the asset for your platform:

After downloading, put the binary somewhere on your PATH or call it directly from your build scripts. On macOS and Linux, make the binary executable if your browser or archive tool strips that bit:

chmod +x bwslc-*

Build the CLI Compiler

From the BWSL source repo:

git clone --recurse-submodules https://github.com/BWSL-Lang/BWSL.git
cd BWSL
make bwslc

This produces the native compiler in build/:

build/
└── bwslc

On Windows, the repo also includes build.bat and make.bat helpers:

build.bat bwslc

Verify Installation

The current compiler exposes help and version information through -h:

./build/bwslc -h

If bwslc is already on your PATH, the same check works as:

bwslc -h

The help output should show the compiler version and flags such as -o, -manifest, -watch, -metal, -hlsl, -glsl, -gles, -variant, -dump-variant-space, -errors-json, and -validation.

VS Code Extension

The source repo includes a declarative VS Code language-support extension in tools/vscode-bwsl. It provides .bwsl syntax highlighting, language configuration for comments/brackets/folding, and snippets for pipelines, modules, passes, shader stages, declarations, variants, and loops.

The repo may already contain a packaged VSIX at tools/vscode-bwsl/bwsl-language-support-*.vsix. Install it directly from a source checkout:

cd tools/vscode-bwsl
code --install-extension bwsl-language-support-*.vsix

If you changed the extension locally or the VSIX is missing, package it first:

npx --yes @vscode/vsce package --no-dependencies
code --install-extension bwsl-language-support-*.vsix

For extension development, open tools/vscode-bwsl in VS Code and press F5 to launch an Extension Development Host.

WebAssembly Build

For browser-based compilation, build the WASM target:

make wasm

Artifacts are written to build/wasm/:

build/wasm/
├── bwsl.js
└── bwsl.wasm

Usage in JavaScript

import initBWSL from "./build/wasm/bwsl.js";

const bwsl = await initBWSL();

const result = bwsl.ccall(
  "compile",
  "string",
  ["string", "string", "string"],
  [
    shaderSource,
    "",
    "-source-file shader.bwsl -internals -modules ./modules",
  ]
);

const output = JSON.parse(result);

The returned JSON includes shaders for convenient stage access and files entries with compiler-provided artifact names, source text, WebGL sidecar JSON, and optional SPIR-V words when -spv is passed. The WASM build also exposes getSymbols for editor tooling and autocomplete.

Specification and Grammar

The BWSL source repo includes the canonical language specification draft in docs/spec/ and a BNF grammar in docs/spec/bwsl.bnf. Use those files when implementing editor tooling, parser checks, or compiler changes that need exact source syntax. See Language Specification for how the public docs relate to the source-tree spec.

Notes

• Releases are the easiest path for users who only need the compiler binary.
• Source builds require a C++20-capable toolchain.
• WASM builds require Emscripten (emcc) in PATH.
• Resources are declared in source; host-only preview or render-graph metadata should be handled outside the compiler call.

Next Steps

• Quick Start - Write your first shader
• CLI Reference - Full command-line flag reference
• Integration - Build-system and engine integration