https://github.com/aether-lang-org/aether
A compiled actor-based programming language with type inference, designed for concurrent systems.
https://github.com/aether-lang-org/aether
actor-model c compiler concurrency embedded-c message-passing open-source pattern-matching programming-language systems-programming type-inference wasm
Last synced: 7 days ago
JSON representation
A compiled actor-based programming language with type inference, designed for concurrent systems.
- Host: GitHub
- URL: https://github.com/aether-lang-org/aether
- Owner: aether-lang-org
- License: mit
- Created: 2025-03-07T02:23:27.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-05-10T13:30:53.000Z (10 days ago)
- Last Synced: 2026-05-10T14:52:36.521Z (10 days ago)
- Topics: actor-model, c, compiler, concurrency, embedded-c, message-passing, open-source, pattern-matching, programming-language, systems-programming, type-inference, wasm
- Language: C
- Homepage:
- Size: 28.8 MB
- Stars: 91
- Watchers: 2
- Forks: 5
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Aether Programming Language
[](https://github.com/nicolasmd87/aether/actions/workflows/ci.yml)
[](https://github.com/nicolasmd87/aether/actions/workflows/windows.yml)
[](LICENSE)
[]()
A compiled actor-based programming language with type inference, designed for concurrent systems. Aether compiles to C for native performance and seamless C interoperability.
## Overview
Aether is a compiled language that brings actor-based concurrency to systems programming. The compiler generates readable C code, providing portability and interoperability with existing C libraries.
**Core Features:**
- Actor-based concurrency with automatic multi-core scheduling
- Type inference with optional annotations
- Compiles to readable C for portability and C library interop
- Lock-free message passing with adaptive optimizations
- Three-layer capability model for sandboxing untrusted code and hosting other languages in-process — `--emit=lib` gates stdlib at compile time, `hide`/`seal except` gates scopes, LD_PRELOAD gates libc
- Go-style result types: `a, err = func()` with `_` discard
- Package management: `ae add host/user/repo[@version]` (GitHub, GitLab, Bitbucket, any git host)
- Production-grade HTTP server in stdlib — TLS, HTTP/1.1 keep-alive, **HTTP/2** (h2 + h2c via libnghttp2 with ALPN, GOAWAY graceful shutdown, server-level pthread pool for concurrent stream dispatch), WebSocket (RFC 6455), Server-Sent Events, **zero-copy `sendfile(2)` static-file serving** (Linux + macOS, with TCP_CORK / TCP_NOPUSH coalescing), plus a stack of composable middleware (CORS, basic/bearer/session-cookie auth, rate limiting, real-IP, vhost, gzip, static files, rewrite, error pages), `/healthz` + `/readyz` health probes, structured access logs, and Prometheus metrics. See [HTTP Server](docs/http-server.md).
- nginx-class **reverse proxy** in stdlib — `std.http.proxy` forwards inbound requests to a pool of upstream servers with five load-balancing algorithms (round-robin / least-conn / ip-hash / smooth weighted RR / cookie-hash sticky), active health checks, in-memory LRU response cache with Vary-aware keying and RFC 7234 cacheability rules, per-upstream circuit breaker, idempotent retry with `proxy_next_upstream` semantics, per-upstream token-bucket rate limit, active drain, W3C Trace-Context propagation, and a Prometheus 0.0.4 metrics endpoint. Hop-by-Hop header handling per RFC 7230. See [Reverse Proxy](docs/http-reverse-proxy.md).
- **`--emit=lib` symbol catalog (`aether_lib_meta`) + `ae lib-info` reflection** — every shared library Aether emits exports a single zero-allocation, layout-stable `static const AetherLibMeta*` describing every exported function (Aether name, C symbol, signature, source file, source line). Walks straight from Python ctypes / Java Panama / Ruby Fiddle / Go cgo / hand-rolled `dlsym` — no JSON, no parsing, the catalog literally lives in `.rodata`. Schema is versioned (`"1.0"`) with explicit append-only growth at the struct tail (closure-context records reserved for v2). `ae lib-info ` is a turnkey reader: dlopen → format-print the catalog. See [Reflection: the symbol catalog](docs/emit-lib.md#reflection-the-symbol-catalog-aether_lib_meta--403).
- **`--emit=lib` resource caps** — sandbox untrusted Aether plugins inside trusted hosts. Embedders set a process-wide memory ceiling (`aether_set_memory_cap`) and per-thread wall-clock deadline (`aether_set_call_deadline`) via the public C surface in `include/libaether.h`. The codegen emits a tripwire at every loop head under `--emit=lib` (zero overhead on `--emit=exe`), so guests that allocate uncapped or spin in infinite loops are bounded predictably. Memory accounting tracks current usage, not high-water-mark, so long-running guests aren't tripped by cumulative churn.
- **DSL block receiver scoping** — inside `receiver.method(args) { body }`, bare-name function references resolve through the receiver's namespace before erroring. SDK builders no longer require an `import X (setter1, setter2, ...)` line to make trailing-block setters resolve.
- **`@derive(eq)` on structs** — annotate a struct with `@derive(eq)` to synthesize `int T_eq(T a, T b)` automatically (field-by-field `==` chain); supports primitive numeric and string fields.
- **Automatic string-ownership tracking** — every string variable carries a compiler-emitted `_heap_` companion that flips on every reassignment, so heap-allocated buffers are reclaimed eagerly without an explicit `defer string.free(s)`. Covers single-value reassignment, tuple destructure, cross-block flow, function-exit cleanup, and escape detection through call-args (`@retain` annotation marks "stored" parameters; default `string`-param treatment is read-only). Recognised heap sources include stdlib `string.concat` / `substring` / `to_upper` / `to_lower` / `trim`, string interpolation, user-defined `-> string` functions whose body provably returns heap (recursive structural escape analysis with cycle detection), and tuple-returning externs annotated `(string @heap, ...)`. See [String memory model](docs/memory-management.md#string-memory-model-heap-string-tracker) for the full picture.
- **Eiffel-style runtime contracts** — `requires` and `ensures` clauses attach pre/postconditions directly to function declarations: `add(a, b) -> int requires a >= 0 ensures result >= a { return a + b }`. Each clause lowers to `if (!()) aether_panic(" violation: in ");` — preconditions at function entry, postconditions before every `return` (with `result` bound to the about-to-be-returned value). Multiple clauses, freely interleaved, each checked independently so the panic message names the specific failed predicate. `--no-contracts` build flag suppresses emission entirely (zero per-call cost — the analog of C's `-DNDEBUG`). See [Function contracts](docs/language-reference.md#function-contracts-requires--ensures-issue-348).
## Runtime Features
The Aether runtime implements a native actor system with optimized message passing:
### Concurrency Model
- **Multi-core partitioned scheduler** with locality-aware actor placement
- **Locality-aware spawning** — actors placed on the caller's core for efficient parent-child messaging
- **Message-driven migration** — communicating actors automatically converge onto the same core
- **Work-stealing fallback** for idle core balancing
- **Lock-free SPSC queues** for same-core messaging
- **Cross-core messaging** with lock-free mailboxes
### Memory Management
- **Manual by default** — use `defer` for cleanup. All allocations cleaned up explicitly.
- **Automatic string-ownership tracking** — heap-allocated strings auto-freed on reassignment, tuple destructure, and function exit; opt-in `@retain` extern annotation for parameters that store the pointer beyond the call. See [String memory model](docs/memory-management.md#string-memory-model-heap-string-tracker).
- **Arena allocators** for actor lifetimes
- **Memory pools** with thread-local allocation
- **Actor pooling** reducing allocation overhead
- **Zero-copy message delivery** in single-actor main-thread mode (caller stack passed directly)
### Message Optimization
- **Sender-side batching** for reduced overhead
- **Message coalescing** for higher throughput
- **Adaptive batching** dynamically adjusts batch sizes
- **Direct send** for same-core actors bypasses queues
### Capabilities & Sandboxing
Aether is compiled, but comes with a capability system normally associated with interpreted / VM-hosted languages. Three enforcement layers:
- **Compile-time module gate** — `--emit=lib` rejects `std.fs` / `std.net` / `std.os` imports by default; the host opts each in with `--with=fs,net,os`.
- **Compile-time scope gate** — `hide ` and `seal except ` on any lexical block (closure, trailing-block DSL, actor handler) block ambient names from leaking into contained code.
- **Runtime process gate** — `libaether_sandbox.so` (LD_PRELOAD) intercepts libc (`open*`, `connect`/`bind`, `execve`, `mmap`, `dlopen`, `getenv`) against a builder-DSL grant list; inherited across `execve` to child processes.
The same grant list + LD_PRELOAD also contains embedded interpreters — an Aether `main()` can host Lua, Python, Perl, Ruby, Tcl, and JavaScript in-process (`contrib.host..run_sandboxed(perms, code)`) with the same permission model that scopes Aether's own libc calls. In the reverse direction, `--emit=lib` + `ae build --namespace` produce a `.so` plus a typed SDK (Python ctypes, Java Panama, Ruby Fiddle) so host-language apps can embed Aether without writing FFI by hand.
Mashup of Pony object capabilities, Java's removed SecurityManager, and a fraction of gVisor — see [Containment Sandbox](docs/containment-sandbox.md) for the full comparison, threat model, and known bypass surface.
### Platform Portability
- **Compile-time platform detection** via `AETHER_HAS_*` flags (threads, atomics, filesystem, networking, NUMA, SIMD, affinity)
- **Cooperative scheduler** for single-threaded platforms (WebAssembly, embedded, bare-metal)
- **Graceful degradation** — stdlib stubs return errors when features are unavailable
- **`ae build --target wasm`** compiles to WebAssembly via Emscripten
- **`PLATFORM=wasm|embedded`** Makefile targets for cross-compilation
- **Docker CI images** for Emscripten (WASM) and ARM (embedded) verification
### Advanced Features
- **Actor timeouts** — `receive { ... } after N -> { ... }` fires handler if no message arrives within N ms
- **Cooperative preemption** (opt-in) — `AETHER_PREEMPT=1` breaks long handlers, `--preempt` yields at loop back-edges
- **Reactor-pattern async I/O** — `net.await_io(fd)` suspends an actor on a file descriptor without blocking any scheduler thread; the runtime's per-core I/O poller (epoll/kqueue/poll) delivers an `IoReady { fd, events }` message when the fd becomes readable
- **SIMD batch processing** with AVX2 support
- **NUMA-aware allocation** for multi-socket systems
- **CPU feature detection** for runtime optimization selection
- **Performance profiling** with per-core cycle counting
- **Message tracing** for debugging
### Benchmarks
Cross-language benchmark suite based on the [Savina Actor Benchmark Suite](https://dl.acm.org/doi/10.1145/2687357.2687368) — 11 languages × 5 patterns (ping-pong, counting, thread ring, fork-join, skynet). Both the benchmark runner and the visualization server are written in Aether, dogfooding the stdlib.
```bash
make benchmark # Builds runner, runs all 55 benchmarks, opens UI at http://localhost:8080
```
See [Performance Benchmarks](docs/performance-benchmarks.md) for methodology and [benchmarks/cross-language/](benchmarks/cross-language/) for source.
## Quick Start
### Install
**Linux / macOS — one-line install:**
```bash
git clone https://github.com/nicolasmd87/aether.git
cd aether
./install.sh
```
Installs to `~/.aether` and adds `ae` to your PATH. Restart your terminal or run `source ~/.bashrc`, `~/.zshrc`, or `~/.bash_profile`.
**Windows — download and run:**
1. Download `aether-*-windows-x86_64.zip` from [Releases](https://github.com/nicolasmd87/aether/releases)
2. Extract to any folder (e.g. `C:\aether`)
3. Add `C:\aether\bin` to your PATH
4. **Restart your terminal** (so PATH takes effect)
5. Run `ae init hello && cd hello && ae run`
GCC is downloaded automatically the first time you run a program (~80 MB, one-time) — no MSYS2 or manual toolchain setup required.
**All platforms — manage versions with `ae version`:**
```bash
ae version list # see all available releases
ae version install v0.25.0 # download and install a specific version
ae version use v0.25.0 # switch to that version
```
### Your First Program
```bash
# Create a new project
ae init hello
cd hello
ae run
```
Or run a single file directly:
```bash
ae run examples/basics/hello.ae
```
### Editor Setup (Optional)
Install syntax highlighting for a better coding experience:
**VS Code / Cursor:**
```bash
cd editor/vscode
./install.sh
```
This provides:
- Syntax highlighting with TextMate grammar
- Custom "Aether Erlang" dark theme
- `.ae` file icons
### Development Build (without installing)
If you prefer to build without installing:
```bash
make ae
./build/ae version
./build/ae run examples/basics/hello.ae
```
### The `ae` Command
`ae` is the single entry point for everything — like `go` or `cargo`:
```bash
ae init # Create a new project
ae run [file.ae] # Compile and run (file or project)
ae build [file.ae] # Compile to executable
ae check [file.ae] # Type-check without compiling (skips codegen + link)
ae test [file|dir] # Discover and run tests
ae examples [dir] # Build all example programs
ae add # Add a dependency (any git host)
ae repl # Start interactive REPL
ae cache # Show build cache info
ae cache clear # Clear the build cache
ae version # Show current version
ae version list # List all available releases
ae version install # Install a specific version
ae version use # Switch to an installed version
ae help # Show all commands
```
In a project directory (with `aether.toml`), `ae run` and `ae build` compile `src/main.ae` as the program entry point. You can also pass `.` as the directory: `ae run .` or `ae build .`.
**Using Make (alternative):**
```bash
make compiler # Build compiler only
make ae # Build ae CLI tool
make test # Run runtime C test suite (166 tests)
make test-ae # Run .ae source tests (95 tests)
make test-all # Run all tests
make examples # Build all examples
make -j8 # Parallel build
make help # Show all targets
```
### Building on Windows
The Aether build is GNU-make based. Use one of the two paths below — `nmake` from a Visual Studio Developer Prompt **will not work** (the Makefile uses GNU-only syntax that NMAKE can't parse).
**Just running Aether? Skip this section** and use the [release binary](https://github.com/nicolasmd87/aether/releases) — no MSYS2 setup required.
**Building from source — recommended (MSYS2 / MinGW-w64):**
1. Install [MSYS2](https://www.msys2.org/) and open the **MSYS2 MinGW 64-bit** shell (not the bare MSYS shell).
2. Install the toolchain:
```bash
pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-make \
mingw-w64-x86_64-openssl mingw-w64-x86_64-zlib \
mingw-w64-x86_64-ca-certificates pkg-config make bc
```
3. Clone and build:
```bash
git clone https://github.com/nicolasmd87/aether.git
cd aether
make ci # full suite: compiler, ae, stdlib, REPL, C tests, .ae tests, examples
```
For HTTPS to verify certs, the `mingw-w64-x86_64-ca-certificates` package above provides the bundle at `/mingw64/etc/ssl/certs/ca-bundle.crt`. The runtime auto-detects it; if your install is in a non-standard location, export `SSL_CERT_FILE` to the bundle's Windows path.
**Native MSVC (cl.exe / nmake):** not currently supported as a full build path — tracker [#99](https://github.com/nicolasmd87/aether/issues/99). The MSVC matrix job in CI verifies our public headers parse under `cl.exe` so a future native MSVC port stays feasible, but `make` (the build system itself) requires GNU make. The MSYS2 MinGW build above is the supported source-build path for Windows today.
## Project Structure
```
aether/
├── compiler/ # Aether compiler (lexer, parser, codegen)
│ ├── parser/ # Lexer, parser, tokens
│ ├── analysis/ # Type checker, type inference
│ ├── codegen/ # C code generation, optimizer
│ └── aetherc.c # Compiler entry point
├── runtime/ # Runtime system
│ ├── actors/ # Actor implementation and lock-free mailboxes
│ ├── config/ # Platform detection, optimization tiers, runtime config
│ ├── memory/ # Arena allocators, memory pools, batch allocation
│ ├── scheduler/ # Multi-core scheduler + cooperative single-threaded backend
│ └── utils/ # CPU detection, SIMD, tracing, thread portability
├── std/ # Standard library
│ ├── string/ # String operations
│ ├── file/ # File operations (open, read, write, delete)
│ ├── dir/ # Directory operations (create, delete, list)
│ ├── path/ # Path utilities (join, basename, dirname)
│ ├── fs/ # Combined file/dir/path module
│ ├── collections/ # List, HashMap, Vector, Set, PQueue
│ ├── list/ # Dynamic array (ArrayList)
│ ├── map/ # Hash map
│ ├── intarr/ # Fixed-size packed int buffer
│ ├── json/ # JSON parser and builder
│ ├── http/ # HTTP client + server (TLS, keep-alive, h2, WS, SSE, metrics)
│ │ ├── client/ # Builder client (request builder, full response, JSON sugar)
│ │ ├── middleware/ # CORS, basic/bearer/session auth, rate-limit, real-IP, vhost, gzip, static, rewrite, error pages
│ │ ├── proxy/ # Reverse proxy: upstream pool, LB (RR/LC/iphash/WRR), health, cache, circuit breaker
│ │ ├── server/h2/ # HTTP/2 framing via libnghttp2 (h2 + h2c + ALPN + GOAWAY + concurrent dispatch)
│ │ └── server/vcr/ # Servirtium-format record/replay for HTTP tests
│ ├── tcp/ # TCP client and server
│ ├── net/ # Combined TCP/HTTP networking module
│ ├── cryptography/ # SHA-1, SHA-256
│ ├── zlib/ # One-shot deflate/inflate
│ ├── math/ # Math functions and random numbers
│ ├── io/ # Console I/O, environment variables
│ ├── os/ # Shell execution, command capture, env vars, ISO-8601 time
│ └── log/ # Structured logging
├── contrib/ # Optional / opinionated modules outside std/
│ ├── sqlite/ # SQLite bindings (open, prepare, bind, step, column, ...)
│ ├── tinyweb/ # Server-side request/response DSL
│ ├── host// # Embed Lua, Python, Perl, Ruby, Tcl, JS in-process
│ └── climate_http_tests/ # Servirtium climate-API record/replay fixtures
├── tools/ # Developer tools
│ ├── ae.c # Unified CLI tool (ae command)
│ └── apkg/ # Project tooling, TOML parser
├── tests/ # Test suite (runtime, syntax, integration, regression)
├── examples/ # Example programs (.ae files)
│ ├── basics/ # Hello world, variables, arrays, etc.
│ ├── actors/ # Actor patterns (ping-pong, pipeline, etc.)
│ └── applications/ # Complete applications
├── docs/ # Documentation
└── docker/ # Docker (CI, dev, WASM, embedded)
```
## Language Example
```aether
// Counter actor with message handling
message Increment {}
message Decrement {}
message Reset {}
actor Counter {
state count = 0
receive {
Increment() -> {
count = count + 1
}
Decrement() -> {
count = count - 1
}
Reset() -> {
count = 0
}
}
}
main() {
// Spawn counter actor
counter = spawn(Counter())
// Send messages
counter ! Increment {}
counter ! Increment {}
counter ! Decrement {}
counter ! Reset {}
counter ! Increment {}
// Wait for all messages to be processed
wait_for_idle()
println("Final count: ${counter.count}")
}
```
## Closures and Builder DSL
Aether closures take three shapes after a function call. They look similar but have different semantics — picking the right one is the language's main lever for separating DSL structure from runtime behaviour.
| Mode | Syntax | Semantics |
|------|--------|-----------|
| **Immediate** | `func() { block }` | Runs inline at the call site — used for DSL structure |
| **Closure** | `func() \|x\| { block }` | Real closure with explicit params, hoisted to a C function |
| **Callback** | `func() callback { block }` | Real closure that captures enclosing scope — no params needed |
```aether
// Immediate — declarative structure, runs during construction
panel("Settings") {
button("OK")
button("Cancel")
}
// Closure — explicit params, deferred invocation
apply_twice(x: int, f: fn) { return call(f, call(f, x)) }
doubler = |x: int| -> x * 2
println(apply_twice(3, doubler)) // 12
// Callback — captures from scope, runs when invoked
counter = ref(0)
btn("increment") callback { ref_set(counter, ref_get(counter) + 1) }
btn("decrement") callback { ref_set(counter, ref_get(counter) - 1) }
```
The compiler distinguishes them at parse time, which is what makes the sandboxing story (above) work: `hide`/`seal except` checks happen against the hoisted form of `closure` and `callback` blocks, so a `seal except req, res` on a callback body genuinely prevents the body from reaching outer scope. Immediate blocks inherit the caller's lexical scope by design — they're structure, not callbacks.
Inspired by Smalltalk blocks, Ruby's blocks/procs, Groovy closures, and Kotlin/SwiftUI's trailing-block DSLs. See [Closures and Builder DSL](docs/closures-and-builder-dsl.md) for the builder-context mechanism, ref cells, and full DSL pattern.
## Config IS Code
**Don't ship a YAML loader.** If your Aether library has a "start the thing" surface — HTTP server, daemon, agent, scheduler, test rig — expose it as a closure-DSL block and let the operator's "config" be a `.ae` file they run with `ae run`. The pattern collapses YAML → templating → second-language-DSL (HCL, Helm) → embedded-scripting all into one thing: real Aether, type-checked, sandboxable, with the full stdlib available when the operator needs it.
```aether
import avnserver
main() {
avnserver.serve {
host("127.0.0.1")
port(9990)
superuser_token(env("SUPER_TOKEN")) // computed at config time
repo("alpha", "/srv/alpha")
repo("beta", "/srv/beta")
}
}
```
Same file is config, validation, conditional logic, and the entry point. No second parser, no second type system, no template language. Sandboxing (`--emit=lib --with=...`, `hide`, `seal except`) keeps it safe to accept untrusted configs as the embedded-DSL case demands. See [Config IS Code](docs/config-is-code.md) for the full progression (YAML → HCL → Pulumi → here) and library-author recipe.
## Runtime Configuration
When embedding the Aether runtime in a C application, configure optimizations at startup:
```c
#include "runtime/aether_runtime.h"
int main() {
// Auto-detect CPU features and enable optimizations
aether_runtime_init(4, AETHER_FLAG_AUTO_DETECT);
// Or manually configure
aether_runtime_init(4,
AETHER_FLAG_LOCKFREE_MAILBOX |
AETHER_FLAG_ENABLE_SIMD |
AETHER_FLAG_ENABLE_MWAIT
);
// Your actor system runs here
return 0;
}
```
Available flags:
- `AETHER_FLAG_AUTO_DETECT` - Detect CPU features and enable optimizations
- `AETHER_FLAG_LOCKFREE_MAILBOX` - Use lock-free SPSC mailboxes
- `AETHER_FLAG_ENABLE_SIMD` - AVX2 vectorization for batch operations
- `AETHER_FLAG_ENABLE_MWAIT` - MWAIT-based idle (x86 only)
- `AETHER_FLAG_VERBOSE` - Print runtime configuration
## Optimization Tiers
The runtime employs a tiered optimization strategy:
**TIER 0 - Platform Capabilities (compile-time):**
- `AETHER_HAS_THREADS` — pthreads/Win32 threads (auto-detected; disabled on WASM/embedded)
- `AETHER_HAS_ATOMICS` — C11 stdatomic (fallback: volatile for single-threaded)
- `AETHER_HAS_FILESYSTEM` / `AETHER_HAS_NETWORKING` — stdlib feature gates
- `AETHER_HAS_SIMD` / `AETHER_HAS_NUMA` / `AETHER_HAS_AFFINITY` — hardware feature gates
- Override any flag with `-DAETHER_NO_` (e.g. `-DAETHER_NO_THREADING`)
**TIER 1 - Always Enabled:**
- Actor pooling (reduces allocation overhead)
- Direct send for same-core actors (bypasses queues)
- Adaptive batching (adjusts batch size dynamically)
- Message coalescing (combines small messages)
- Thread-local message pools
**TIER 2 - Auto-Detected:**
- SIMD batch processing (requires AVX2/NEON)
- MWAIT idle (requires x86 MONITOR/MWAIT)
- CPU core pinning (OS-dependent)
**TIER 3 - Opt-In:**
- Lock-free mailbox (better under contention)
- Message deduplication (prevents duplicate processing)
## Documentation
- [Getting Started Guide](docs/getting-started.md) - Installation and first steps
- [Language Tutorial](docs/tutorial.md) - Learn Aether syntax and concepts
- [Language Reference](docs/language-reference.md) - Complete language specification
- [Standard Library Reference](docs/stdlib-reference.md) - Full stdlib surface
- [HTTP Server](docs/http-server.md) - TLS, HTTP/2, middleware, health probes, metrics, graceful shutdown
- [Reverse Proxy](docs/http-reverse-proxy.md) - `std.http.proxy` upstream pool, load balancing, health, cache, circuit breaker
- [HTTP Record/Replay (VCR)](docs/http-vcr.md) - `std.http.server.vcr` Servirtium-format record/replay for HTTP tests
- [Install Layout](docs/install-layout.md) - What ships in `~/.aether`, MANIFEST format, downstream-link contract
- [C Interoperability](docs/c-interop.md) - Using C libraries and the `extern` keyword
- [Architecture Overview](docs/architecture.md) - Runtime and compiler design
- [Memory Management](docs/memory-management.md) - defer-first manual model, arena allocators
- [Structured Concurrency](docs/structured-concurrency.md) - Proposal: supervision trees + capability-scoped spawn/send (not yet shipped)
- [Runtime Optimizations](docs/runtime-optimizations.md) - Performance techniques
- [Cross-Language Benchmarks](benchmarks/cross-language/README.md) - Comparative performance analysis
- [Docker Setup](docker/README.md) - Container development environment
## Development
### Running Tests
```bash
# Runtime C test suite
make test
# Aether source tests
make test-ae
# All tests
make test-all
# Build all examples
make examples
```
### Testing
```bash
# Full CI suite (8 steps, -Werror) — runs on your current platform
make ci
# Unit tests only (215 tests)
make test
# Integration + regression .ae tests (463 tests)
make test-ae
# Build all examples (89 programs)
make examples
# Full CI + Valgrind + ASan in Docker (Linux)
make docker-ci
```
### Cross-Platform Testing
**CI runs automatically on:** Linux (GCC + Clang), macOS (ARM64 + x86_64), Windows (MinGW/MSYS2)
```bash
# Cooperative scheduler (no Docker needed)
make ci-coop
# Windows cross-compile syntax check (requires mingw-w64 or Docker)
make ci-windows # needs: brew install mingw-w64
make docker-ci-windows # or use Docker
# WebAssembly (requires Docker with Emscripten)
make docker-ci-wasm
# ARM embedded syntax check (requires Docker with arm-none-eabi-gcc)
make docker-ci-embedded
# All portability checks (coop + WASM + embedded)
make ci-portability
```
**`make ci` tests your current OS only.** No OS can locally test another OS natively — macOS cannot be virtualized on Linux/Windows, Windows build+run requires MSYS2. GitHub Actions CI automatically tests all 5 platform targets (Linux GCC, Linux Clang, macOS ARM64, macOS x86_64, Windows MinGW) on every PR. Docker targets (`docker-ci-windows`, `docker-ci-wasm`, `docker-ci-embedded`) provide cross-compilation syntax checking from any host.
See [CONTRIBUTING.md](CONTRIBUTING.md) for the full pre-PR checklist.
### Running Benchmarks
```bash
# Run cross-language benchmark suite with interactive UI
make benchmark
# Open http://localhost:8080 to view results
```
The benchmark runner is written in Aether (`run_benchmarks.ae`), dogfooding the stdlib. It compiles and runs all 11 languages, parses output, and writes JSON results.
## Sibling Projects
The Aether ecosystem includes downstream consumers that live in their
own repos and release independently:
- **[aether-ui](https://github.com/aether-lang-org/aether-ui)** —
Cross-platform widget toolkit (GTK4 on Linux, AppKit on macOS, Win32
on Windows) with an AetherUIDriver HTTP test server for headless
integration testing. Previously shipped as `contrib/aether_ui/` in
this repo; spun out so it can iterate on its own cadence.
- **[aeb](https://github.com/aether-lang-org/aeb)** — Build system for
multi-package Aether projects. Reads `share/aether/MANIFEST` (the
authoritative list of link-suitable runtime/stdlib `.c` files) and
dispatches per-package builds with cache reuse and incremental
relinking.
If you're adding to Aether and the change isn't a runtime / compiler /
stdlib concern, the right home may be one of the siblings above. Both
repos consume Aether the same way external users do — `import` against
the installed `share/aether/` tree plus `$(ae cflags)` for the link
line — so they're useful references for downstream integration shapes.
## Status
Aether is under active development. The compiler, runtime, and standard library are functional and tested.
## Contributing
Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
**Areas of interest:**
- Runtime optimizations
- Standard library expansion
- Documentation and examples
## Supporting Aether
Aether is free and open source, built and maintained in personal time. CI runners, cross-platform testing infrastructure, and future project hosting cost real money.
If Aether is useful to you, consider [sponsoring the project on GitHub](https://github.com/sponsors/nicolasmd87). Every contribution goes directly into development and infrastructure.
[](https://github.com/sponsors/nicolasmd87)
## Acknowledgments
Aether draws inspiration from:
- **Erlang/OTP** — Actor model, message passing semantics
- **Go** — Pragmatic tooling, simple concurrency primitives
- **Rust** — Systems programming practices, zero-cost abstractions
- **Pony** — Actor-based type safety concepts and object-capability model
- **Smalltalk / Ruby / Groovy** — Block / closure ergonomics: trailing-block builders, `do |x| … end` syntax, and DSL-shaped APIs where the closure is the configuration
## License
MIT License. See [LICENSE](LICENSE) for details.