Awsum

Documentation

Use the awsum CLI, plus the design documents that describe the language and its compiler.

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 (the -D flags pin I/O charsets to UTF-8 so non-ASCII argv survives the JVM startup decode on hosts whose default isn't UTF-8 — Windows in particular)
java -Dsun.jnu.encoding=UTF-8 -Dfile.encoding=UTF-8 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 run with the matching system runtime in one step. Pick the target with -t. Everything after -- is forwarded as command-line arguments and read with IO.Args.getArgs as a List String; with no --, the list is empty (Right Nil). The child inherits awsum's stdin, so a shell pipe or < file reaches IO.Stdin.readAll verbatim. The two channels are independent and can be used together. 

# argv — after the -- separator
awsum run --program-type cli -t llvm src/Main.aww -- hello world

# stdin — pipe or < file
echo "world" | awsum run --program-type cli -t llvm src/Main.aww
awsum run --program-type cli -t llvm src/Main.aww < input.txt

# both at once
echo "data" | awsum run --program-type cli -t llvm src/Main.aww -- hello

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.

Further reading

Design documents and the bundled prelude. They live in the compiler repo on GitHub — single source of truth, kept in lockstep with the released compiler.

Design documents

Bundled prelude