Static copy

Copied from docs/install.md in https://github.com/poppy-team/ori-lang (MIT). Pinned to revision 42e1817227fbc96e8e4a4a85fac78b3fec0a0e0f, blob 642c5537a76a2c7e2e3d11d3af2d13ed49092126. The source repository remains canonical; this copy is refreshed through a sync pull request, not live.

Installing Ori

Audience: end users who want to write Ori programs without cloning this repository and without a Rust toolchain.
Portuguese: install.pt-BR.md
Surface: S3 + inference B · latest release v0.3.8 · M1 complete

System prerequisites

Ori uses a packaged rust-lld when available and otherwise discovers the OS native linker for AOT (ori compile, ori test). The package does not require rustc or cargo. For JIT (ori run), no linker is required — only the packaged runtime next to the ori binary (runtime/<triple>/).

Windows (10/11)

Fallback requirement: Visual Studio Build Tools or Visual Studio Community with the "Desktop development with C++" workload. Release packages normally bundle rust-lld; install this only when ori doctor reports the system-linker fallback.

winget install Microsoft.VisualStudio.2022.BuildTools

Or the installer at visualstudio.microsoft.com/downloads.

Why: AOT falls back to MSVC link.exe when the packaged rust-lld is not available.

Not required: Rust (rustc, cargo). A packaged rust-lld, when present, is an implementation detail of the release package.

Linux

Fallback requirement: build-essential (or gcc + ld + libc headers). Release packages normally bundle rust-lld; install this only when ori doctor reports the system-linker fallback.

# Debian / Ubuntu
sudo apt update && sudo apt install build-essential

# Fedora / RHEL
sudo dnf install gcc gcc-c++ make glibc-devel

# Arch
sudo pacman -S base-devel

Not required: Rust. The packaged rust-lld is not the Rust compiler.

macOS

Fallback requirement: Xcode Command Line Tools. Release packages normally bundle rust-lld; install these tools only when ori doctor reports the system-linker fallback.

xcode-select --install

Not required: full Xcode, Rust, or rust-lld.

---

Download and install

Release package (recommended)

Shipping policy (2026-07-14): official release packages for Linux, Windows (MSVC), and macOS (Apple Silicon + Intel) via GitHub Actions (.github/workflows/release.yml). Assets appear on GitHub Releases after a v* tag.

1. Download from GitHub Releases. Example names for tag vX.Y.Z:

   Platform	Asset
   Linux x86_64	ori-vX.Y.Z-x86_64-unknown-linux-gnu.tar.gz
   Linux deb	ori_X.Y.Z_amd64.deb
   Windows MSVC x86_64	ori-vX.Y.Z-x86_64-pc-windows-msvc.zip
   macOS Apple Silicon	ori-vX.Y.Z-aarch64-apple-darwin.tar.gz
   macOS Intel	ori-vX.Y.Z-x86_64-apple-darwin.tar.gz

   Releases produced by the current workflow also contain SHA256SUMS, ori-vX.Y.Z.spdx.json, and GitHub build-provenance attestations. Verify the downloaded bytes from the directory containing the assets:

   sha256sum --check SHA256SUMS
   gh attestation verify ori-vX.Y.Z-x86_64-unknown-linux-gnu.tar.gz --repo raillen/ori-lang

Option A — Windows one-liner (recommended, Scoop-style)

# Optional once: allow local scripts (CurrentUser)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Install latest Ori + add User PATH
irm https://raw.githubusercontent.com/raillen/ori-lang/main/tools/windows/get.ps1 | iex

Pin version / reinstall:

$env:ORI_VERSION = "0.3.8"
$env:ORI_FORCE = "1"
irm https://raw.githubusercontent.com/raillen/ori-lang/main/tools/windows/get.ps1 | iex

Default install location: %LOCALAPPDATA%\Programs\Ori
(all-users: $env:ORI_SYSTEM = "1" as Administrator).

Then open a new terminal:

ori --version
ori doctor

Uninstall:

irm https://raw.githubusercontent.com/raillen/ori-lang/main/tools/windows/Uninstall-Ori.ps1 | iex
# or:
pwsh -File "$env:LOCALAPPDATA\Programs\Ori\uninstall.ps1"

Option A2 — Windows zip (offline / manual)

1. Download ori-vX.Y.Z-x86_64-pc-windows-msvc.zip and extract it.
2. Run install.cmd or pwsh -ExecutionPolicy Bypass -File .\install.ps1.

Full details: tools/windows/README.md.

Option B — tarball / zip (manual PATH)

2. Extract to a directory (e.g. ~/ori or C:\ori).

3. Expected layout:

   Path	Role
   ori / ori.exe	CLI
   ori-lsp / ori-lsp.exe	LSP server
   stdlib/	Layer 2/3 .orl modules
   runtime/<triple>/	staticlib + cdylib + runtime-link.json
   install.ps1 / install.cmd	Windows only — installer + PATH

4. Put the directory on your PATH (on Windows prefer Option A).

Option C — .deb (Debian / Ubuntu)

sudo dpkg -i ori_0.3.8_amd64.deb
# installs /usr/lib/ori + /usr/bin/ori + /usr/bin/ori-lsp
# AOT fallback only: sudo apt install build-essential

Verify

ori --version
ori doctor

Healthy install: stdlib found, AOT + JIT runtime present, target triple detected, linker strategy SystemLinker (or documented fallback), JIT available for ori run.

---

First program

hello.orl (S3):

module app.hello

import ori.io = io

main()
    io.println("Hello, Ori!")
end

ori run hello.orl                 # JIT — no linker
ori compile hello.orl --out hello # AOT — needs system linker
./hello

Recommended project skeleton:

ori new my_app
cd my_app
ori run main.orl

Editor extensions (VS Code / Zed)

From the same GitHub Release as the language package:

Editor	Asset	Install
VS Code / Cursor	ori-vscode-orl-0.3.5.vsix (release) or vscode-orl-0.3.5.vsix (local)	code --install-extension <file>.vsix
Zed	ori-zed-0.3.5.zip (current dev extension artifact)	extract → zed: install dev extension

Requires ori-lsp on PATH (from the language install above).
Details: extensions/README.md.

Next: Language tour · First project · Examples · Editors: VS Code · Zed.

---

Updating

Package installs (tar.gz / Windows zip) can update themselves:

$ ori update --check   # report whether a newer release exists
$ ori update           # download, verify (sha256), and swap in place

ori update refuses system-package installs (use the new .deb instead) and development builds (update via git pull + cargo build). The archive checksum comes from the GitHub release manifest; a mismatch aborts before anything is touched.

---

Environment overrides

Usually none are needed.

Variable	Purpose
ORI_USE_SYSTEM_LINKER=1	Force OS linker
ORI_SYSTEM_LINKER	Explicit linker path
ORI_USE_BUNDLED_RUST_LLD=1	Force bundled rust-lld
ORI_USE_RUSTC_DRIVER=1	Legacy rustc driver (not for end users)
ORI_USE_JIT=1 / ORI_USE_AOT=1	Force ori run mode
ORI_RUNTIME_CDYLIB / ORI_RUNTIME_LIB	Runtime path overrides
ORI_STDLIB_ROOT	Stdlib path override
ORI_REQUIRE_PACKAGED_RUNTIME=1	Package-only runtime (smoke/release)

---

Troubleshooting

Symptom	Fix
native.link_failed / linker not found	Install OS linker prereqs; check link.exe / ld / xcrun --find ld
Runtime not found	Keep runtime/ beside ori
ori run works, ori compile fails	Install system linker (AOT only)
VS Code / LSP	Put ori-lsp on PATH or set ori.lsp.path / ori.compiler.path / ori.stdlib.root

---

Maintainer package smoke

sh tools/package_native_release.sh --force
sh tools/smoke_no_rust.sh --package-root compiler/target/dist/ori-… --allow-rust-on-path

See AGENTS.md and spec/19-abi.md (ori-native-abi-1).