Compiler Reference

Usage

joulec <INPUT> [OPTIONS]

Where <INPUT> is a .joule source file (or a foreign source file when using --lift-run).

Options

Environment Variables

Examples

Basic Compilation

# Compile to executable via C backend
joulec program.joule --emit c -o program.c
cc -o program program.c

# Compile with energy checking
joulec program.joule --emit c -o program.c --energy-check

# Release build with optimizations
joulec program.joule --release -o program

Emit Intermediate Representations

# Emit the AST (for debugging)
joulec program.joule --emit ast

# Emit HIR (typed intermediate representation)
joulec program.joule --emit hir

# Emit MIR (mid-level IR, after lowering)
joulec program.joule --emit mir

# Emit EIR (Energy IR with picojoule cost annotations)
joulec program.joule --emit eir

JIT Compilation

# JIT-compile and run immediately
joulec --jit program.joule

# Watch mode: re-compile and re-run on file changes
joulec --watch program.joule

See JIT Compilation for details.

Polyglot Energy Analysis

# Lift and run Python with energy measurement
joulec --lift-run python script.py

# Lift and run JavaScript with energy measurement
joulec --lift-run js app.js

# Apply energy optimization before running
joulec --energy-optimize --lift-run python script.py

See Polyglot Energy Analysis for details.

Advanced Optimization

# E-graph algebraic optimization
joulec program.joule --emit c --egraph-optimize -o program.c

# Profile-guided optimization (two-phase)
joulec program.joule --profile-generate -o program
./program                    # generates profile data
joulec program.joule --profile-use profile.json -o program_optimized

# Incremental compilation
joulec program.joule --incremental -o program

Testing and Benchmarking

# Run tests with energy reporting
joulec program.joule --test

# Run benchmarks with energy reporting
joulec program.joule --bench

JSON Energy Output

# Get energy reports as JSON
JOULE_ENERGY_JSON=1 joulec program.joule --emit c -o program.c --energy-check

Compilation Pipeline

Source code flows through these stages:

Source (.joule)
    |
    v
  Lexer ---------- Tokens
    |
    v
  Parser --------- AST (Abstract Syntax Tree)
    |
    v
  Type Checker ---- HIR (High-level IR) + Type Information
    |
    +-- Energy Budget Checker (if --energy-check)
    |
    v
  EIR Lowering ---- EIR (Energy IR) [if --egraph-optimize or --emit eir]
    |
    +-- E-Graph Optimizer (30+ algebraic rewrite rules)
    |
    v
  MIR Lowering ---- MIR (Mid-level IR)
    |
    v
  Borrow Checker -- Ownership/lifetime verification
    |
    v
  Code Generation
    +-- C Backend ---------- C source code
    +-- Cranelift Backend --- Native binary (fast compilation)
    +-- Cranelift JIT ------- In-memory execution (--jit/--watch)
    +-- LLVM Backend -------- Native binary (optimized)
    +-- MLIR Backend -------- GPU/accelerator code
    +-- WASM Backend -------- WebAssembly

Incremental Compilation

When --incremental is enabled, the compiler:

1. Fingerprints each source file using FNV-1a hashing
2. Builds a dependency graph between modules
3. On recompilation, only reprocesses files whose fingerprint changed (or whose dependencies changed)
4. Caches query results to disk as JSON for persistence across sessions

Profile-Guided Optimization

PGO is a two-phase process:

1. Phase 1 (--profile-generate): The compiler instruments the C output with basic-block counters. Running the instrumented binary produces a JSON profile with execution frequencies.
2. Phase 2 (--profile-use): The compiler reads the profile and refines EIR energy cost estimates using actual execution frequencies. Loop trip counts are derived from back-edge counter ratios. Hot paths get more accurate energy budgets.

Backends

C Backend (--emit c)

Generates portable C source code. This is the primary backend and the one used for the bootstrap compiler. The generated C compiles with any standard C compiler (gcc, clang, cc).

joulec program.joule --emit c -o program.c
cc -o program program.c

Features:

• Freestanding mode for embedded targets (jrt_* runtime abstraction)
• #line directives for source-level debugging
• Energy instrumentation for PGO

Cranelift Backend

Fast compilation, suitable for development. Uses the Cranelift code generator. Enable with --features cranelift.

Cranelift JIT Backend

In-memory compilation and execution. No intermediate files. Enable with --features jit.

joulec --jit program.joule

LLVM Backend

Optimized compilation for release builds. Requires LLVM 16+. Enable with --features llvm.

MLIR Backend

Heterogeneous computing with GPU/accelerator support. Targets CUDA, Metal, and ROCm. Enable with --gpu.

WASM Backend

WebAssembly output for browser and edge deployment.

File Extension

Joule source files must use the .joule extension. The compiler rejects all other extensions (except when using --lift-run, which accepts .py, .js, and .c).

Energy Checking

When --energy-check is passed, the compiler performs static analysis on every function with an #[energy_budget] attribute. Functions that exceed their declared budget produce a compilation error.

See Energy System Guide for details.

Diagnostics

The compiler produces structured error messages with source locations:

error[E0001]: mismatched types
  --> program.joule:10:15
   |
10 |     let x: i32 = "hello";
   |                  ^^^^^^^ expected i32, found String

Warnings are shown for potential issues but don't prevent compilation (unless you've set strict mode).