Building from Source

Build Zeus from source if you want to contribute, work on unreleased features, or debug the compiler and runtime. For everyday use, install via Homebrew instead.

Note

Zeus builds on macOS (Apple Silicon and Intel). The compiler is written in Go, the runtime in Zig, and memory management uses the bundled Boehm GC.

Prerequisites

Tool	Version	Install	Used for
Xcode Command Line Tools	latest	xcode-select --install	C compiler & linker
Go	1.25+	brew install go	the compiler (zeus.go)
LLVM	19	brew install llvm@19	native code generation (via CGO)
Zig	0.13.x	brew install zig	the runtime (zig build-lib)
CMake	3.x	brew install cmake	building the bundled Boehm GC

Pin the exact major versions

Zeus links against LLVM 19 (the Go build uses -tags llvm19) and the runtime is built with Zig 0.13.x (the event loop, libxev, is pinned to a Zig 0.13-compatible commit). Newer major versions of either tool will not build.

Configure LLVM for CGO

The Go LLVM bindings need to find LLVM 19. Add this to your ~/.zshrc (or ~/.bashrc):

# LLVM 19 for Zeus
export LLVM_PATH="$(brew --prefix llvm@19)"
export PATH="$LLVM_PATH/bin:$PATH"
export CGO_CFLAGS="-I$LLVM_PATH/include"
export CGO_LDFLAGS="-L$LLVM_PATH/lib -Wl,-rpath,$LLVM_PATH/lib"

Reload and verify:

source ~/.zshrc
llvm-config --version   # 19.x.x

Building

1. Clone the repository

   git clone https://github.com/ameerthehacker/zeus.git
   cd zeus

2. Build the compiler

   make build

   This produces a zeus binary in the project root. Verify it:

   ./zeus --help

3. Compile and run a program

   The make run target orchestrates the full toolchain — it builds the Boehm GC with CMake, the Zig runtime, then compiles and runs a file from playground/:

   echo 'function main(): i32 { return 42; }' > playground/test.zs
   make run file=test
   echo $?   # 42

Tip

The make targets set ZEUS_HOME automatically so the compiler can locate the runtime, prelude, and standard library. If you invoke ./zeus build directly, export ZEUS_HOME to the repo root first.

Development workflow

Running tests

make test        # runtime + Go unit tests + runtime tests
make test-go     # Go unit tests only
make test-e2e    # end-to-end tests (compiles real programs)

Compiling playground files

make compile file=test   # compile only, no run
make run file=test       # compile and run
make zeus-fmt file=test  # format playground/test.zs in place

Build flags

Append these to make compile / make run:

Flag	Effect
debug=true	Emit Zeus IR and LLVM IR, enable GC debug output
nogc=true	Disable garbage collection
release=true	Build the optimized (ReleaseSmall) runtime

make run file=test debug=true

Project structure

zeus/
├── zeus.go                 # CLI entry point
├── Makefile                # Build & test targets
├── CMakeLists.txt          # Builds the bundled Boehm GC (bdwgc)
├── cmd/                    # Cobra CLI commands (build, run, check, lsp, ...)
├── internal/               # Compiler implementation
│   ├── token/  lexer/  ast/  parser/
│   ├── ir/                 # HIR/LIR, type checking, lowering
│   ├── codegen/            # LLVM IR generation
│   ├── zeus_value/         # Zeus type system
│   ├── module/  symbol_table/
│   ├── prelude/            # Self-hosted primordials (Console, ...)
│   ├── zeus_compiler/      # Pass orchestration
│   └── lsp/                # Language Server Protocol
├── runtime/                # Zig runtime (GC glue, arrays, timers via libxev)
├── lib/std/                # Standard library modules
├── playground/             # Scratch .zs files for make compile/run
├── test/                   # Go + end-to-end test suites
├── zeus-vscode/            # VS Code extension
└── docs/                   # This documentation site

Troubleshooting

llvm-config: command not found or CGO link errors — LLVM 19 isn’t on your PATH. Confirm brew --prefix llvm@19 resolves, re-export the variables above, and check go env CGO_ENABLED returns 1.

Runtime build fails — make sure you’re on Zig 0.13.x (zig version); newer Zig releases are incompatible with the pinned libxev.

GC link errors (-lgc) — the Boehm GC is built by CMake on first make run/make compile. Ensure CMake is installed and you have network access (it’s fetched via CMake FetchContent).

Tests failing — build the runtime first with make build-runtime, then make test.

Contributing

1. Fork the repository and create a feature branch.
2. Make your change and format Go code with make fmt.
3. Run make test (and make test-e2e for language changes).
4. Open a pull request.

Makefile reference

Command	Description
make build	Build the zeus compiler binary
make build-runtime	Build the Zig runtime
make run file=<name>	Compile and run playground/<name>.zs
make compile file=<name>	Compile playground/<name>.zs without running
make check file=<name>	Type-check and emit IR
make test	Run the full test suite
make test-e2e	Run end-to-end tests
make lsp	Build and start the language server
make fmt	Format Go source
make clean	Remove build artifacts