@gasm-compiler/cli

Command-line compiler for WebAssembly → WGSL

Compile WebAssembly (.wasm) or AssemblyScript (.as/.ts) files to WGSL compute shaders from the command line. Built on top of @gasm-compiler/core.

Installation

npm install -g @gasm-compiler/cli

Or use without installing:

npx @gasm-compiler/cli compile shader.wasm -o shader.wgsl

Quick Start

# Compile a .wasm file to WGSL
gasm-compiler compile shader.wasm --output shader.wgsl

# Compile AssemblyScript to WGSL (compiles to Wasm first, then to WGSL)
gasm-compiler compile kernel.as --output kernel.wgsl

# Print WGSL to stdout
gasm-compiler compile shader.wasm

# Show verbose compilation steps
gasm-compiler compile shader.wasm --verbose

# View help
gasm-compiler --help

Commands

compile <input>

Compiles a WebAssembly binary or AssemblyScript source to WGSL.

| Option | Description | |--------|-------------| | --output <file>, -o | Write WGSL output to a file (default: stdout) | | --verbose | Show detailed compilation steps | | --keep-wasm | Keep intermediate .wasm file when compiling from AssemblyScript | | --optimize | Apply optimization passes |

Examples:

# Compile pre-built Wasm
gasm-compiler compile my_shader.wasm -o my_shader.wgsl

# Compile AssemblyScript with verbose output
gasm-compiler compile gpu_kernel.as --verbose -o output.wgsl

# Pipe output into another tool
gasm-compiler compile shader.wasm | tee shader.wgsl

How It Works

AssemblyScript (.as/.ts)     WebAssembly (.wasm)
        ↓                           │
   ASC Compiler                     │
        ↓                           │
WebAssembly Binary ←────────────────┘
        ↓
   Gasm Compiler (parse, validate, transform)
        ↓
   WGSL Compute Shader (.wgsl)

1. If the input is AssemblyScript, it is first compiled to WebAssembly using the AssemblyScript compiler
2. The WebAssembly binary is validated against the Gasm specification (GPU-safe subset)
3. The compiler transforms the Wasm into WGSL, restructuring control flow and lowering memory operations
4. The output is a valid WGSL compute shader ready for use with WebGPU

Writing Gasm-Compatible WebAssembly

Your WebAssembly module must conform to the Gasm subset:

• Export a single linear memory as "memory"
• Only import globals from the "gasm" module (GPU built-ins like global_invocation_id_x)
• No function or memory imports
• Export your entry point function

Example (WAT):

(module
  (import "gasm" "global_invocation_id_x" (global $gid_x i32))
  (memory (export "memory") 1)
  (func (export "main")
    ;; Your GPU kernel logic here
    ;; Use $gid_x for per-thread indexing
  ))

For the full list of available Gasm built-in globals and supported instructions, see the @gasm-compiler/core documentation.

Related Packages

• @gasm-compiler/core — Core compiler library (programmatic API)
• @gasm-compiler/math-reference — CPU-side reference implementations of Gasm math functions

License

See LICENSE for details.