docs

Appearance

Get started in 5 minutes ​

Two steps. The first runs in your browser and needs nothing installed. The second puts the toolchain on a Linux machine; most of its time is spent compiling.

1. In your browser (1 minute) ​

Open this program in the playground and press Run:

nim
import std/syncio
echo "hello from aoughwl"
▶ Open hello world in the playground

What happened: aowlparser parsed the source, aowlsem type-checked it, and an interpreter ran the result, all inside your browser tab. Nothing was sent to a server.

Try a program with a type and a procedure:

nim
import std/syncio

type
  Shape = object
    name: string
    sides: int

proc describe(s: Shape): string =
  s.name & " has " & $s.sides & " sides"

let shapes = @[Shape(name: "triangle", sides: 3), Shape(name: "square", sides: 4)]
for s in shapes:
  echo describe(s)
▶ Open shapes in the playground

Things to try while you are there:

  • Change the engine in the toolbar. Native JS compiles your program to JavaScript and lets the browser's JIT run it. Bytecode VM and tree-walk interpret it exactly.
  • Make a mistake on purpose, such as echo describe(3). The error appears as you type, from the same type checker the command-line toolchain uses.
  • Share it. The URL carries your program, so a link reproduces it.

New to Nim?

Nimony is the next-generation compiler for the Nim language: Python-like syntax, static types, compiled to C. If you know Python, most of the examples above read as you expect. Two differences that catch people early: echo needs import std/syncio, and a variable may not share its name with the module it is in.

2. On your machine (about 3 minutes, mostly compiling) ​

What you need ​

SystemLinux x86-64 with glibc 2.34 or newer (Ubuntu 22.04+, Debian 12+, Fedora 35+)
Toolsgit, curl, a C compiler (gcc)
Nim 2used once, to build the Nimony compiler from source
Node.jsruns the C backend's linker driver

On macOS and Windows, use the playground for now, or WSL on Windows.

Install ​

sh
# 1. the toolchain manager
curl -fsSL https://raw.githubusercontent.com/aoughwl/aowlup/main/install.sh | sh
export PATH="$HOME/.aowl/bin:$PATH"

# 2. build the compiler and the free components (2 to 3 minutes)
aowlup setup --yes

# 3. the driver
aowlup install aowlmony

aowlup setup clones each component into its own directory in your home folder (~/nimony, ~/aowlc, ~/aowlparser, …) and builds it. A few components have private source. Setup reports those as clone failed and carries on, and nothing on this page needs them.

Add the export PATH=… line to your shell profile to keep it.

Run a program ​

sh
cat > hello.nim <<'EOF'
import std/syncio
echo "hello from aoughwl"
EOF

aowlmony run hello.nim
hello from aoughwl
  ✓ run · compiled 1.8s · ran 150ms

run compiled hello.nim through the pipeline to C, linked a native binary and ran it. To keep the binary:

sh
aowlmony build hello.nim -o hello
./hello

Start a project ​

sh
aowlmony new myapp
cd myapp

This writes a mony.toml and src/myapp.nim. Inside the project, plain aowlmony run builds and runs it (the entry point comes from mony.toml), and aowlmony watch src/myapp.nim reruns it on every save.

3. What to read next ​

If you want toRead
see what each stage producedaowlmony nif hello.nim prints the paths of the parsed, typed and lowered files; AIF explains the format
know why something rebuiltaowlmony why hello.nim
check your setupaowlup doctor lists every pipeline slot and what fills it
swap our stages for Nimony'saowlup profile use nimony, see aowlup
set up an editoraowllsp, or aowlup vscode . --yes
know what is missingParity

If something goes wrong ​

  • aowlup doctor shows which slot is missing or unbuilt.
  • aowlmony says a component is not installed when a command needs one that is not there. The interpreter and the TypeScript, Python and WebAssembly backends are part of the paid bundle, installed with aowlup login YOUR-KEY.
  • Anything else: ask on Discord. Reports of a step on this page that did not work for you are the most useful thing you can send.