aowlup — the toolchain manager

▶️ Try aoughwl/aowlup live in the Playground — clones the repo into the in-browser IDE, no install.

aowlup is rustup for the aowl/nimony stack. It installs, versions, and selects the components of the compilation pipeline; the driver, aowlmony, compiles your code against whatever aowlup has selected. One provisions the toolchain, the other runs it.

aowlup  ── manages the toolchain ──►  ~/.aowl/registry.json  ◄── reads ──  aowlmony
                                       (single source of truth)

• Three axes
  • Variants — swap any implementation
  • Profiles — flip the whole stack at once
  • Versions — a nimony version manager, too
• Fresh machine — aowlup setup
• Editor — aowlup vscode
• The registry — one source of truth

---

Three axes

Variants — swap any implementation

Every pipeline slot has interchangeable implementations, and aowlup records which one is selected:

slot	variants
parser	aowlparser (ours) · nifler (nimony)
sem	aowlsem (ours) · nimsem (nimony)
hexer	aowlhexer (ours) · hexer (nimony)

Backends (native/interp/vm/js/ts/py) and tooling (lsp/suggest/fmt/lens) live in the same catalog, so new targets are data, not new code.

Profiles — flip the whole stack at once

profile	parser	sem	hexer
aowl	aowlparser	aowlsem	aowlhexer	all ours
nimony	nifler	nimsem	hexer	all nimony
hybrid	aowlparser	nimsem	aowlhexer	the driver default

aowlup profile use nimony     # flip all three passes
aowlup use sem aowlsem        # override one slot on top of the profile
aowlup +nimony doctor         # one-shot ephemeral profile (rustup +toolchain style)

Versions — a nimony version manager, too

Every component is a git checkout. aowlup status derives each repo's GitHub branch and asks whether it is behind — behind / ahead / diverged / up-to-date. Because the nimony variants (nifler/nimsem/hexer) all resolve to your nimony checkout, status doubles as a nimony version manager, tracking master/devel against upstream nim-lang/nimony.

aowlup status                 # git rev + GitHub update check per component
aowlup update aowlc --yes     # git pull (ff-only; dry-run without --yes)
aowlup rebuild aowlsem --yes  # rebuild from source

Fresh machine — aowlup setup

There is no prebuilt nimony binary, so setup is the build. aowlup setup clones the components into your home directory (~/nimony, ~/aowlc, ~/aowlparser, …) and builds them, nimony first: it clones the aoughwl nimony fork, which the components are pinned to, and bootstraps it with nim c -r src/hastur build all. It then builds each component with that compiler, writes the ~/.aowl/bin shims, and registers everything. Dry-run by default; --yes executes.

aowlup setup            # show the plan
aowlup setup --yes      # clone + build everything
aowlup install aowlmony # the driver, from its public release

Measured 2026-10-08 on an empty home directory with no git credentials, starting from install.sh: setup exits 0 in about 2 minutes, and aowlmony run hello.nim prints hello. The full walkthrough is Get started in 5 minutes.

What a machine without credentials does not get:

• private components (aowlsem, aowli, aowljs, aowlts, aowlpy, aoughwlup) show as private — skipped in the plan (since v0.1.0-alpha.5, checked with git ls-remote before cloning); the driver uses Nimony's own pass for each missing slot.
• the paid bundle (the interpreter, its debugger, the TS / Python / JS-WASM backends) comes from aowlup login YOUR-KEY, not from setup.
• aowlhexer currently does not build against the fork's published master, so lowering falls back to Nimony's hexer (being fixed).

You need Linux x86-64 with glibc 2.34+, git, curl, gcc, Nim 2 (for the one-time bootstrap) and Node.js (the C backend's linker driver).

Editor — aowlup vscode

The LSP is just another registry component, so the editor never hardcodes paths. aowlup vscode writes .vscode/settings.json for the nimony VS Code extension (nimony.nimony), pointing nimony.serverPath at the resolved aowllsp and nimony.nimonyPath at the compiler — so the editor tracks whichever profile is active.

aowlup vscode           # preview the settings
aowlup vscode . --yes   # write .vscode/settings.json here

The registry — one source of truth

~/.aowl is the data home: registry.json (profile + per-slot overrides + linked repos) and backends/<slot>/backend.json (the resolved invocation contract for each component). Resolution order for any slot:

AOWL_<SLOT> env  →  slot override  →  active profile's variant  →  dev-fallback probe  →  error

aowlup config [--lsp] emits the resolved payload as JSON — this is exactly what aowlmony reads to run, and what aowlup vscode reads to wire the editor. No component path is ever named on the command line.