Compiling Programs

Zeus ships three commands for working with source files:

Command	What it does
zeus run [file]	Compile and immediately execute (no binary left behind)
zeus check [file]	Check for errors without producing any output
zeus build [file]	Compile to a binary you keep

---

zeus run

The fastest way to execute a Zeus program during development. Compiles in debug mode to a temporary file, runs it, then discards the binary.

zeus run main.zs

Use this while iterating — no build artifacts to clean up, one command instead of two.

---

zeus check

Runs all compilation passes (parsing, type checking, IR lowering) and reports any errors, but stops before generating a binary. Useful for catching mistakes quickly without waiting for code generation.

zeus check main.zs

This is also what the language server uses under the hood to provide inline diagnostics.

---

zeus build

Compiles your program into a binary you can distribute or run repeatedly. By default it produces a debug build — fast to compile, easy to inspect. Add --release for a fully optimized binary.

# Debug build (default)
zeus build main.zs

# Release build
zeus build main.zs --release

Debug vs Release

	Debug	Release
Compile time	Fast	Slower
Optimization	None	Full
Binary size	Larger	Smaller
Incremental cache	Yes	No (full rebuild)
Output directory	target/debug/	target/release/

Output Layout

Debug

target/
  debug/
    obj/   ← cached object file per source file
    bin/   ← executable

Release

target/
  release/
    obj/   ← single merged object file
    bin/   ← executable

Flags

# Custom output path
zeus build main.zs -o /usr/local/bin/myapp

# Custom target directory
zeus build main.zs --target-dir /workspace

# Release build with custom output
zeus build main.zs --release -o /usr/local/bin/myapp

---

How Release Compilation Works

Release mode applies whole-program optimization by merging all source files into a single compilation unit before optimizing — similar in spirit to link-time optimization (LTO).

Why a single unit?

When all source files are compiled together, the optimizer can inline across file boundaries, eliminate dead code from imported modules, and apply deeper optimizations. This produces binaries that are typically both smaller and faster than per-file compilation at the same optimization level.

Caution

Release builds always recompile everything. The per-file incremental cache used by debug builds does not apply in release mode because the whole-program merge must see every file fresh.

---

Inspecting Compiler Output

Set the ZEUS_DEBUG environment variable to dump the low-level compiler output alongside the object file:

ZEUS_DEBUG=1 zeus build main.zs --release

This writes two files to target/release/obj/:

target/release/obj/program.o    ← object file
target/release/obj/program.ll   ← low-level compiler output

The .ll file shows exactly what the optimizer produced — useful for understanding inlining decisions and dead code removal.