Welcome to GAL (Gödelian Actor Language) - the world's first programming language with native chaos engineering capabilities! This guide will get you up and running with GAL in minutes.
GAL is a memory-safe, actor-based programming language that combines:
- Actor Model Concurrency - Scalable, fault-tolerant systems
- Native Chaos Engineering - Built-in fault injection and resilience testing
- Gödelian Self-Reference - Programs that can reason about themselves
- Formal Verification - Mathematical correctness proofs
- Self-Optimization - AI-powered runtime performance improvement
- Rust 1.70+ (for building from source)
- LLVM 17+ (optional, for LLVM backend)
- Git
# Clone the repository
git clone https://github.com/geeknik/gal
cd gal
# Build with default features
cargo build --release
# Build with all features
cargo build --release --all-features
# Install GAL tools
cargo install --path . --binsAfter building, you'll have access to these command-line tools:
galc- GAL compilergal-repl- Interactive REPLgal-chaos- Chaos engineering CLIgal-language-server- LSP server for editorsgal-verify- Formal verification toolgal-pkg- Package managergal-bench- Performance benchmarking
Create a file called hello.gal:
// hello.gal - Your first GAL program
actor Greeter {
state greeting: String = "Hello"
on "greet" =>
println(greeting + ", World!")
}
actor Main {
new create() =>
let greeter = spawn Greeter()
send(greeter, "greet")
}
Compile and run using the C backend:
galc compile --backend c hello.gal -o hello.c
gcc -o hello hello.c -lpthread
./helloGAL supports typed message parameters:
// hello_actors.gal - Actor-based hello world with parameters
actor Greeter {
state greeting: String = "Hello"
on Greet(name: String) =>
println(greeting + ", " + name + "!")
}
actor Main {
new create() =>
let greeter = spawn Greeter()
send(greeter, Greet("Actor World"))
send(greeter, Greet("GAL"))
}
// Basic actor with state
actor Counter {
state count: Int = 0
state max_count: Int = 10
new create(max: Int) =>
max_count = max
send(self, "increment")
on "increment" =>
count = count + 1
println("Count: " + count)
if count < max_count then
send(self, "increment")
else
println("Done counting!")
on "reset" =>
count = 0
println("Counter reset")
}
actor Main {
new create() =>
let counter = spawn Counter(5)
}
// Actors use pattern matching on incoming messages
actor MessageRouter {
on "ping" =>
println("Received ping!")
on Greet(name: String) =>
println("Hello, " + name + "!")
on Calculate(x: Int, y: Int) =>
let result = x + y
println("Sum: " + result)
}
GAL is designed for Rust-like ownership semantics for memory safety. Currently, the C backend uses simple memory management. Full ownership tracking is planned:
// Planned syntax for ownership
fn transfer_ownership() {
let data = vec![1, 2, 3, 4, 5]
let moved_data = data // data would be moved
// println(data) // Would error: use after move
println(moved_data) // OK
}
Note: Memory safety features are in development. The current C backend uses manual memory management.
GAL's unique selling point is native chaos engineering. The gal-chaos tool enables fault injection testing:
# Run chaos experiments with fault injection
gal-chaos examples/chaos_demo.gal --experiment random --fault-rate 0.1
# Available experiment types:
# - random: Random fault injection
# - message-drop: Drop messages between actors
# - message-delay: Delay message delivery
# - actor-crash: Simulate actor crashes
# - partition: Network partition simulation
# - overload: System overload testingDefine formal invariants that must hold even under chaos:
// Planned annotation syntax
@chaos_contract(
invariant: "count >= 0",
tested_under: [MessageDrop(0.1), ActorCrash]
)
actor ReliableCounter {
state count: Int = 0
on "increment" =>
count = count + 1
on "get" =>
reply(count)
}
Note: Chaos contract annotations are parsed but full integration is in development. Use
gal-chaosCLI for chaos testing today.
GAL supports basic self-reference through the reflect() built-in:
// Basic self-reflection - works today
actor SelfAware {
state name: String = "Observer"
on "analyze" =>
println("My source code:")
println(reflect(self))
}
actor Main {
new create() =>
let observer = spawn SelfAware()
send(observer, "analyze")
}
The reflect(self) function returns a string representation of the actor's structure.
The following features are in the compiler architecture but not yet fully integrated:
- Quine Generation - Programs that output their own source code
- Self-Modification - Actors that can modify their own behavior at runtime
- Fixed-Point Computation - Self-referential calculations
See examples/quine.gal and examples/godel_self_modification_demo.gal for aspirational syntax.
# Start the GAL REPL
gal-repl
# The REPL provides an interactive environment for experimenting with GAL
# Note: Full actor spawning in REPL is in developmentGAL provides Language Server Protocol (LSP) support via gal-language-server:
# Start the language server for your editor
gal-language-server
# Features available:
# - Syntax highlighting
# - Code completion
# - Error diagnostics
# - Go to definition
# - Hover documentation
# - Refactoring support
# - Actor system visualizationThe gal-verify tool provides formal verification capabilities:
# Verify a GAL program using Z3 SMT solver
gal-verify examples/verification_example.gal
# Use different SMT backends
gal-verify --smt-backend z3 your_program.gal
gal-verify --smt-backend cvc5 your_program.gal
# Generate formal proofs
gal-verify --generate-proofs --export-format coq your_program.gal
# Check specific properties
gal-verify --verify-safety --verify-deadlock your_program.gal// Planned annotation syntax for contracts
@requires("amount > 0")
@ensures("balance >= 0")
actor BankAccount {
state balance: Int = 0
on Deposit(amount: Int) =>
balance = balance + amount
}
Note: Contract annotations are parsed but verification integration is in development.
# Initialize a new GAL package
gal-pkg init my_actor_system
cd my_actor_system
# Package structure
# my_actor_system/
# ├── gal.toml # Package configuration
# ├── src/
# │ └── main.gal # Main source file
# └── tests/
# └── integration.gal[package]
name = "my_actor_system"
version = "0.1.0"
description = "My first GAL actor system"
authors = ["Your Name <you@example.com>"]
license = "MIT"
[dependencies]
gal_std = "1.0"
chaos_utils = "0.5"
[features]
default = ["chaos-engineering"]
chaos-engineering = []
formal-verification = []
[chaos]
default_profile = "development"
[chaos.profiles.development]
fault_injection_rate = 0.01
max_concurrent_faults = 2
[chaos.profiles.production]
fault_injection_rate = 0.001
max_concurrent_faults = 1# Add a dependency
gal-pkg add distributed_actors --version "^2.0"
# Update dependencies
gal-pkg update
# Build with dependencies
gal-pkg build
# Run tests
gal-pkg test
# Publish to registry
gal-pkg publishThe gal-bench tool provides comprehensive performance measurement:
# List available benchmarks
gal-bench list
# Run all benchmarks
gal-bench run --all
# Run specific benchmark category
gal-bench run --category actor
# Compare results against baseline
gal-bench compare baseline.json current.json
# Generate performance report
gal-bench report --format htmlThe compiler supports multiple optimization levels:
# No optimization (fastest compile)
galc compile -O 0 program.gal
# Default optimization
galc compile -O 2 program.gal
# Maximum optimization
galc compile -O 3 program.galDistributed actor support is in development. See examples/distributed_kv_store.gal for the planned syntax.
- Location-transparent actor spawning
- Automatic cluster membership management
- Built-in consensus protocols (Raft, Paxos)
- Network partition handling
The examples/ directory contains many sample programs:
# Basic actor messaging
galc compile --backend c examples/hello_world.gal -o hello.c
gcc -o hello hello.c -lpthread && ./hello
# Stateful counter with self-messaging
galc compile --backend c examples/counter.gal -o counter.c
gcc -o counter counter.c -lpthread && ./counterThese examples demonstrate planned syntax and features:
examples/chaos_demo.gal- Chaos engineering conceptsexamples/distributed_kv_store.gal- Distributed systems patternsexamples/secure_vault.gal- Security patternsexamples/web_server.gal- Web service architecture
actor ChatRoom {
state messages: Int = 0
on Post(text: String) =>
messages = messages + 1
println("Message #" + messages + ": " + text)
}
actor Main {
new create() =>
let room = spawn ChatRoom()
send(room, Post("Hello everyone!"))
send(room, Post("Welcome to GAL!"))
}
actor Counter {
state count: Int = 0
on Increment(amount: Int) =>
count = count + amount
println("Count is now: " + count)
on "reset" =>
count = 0
println("Counter reset")
}
actor Main {
new create() =>
let c = spawn Counter()
send(c, Increment(5))
send(c, Increment(3))
send(c, "reset")
}
The following sections describe planned features. See individual example files for syntax previews.
// Planned: Custom syntax for actor patterns
// See examples for aspirational syntax
// Planned: Call C functions from GAL
// The C backend generates C code that can interop with C libraries
- Keep actors small and focused
- Use message passing for all inter-actor communication
- Design for fault tolerance from the start
- Use state fields for actor-local data
- Use the C backend for development and testing
- Check compilation with
galc compile --check - Run chaos experiments with
gal-chaos - Use
gal-verifyfor formal verification experiments
- GitHub Issues: https://github.com/geeknik/gal/issues
- Examples: See the
examples/directory for working code samples
Now that you've got GAL running:
- Try the examples - Compile and run
examples/hello_world.galandexamples/counter.gal - Experiment with chaos - Use
gal-chaosto test resilience - Explore verification - Try
gal-verifyon your programs - Read the source - The compiler is well-documented Rust code
- Contribute - The C backend and runtime are actively developed
Welcome to GAL! 🚀
Note: GAL is experimental software in active development. Features marked as "planned" are in the roadmap but may not be fully implemented yet.