Documentation

Install Awsum and use the awsum CLI.

Install

Prebuilt binaries from GitHub Releases

  1. Download into ~/.local/bin (overwrites any existing copy): 

    mkdir -p ~/.local/bin
curl -fsSL https://github.com/awsum-lang/awsum/releases/download/v0.0.3/awsum-0.0.3-macos-aarch64.tar.gz \
  | tar -xzC ~/.local/bin

  2. Verify install — ~/.local/bin must be on your PATH: 

    awsum --version

  1. Download into ~/.local/bin (overwrites any existing copy): 

    mkdir -p ~/.local/bin
curl -fsSL https://github.com/awsum-lang/awsum/releases/download/v0.0.3/awsum-0.0.3-linux-x86_64-gnu.tar.gz \
  | tar -xzC ~/.local/bin

  2. Verify install — ~/.local/bin must be on your PATH: 

    awsum --version

  1. Download into ~/.local/bin (overwrites any existing copy): 

    mkdir -p ~/.local/bin
curl -fsSL https://github.com/awsum-lang/awsum/releases/download/v0.0.3/awsum-0.0.3-linux-aarch64-gnu.tar.gz \
  | tar -xzC ~/.local/bin

  2. Verify install — ~/.local/bin must be on your PATH: 

    awsum --version

  1. Download into %LOCALAPPDATA%\Microsoft\WindowsApps — already on PATH by default since Windows 10 (overwrites any existing copy): 

    $Url  = "https://github.com/awsum-lang/awsum/releases/download/v0.0.3/awsum-0.0.3-windows-x86_64.zip"
$Dest = "$env:LOCALAPPDATA\Microsoft\WindowsApps"
Invoke-WebRequest -Uri $Url -OutFile "$env:TEMP\awsum.zip"
Expand-Archive -Path "$env:TEMP\awsum.zip" -DestinationPath $Dest -Force

  2. Verify install:

    awsum --version

For other platforms (musl Linux, x86 macOS, BSD), build from source — see awsum/README.md.

Target runtimes

Install only the runtimes for the targets you actually plan to use. 

# LLVM target — clang 15+ (opaque pointers)
brew install llvm@15

# JVM target — Java 7+
brew install openjdk

# CLR target — .NET 9+
brew install dotnet

# WASM target — wasmtime with WASI
brew install wasmtime

# JS target — Node 22+
brew install node
# LLVM target — clang 15+ (opaque pointers)
sudo apt-get install -y clang-15

# JVM target — Java 7+
sudo apt-get install -y default-jre

# CLR target — .NET 9+ (Ubuntu 24.04+; on older systems add
# Microsoft's APT repo first)
sudo apt-get install -y dotnet-sdk-9.0

# WASM target — wasmtime with WASI
curl https://wasmtime.dev/install.sh -sSf | bash

# JS target — Node 22+ via NodeSource (apt's default is older)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
# LLVM target — clang 15+ (opaque pointers)
sudo apt-get install -y clang-15

# JVM target — Java 7+
sudo apt-get install -y default-jre

# CLR target — .NET 9+ (Ubuntu 24.04+; on older systems add
# Microsoft's APT repo first)
sudo apt-get install -y dotnet-sdk-9.0

# WASM target — wasmtime with WASI
curl https://wasmtime.dev/install.sh -sSf | bash

# JS target — Node 22+ via NodeSource (apt's default is older)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
# LLVM target — clang 15.0.7 (opaque pointers; 16+ has known issues
# with our codegen on Windows runners)
$Url  = "https://github.com/llvm/llvm-project/releases/download/llvmorg-15.0.7/LLVM-15.0.7-win64.exe"
Invoke-WebRequest -Uri $Url -OutFile "$env:TEMP\llvm-installer.exe"
Start-Process -Wait "$env:TEMP\llvm-installer.exe" -ArgumentList "/S"

# JVM target — Java 7+
winget install EclipseAdoptium.Temurin.21.JDK

# CLR target — .NET 9+
winget install Microsoft.DotNet.SDK.9

# WASM target — wasmtime with WASI
winget install BytecodeAlliance.Wasmtime

# JS target — Node 22+
winget install OpenJS.NodeJS

Editor Support

Visual Studio Code

Syntax highlighting, formatting, inline diagnostics, quick fixes, outline, breadcrumbs, workspace symbols.

Other editors

Use

awsum build

Compile your program for a target picked with -t. With -o OUT the result goes to a file; omit it for stdout. 

# Compile to LLVM IR
awsum build --program-type cli -t llvm -o out.ll          src/Main.aww
# Assemble to native binary with clang, then run
clang out.ll -o program && ./program "world"

# Compile to JVM bytecode
awsum build --program-type cli -t jvm  -o AwsumMain.class src/Main.aww
# Run with java
java AwsumMain "world"

# Compile to CLR assembly
awsum build --program-type cli -t clr  -o AwsumMain.dll   src/Main.aww
# Run with dotnet
dotnet AwsumMain.dll "world"

# Compile to WebAssembly module
awsum build --program-type cli -t wasm -o out.wasm        src/Main.aww
# Run with wasmtime
wasmtime out.wasm "world"

# Compile to JavaScript
awsum build --program-type cli -t js   -o out.js          src/Main.aww
# Run with Node.js
node out.js "world"

awsum run

Compile to a temporary location and execute with the matching system runtime in one step — useful for trying things out without leaving build artifacts on disk. Pick the target with -t. Input passed via --input or --stdin reaches main directly. 

# Run with inline input
awsum run --program-type cli -t llvm --input "world" src/Main.aww

# Run with stdin
echo "world" | awsum run --program-type cli -t llvm --stdin src/Main.aww

awsum check

Check the program for errors and warnings, without producing any artifact. The fast feedback loop during development. 

# Human-readable terminal output
awsum check --program-type cli src/Main.aww

# JSON output for editor integrations
awsum check --program-type cli --json src/Main.aww

# Strict mode — escalate warnings to non-zero exit code (for CI)
awsum check --program-type cli --strict src/Main.aww

awsum format

Format the source file. The implementation is "parse, then render". 

# Format and rewrite the file in place
awsum format -i src/Main.aww

# Print formatted source to stdout
awsum format src/Main.aww

Additional inspection commands — ast, core, asm, symbols — see awsum --help.