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:

There is no Intel macOS build; build from source on those machines.

Development Builds

Every commit to master also publishes a rolling Dev prerelease with the same asset names. Its version reads dev-YYYYMMDD-<commit>. To always get the newest build, download from the fixed dev tag:

curl -LO https://github.com/BWSL-Lang/BWSL/releases/download/dev/bwslc-linux-x64

Dev builds track master and are not stable releases.

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 build

This produces the native compiler in build/:

build/
└── bwslc

make build builds for the host by default. Pass TARGET_OS (linux, macos, windows), TARGET_ARCH (x86_64, arm64) and CONFIG (release, debug) to change that. Cross builds need the matching toolchain on PATH (for example mingw-w64 for Windows) and are written as build/bwslc-<os>-<arch>:

make build CONFIG=debug
make build TARGET_OS=windows TARGET_ARCH=x86_64

On Windows without GNU Make, use the build.bat helper from a Visual Studio Developer Command Prompt:

build.bat bwslc
build.bat bwslc-debug

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);
if (!output.success) {
  console.error(output.errors);
}

The second argument is reserved and ignored; pass an empty string. The flags string accepts -source-file <path>, -modules <path> (repeatable), -internals, -spv, -variant name=value (repeatable) and -dump-variant-space.

A successful result has success: true and includes:

• shaders for convenient stage access;
• files entries with compiler-provided artifact names, source text, WebGL sidecar JSON, and optional SPIR-V words when -spv is passed;
• diagnostics, a list of non-blocking notes such as a shadowed local name. Compilation still succeeded when it is non-empty.

A failed compile returns success: false with an errors array.

The WASM build also exports getVersion, which returns a string such as BWSL Compiler 0.11.0 (WASM), and getSymbols for editor tooling and autocomplete. The WASM build does not include the experimental WGSL backend.

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 with em++ on PATH (current Emscripten releases are supported).
• 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