Getting Started

Install Joule

Build the toolchain from source — or skip install entirely and try it in the browser playground.

Build from source

Requires a Rust toolchain. The build produces two binaries: joule (the project driver) and joulec (the compiler).

# from the joulesperbit workspace
$ cd crates/joule-lang
$ cargo build --release
$ export PATH="$PWD/target/release:$PATH"

macOS with Homebrew LLVM: export LIBRARY_PATH=/opt/homebrew/lib first so the MLIR backend can link libzstd.

Bootstrap (no Rust)

The compiler can build itself from Joule source — only a C compiler required.

$ cd bootstrap && make
$ ./joulec hello.joule -o hello && ./hello

Quick Start

# Create a new project
$ joule new sensor_pipeline
$ cd sensor_pipeline

# Build with energy receipt
$ joule build
  Compiling sensor_pipeline v0.1.0
  Energy: 12.4 μJ (compute: 8.1, memory: 3.2, io: 1.1)
  Finished in 0.34s

# Run
$ joule run
  Hello from Joule!

# Run with energy profiler
$ joule run --energy-profile
  ┌─────────────────────┬──────────┐
  │ Function            │ Energy   │
  ├─────────────────────┼──────────┤
  │ main                │   5.2 μJ │
  │ process_data        │   4.1 μJ │
  │ io::write_line      │   3.1 μJ │
  └─────────────────────┴──────────┘

CLI Commands

joule new <name> Create a new project

joule build Compile with energy analysis

joule run Build and execute

joule check Type-check without codegen

joule test Run tests with energy receipts

joule bench Benchmark with energy comparison

joule fmt Format source code

joule doc Generate documentation

joule repl Interactive REPL with energy display