Getting Started

Eta — Building from Source

Prerequisites

One-Script Build

Both scripts configure, build, install, package the VS Code extension, and create a distributable archive. They take an optional install directory argument.

Linux / macOS / WSL

chmod +x scripts/build-release.sh
./scripts/build-release.sh ./dist/eta-v0.0.2-linux-x86_64

Produces dist/eta-v0.0.2-linux-x86_64/ and dist/eta-v0.0.2-linux-x86_64.tar.gz.

Additional flags:

# Explicit version tag
./scripts/build-release.sh -v v0.0.2

# Enable libtorch bindings (auto-downloads libtorch)
./scripts/build-release.sh -t
./scripts/build-release.sh -t --torch-backend cu126   # CUDA 12.6

Windows (PowerShell)

.\scripts\build-release.ps1 .\dist\eta-v0.0.2-win-x64

Produces dist\eta-v0.0.2-win-x64\ and dist\eta-v0.0.2-win-x64.zip.

Additional flags:

# Explicit version + vcpkg for Boost
.\scripts\build-release.ps1 -Version v0.0.2 -VcpkgRoot C:\src\vcpkg

# Enable libtorch bindings
.\scripts\build-release.ps1 -EnableTorch
.\scripts\build-release.ps1 -EnableTorch -TorchBackend cu126

Manual Build Steps

If you prefer not to use the scripts:

Linux / WSL

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)
cmake --install build --prefix dist/eta-v0.0.2-linux-x86_64

Windows (MSVC)

cmake -B build
cmake --build build --config Release
cmake --install build --prefix dist\eta-v0.0.2-win-x64 --config Release

With CUDA

By default the build downloads the CPU-only libtorch archive automatically. To select a CUDA variant:

cmake -B build -DCMAKE_BUILD_TYPE=Release -DETA_TORCH_BACKEND=cu126
cmake --build build -j$(nproc)

The FetchLibtorch.cmake module downloads the correct libtorch archive for your platform and caches it in the build directory. Supported backends: cpu (default), cu126, cu128, cu130.

Bundle Layout

After build or extraction:

eta-v0.0.2-<platform>/
  bin/
    etac(.exe)              # Ahead-of-time bytecode compiler
    etai(.exe)              # File interpreter (also runs .etac files)
    eta_repl(.exe)          # Interactive REPL
    eta_lsp(.exe)           # Language Server (JSON-RPC over stdio)
    eta_dap(.exe)           # Debug Adapter (DAP over stdio, used by VS Code)
    eta_jupyter(.exe)       # Jupyter kernel executable (`--install` writes kernelspec)
    resources/
      logo-32x32.png        # Kernel logo copied by `eta_jupyter --install`
      logo-64x64.png
  stdlib/
    std/
      prelude.eta           # Auto-loaded standard library module (std.prelude)
      core.eta  math.eta  io.eta  collections.eta  test.eta
      logic.eta  clp.eta  clpb.eta  clpr.eta  causal.eta
      db.eta  fact_table.eta  freeze.eta  net.eta  stats.eta
      supervisor.eta  torch.eta
  cookbook/
    hello.eta  basics.eta  functions.eta  higher-order.eta  ...
  editors/
    eta-lang-<version>.vsix # VS Code extension
  install.sh / install.cmd  # Post-extract installer

The binaries automatically locate stdlib/ relative to themselves (<exe>/../stdlib/), so no environment variables are needed when using the installed layout.

To register the bundled Jupyter kernel in your current user environment:

eta_jupyter --install --user

Development: Manual stdlib Path

When running from a build directory (not the install tree):

# Via CLI flag
./build/eta/tools/interpreter/etai --path ./stdlib cookbook/basics/hello.eta

# Or via environment variable
export ETA_MODULE_PATH=./stdlib
./build/eta/tools/interpreter/etai cookbook/basics/hello.eta

Running Tests

C++ Unit Tests

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
ctest --test-dir build

Torch Test Suite

Ten standalone test files in cookbook/tests/torch/ exercise every std.torch primitive end-to-end using the std.test framework:

# Run all torch tests (Linux / macOS)
for f in cookbook/tests/torch/*.eta; do echo "── $f"; etai "$f"; done

# Run all torch tests (Windows PowerShell)
Get-ChildItem cookbook\tests\torch\*.eta | ForEach-Object { Write-Host "── $_"; etai $_ }

# Run a single test file
etai cookbook/tests/torch/tensor_creation.eta

C++ Unit Tests (Torch)

The C++ tests in eta/qa/test/src/torch_tests.cpp mirror the Eta tests at the primitive level, additionally verifying heap lifecycle, GC behaviour, error paths, and builtin registration:

cmake -B build
cmake --build build
ctest --test-dir build -R torch

The example_runner_tests suite also automatically discovers and runs all .eta files (including tests/torch/) when built with torch support.

QP Benchmark and Rollout Gate

Stage 6 QP rollout benchmarking uses eta_qp_bench plus wrapper scripts.

Windows (PowerShell)

cmake --build out\msvc-release --target eta_qp_bench
.\scripts\qp-benchmark.ps1 -BuildDir C:\Users\lewis\develop\eta\out\msvc-release
.\scripts\qp-benchmark.ps1 -BuildDir C:\Users\lewis\develop\eta\out\msvc-release -Gate

Linux / macOS

cmake --build out/wsl-clang-release --target eta_qp_bench -j"$(nproc)"
BUILD_DIR=./out/wsl-clang-release ./scripts/qp-benchmark.sh
BUILD_DIR=./out/wsl-clang-release GATE=1 ./scripts/qp-benchmark.sh

-Gate / GATE=1 enables rollout checks for quality parity and stability.

GitHub Actions CI

The repository includes .github/workflows/release.yml which:

1. Builds release bundles for Linux x86_64 and Windows x64
2. Uploads them as workflow artifacts (downloadable from the Actions tab)
3. On tag push (v*), creates a GitHub Release with both archives

To trigger a release:

git tag v0.0.2
git push origin v0.0.2

To test the workflow without tagging, use Actions → Release Bundle → Run workflow (manual dispatch).