Building from Source

This guide walks you through building the Zeus compiler from source. This is recommended if you want to:

• Contribute to Zeus development
• Customize the compiler
• Work on the latest unreleased features
• Debug compiler internals

Tip

For regular usage, we recommend installing via Homebrew instead.

---

Prerequisites

1. Xcode Command Line Tools (macOS)

Required for the C/C++ compiler (clang) and linker:

xcode-select --install

2. Homebrew

If you don’t have Homebrew installed:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

3. Go (1.23 or later)

The Zeus compiler is written in Go:

brew install go

Verify:

go version
# Should show: go version go1.23.x darwin/arm64 (or amd64)

4. Zig (0.14 or later)

The Zeus runtime is written in Zig:

brew install zig

Verify:

zig version
# Should show: 0.14.x or later

5. LLVM (18)

The Zeus compiler uses LLVM via Go bindings. Install LLVM 18:

brew install llvm@18

Then add the following to your shell configuration (~/.zshrc or ~/.bashrc):

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

Apply the changes:

source ~/.zshrc  # or ~/.bashrc

Verify:

llvm-config --version
# Should show: 18.x.x

Caution

The Go LLVM bindings require these environment variables to be set correctly. If you encounter CGO or LLVM-related build errors, double-check that the paths are correct for your system.

---

Building the Compiler

1. Clone the repository

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

2. Install Go dependencies

   go mod download

3. Build the runtime

   The runtime provides garbage collection, arrays, and other built-in operations:

   make build-runtime

4. Build the compiler

   make build

   This creates a zeus binary in the project root.

5. Verify the build

   ./zeus --help

6. (Optional) Add to PATH

   To use zeus from anywhere:

   # Add to ~/.zshrc or ~/.bashrc
   export PATH="$HOME/path/to/zeus:$PATH"

---

Development Workflow

Running Tests

Run the full test suite:

make test

Run specific test categories:

make test-go        # Go unit tests
make test-runtime   # Runtime tests
make test-e2e       # End-to-end tests

Compiling & Running Zeus Programs

Use the playground directory for quick experiments:

# Create a test file
echo 'function main(): i32 { return 42; }' > playground/test.zs

# Compile and run
make run file=test

# Check exit code
echo $?  # Should print 42

Debug Mode

Enable verbose output to see compiler internals:

make run file=test debug=true

This will:

• Print the Zeus IR (intermediate representation)
• Save LLVM IR files to playground/debug/out/
• Show GC debug information

Build Flags

Flag	Description
debug=true	Enable debug output
nogc=true	Disable garbage collection
release=true	Use optimized runtime

Combine flags as needed:

make run file=test debug=true nogc=true

---

Project Structure

zeus/
├── cmd/                    # CLI entry points
│   ├── main.go             # Main entry point
│   ├── build.go            # Build command
│   └── lsp.go              # LSP server command
├── internal/               # Compiler internals
│   ├── lexer/              # Tokenizer
│   ├── parser/             # Parser & AST construction
│   ├── ast/                # Abstract Syntax Tree definitions
│   ├── ir/                 # Intermediate representation & type checking
│   ├── codegen/            # LLVM IR generation
│   ├── symbol_table/       # Symbol table management
│   ├── module/             # Module system
│   ├── lsp/                # Language Server Protocol
│   └── zeus_compiler/      # Compiler orchestration
├── runtime/                # Zig runtime
│   ├── gc.zig              # Garbage collector
│   ├── gc_runtime.zig      # GC runtime interface
│   ├── array_runtime.zig   # Array operations
│   └── stackmap.zig        # Stack map for GC
├── playground/             # Test files directory
├── examples/               # Example programs
├── test/                   # Test suites
│   ├── e2e/                # End-to-end tests
│   ├── lexer/              # Lexer tests
│   └── parser/             # Parser tests
├── lib/                    # Standard library
│   └── std/                # Standard modules
├── zeus-vscode/            # VS Code extension
└── docs/                   # Documentation (this site)

Tip

For a deep dive into the compiler internals, see Compiler Architecture.

---

Working on the Runtime

The runtime is written in Zig and provides:

• Garbage collection
• Array operations
• Memory management

Building the Runtime

make build-runtime

Runtime Debug Mode

For GC debugging:

make build-runtime-debug

Key Runtime Files

File	Purpose
runtime/gc.zig	Core garbage collector
runtime/gc_runtime.zig	GC interface for compiled code
runtime/array_runtime.zig	Dynamic array implementation
runtime/stackmap.zig	Stack map parsing for precise GC

---

Working on the VS Code Extension

The Zeus VS Code extension provides syntax highlighting and LSP support.

Setup

cd zeus-vscode
npm install
npm run compile

Testing

Press F5 in VS Code to launch the Extension Development Host.

Packaging

npm run package

---

Common Issues

LLVM Not Found / CGO Errors

If you see errors like cannot find -lLLVM or llvm-config: command not found:

1. Ensure LLVM 18 is installed:

   brew install llvm@18

2. Verify environment variables are set:

   echo $LLVM_PATH
   # Should show: /opt/homebrew/opt/llvm@18 (Apple Silicon)
   # Or: /usr/local/opt/llvm@18 (Intel)

3. Check that llvm-config is in PATH:

   which llvm-config
   llvm-config --version

4. Ensure CGO is enabled:

   go env CGO_ENABLED
   # Should show: 1
   
   # If not, enable it:
   go env -w CGO_ENABLED=1

5. Reload your shell configuration:

   source ~/.zshrc  # or ~/.bashrc

Runtime Build Fails

Ensure Zig is properly installed:

zig version  # Should be 0.14+

Tests Failing

Make sure the runtime is built first:

make build-runtime
make test

---

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run the test suite: make test
5. Submit a pull request

See our GitHub repository for contribution guidelines.

---

Makefile Reference

Command	Description
make build	Build the Zeus compiler
make build-runtime	Build the runtime
make build-runtime-debug	Build runtime with debug symbols
make run file=<name>	Compile and run a playground file
make compile file=<name>	Compile without running
make test	Run all tests
make test-go	Run Go tests only
make test-e2e	Run end-to-end tests
make clean	Remove build artifacts
make lsp	Start the Language Server

---

Next Steps

Hello World

Write your first Zeus program

Compiler Reference

Learn compiler commands