Building Moxie

System Requirements

Component	Version	Notes
Go	1.25+	Host compiler
LLVM	19	Must be exactly 19 (go-llvm bindings are version-specific)
clang	19	For compiling C runtime components (musl, bdwgc, compiler-rt)
lld	19	LLVM linker for final binary linking

Arch Linux

sudo pacman -S llvm19 clang19 lld19

Ubuntu/Debian

# Add LLVM apt repository for version 19, then:
sudo apt install llvm-19-dev clang-19 lld-19

Building the Compiler

cd /path/to/moxie

# Set CGO flags to find LLVM 19
export CGO_CPPFLAGS="-I/usr/lib/llvm19/include"
export CGO_LDFLAGS="-L/usr/lib/llvm19/lib $(/usr/lib/llvm19/bin/llvm-config --ldflags --libs all) -lclang -lstdc++ -lz -lzstd"

# Build (GOWORK=off if parent go.work doesn't include moxie)
GOWORK=off go build -tags llvm19 -o moxie ./main.go

The binary is statically linked against LLVM 19 libraries.

Using the Compiler

# Set MOXIEROOT to the source tree (contains src/, lib/)
export MOXIEROOT=/path/to/moxie

# LLVM 19 tools must be in PATH
export PATH="/usr/lib/llvm19/bin:$PATH"

# Build a program
./moxie build -o hello hello.mx

# Run
./hello

Build Flags

-o <file>       output filename
-opt <level>    optimization: 0, 1, 2, s, z (default "z")
-gc <gc>        garbage collector: none, leaking, conservative, boehm (default from target)
-scheduler <s>  scheduler: none, tasks (default "tasks")
-panic <mode>   panic strategy: print, trap (default "print")
-stack-size <n> goroutine stack size in bytes
-tags <tags>    extra build tags
-x              print commands as they execute
-work           keep temporary build directory

Subcommands

moxie build     compile a program
moxie run       compile and run
moxie test      compile and run tests
moxie clean     clean build cache
moxie version   print version
moxie env       print environment variables
moxie info      show target information
moxie list      list available targets
moxie help      show help

Output Binaries

Moxie produces fully static binaries:

Linux: statically linked against musl libc, Boehm GC, compiler-rt
Darwin: linked against minimal macOS SDK
No glibc, no dynamic libraries, no threads

Typical sizes:

Hello world: ~400KB
With spawn: ~420KB

C Libraries

The following C libraries live under lib/ and are compiled automatically:

Library	Purpose	Source
`lib/musl`	C standard library (static)	musl-libc
`lib/bdwgc`	Boehm garbage collector	ivmai/bdwgc @ 7577ca7
`lib/compiler-rt-builtins`	LLVM runtime builtins	LLVM compiler-rt

Libraries are compiled once and cached in ~/.cache/moxie/.

building.md raw