Getting Started

Getting Started

Don't want to learn the syntax first? Paste agent-skills/nirdosha/paste-anywhere-prompt.md into any LLM chat (ChatGPT, Claude.ai, Gemini, ...), describe what you want in plain English, and it writes the .nir code for you — no install needed for that step. See LLM Integration for what that's been used to build. Everything below is for actually running the code it hands you back.

Install (no Rust, no clang, no z3)

# macOS / Linux
curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/arunsoman/nirdosha/main/scripts/install.sh | sh

# Windows
irm https://raw.githubusercontent.com/arunsoman/nirdosha/main/scripts/install.ps1 | iex

Prebuilt binaries: Linux x86_64 and Windows x86_64 have Z3 statically vendored — nothing to install first, no linker errors. macOS binaries link the system Z3 instead (brew install z3 first) — z3-src 416.0.2 doesn't compile against the AppleClang on current macOS toolchains, a real upstream incompatibility, not a packaging choice; tracked in PUBLIC_ROADMAP.md. clang is only needed later, and only on the machine running nirdosha build/emit-llvm (native codegen); interpreting, emit-ui, and serve all work straight out of the download on every platform. See GitHub Releases to download a binary directly instead of piping the script.

Windows is untested. The compiled tcp/tcp_listener runtime was ported to Windows' socket API but has not been verified against a real Windows machine. Everything else (interpret, emit-ui, serve, the rest of native codegen) doesn't touch that code path and should be unaffected. Please report an issue if something doesn't work on Windows.

Get the examples

git clone https://github.com/arunsoman/nirdosha.git
cd nirdosha

Or build from source (for contributors)

cd compiler
cargo build --release
# binary: compiler/target/release/nirdosha

Toolchain: Rust (edition 2024), plus two system libraries the build links against directly — install these before cargo build or the build fails with a linker error, not a friendly message:

# Debian/Ubuntu
sudo apt install clang libz3-dev

# macOS (Homebrew)
brew install llvm z3

# Arch
sudo pacman -S clang z3

clang is invoked at runtime by nirdosha build/emit-llvm (native codegen); z3 is linked at compile time for the SMT refinement layer and is required even just to build the compiler, not only to use that feature. (The prebuilt binaries above sidestep this with cargo build --features dist, which vendors Z3 from source instead.)

Run a program

# Interpret (always works for every construct)
nirdosha examples/hello.nir

# Compile to a native binary (subset — see LANGUAGE.md §10)
nirdosha build examples/factorial.nir -o factorial
./factorial

# Inspect the program
nirdosha emit-llvm examples/factorial.nir   # print LLVM IR
nirdosha emit-ast  examples/matrices.nir    # print AST as JSON

Scaffold a new project

nirdosha init shop
# writes ./shop/:
#   shop.nir      -- starter source (Email/RoleMapping admin-panel
#                     fixtures by default; --no-email/--no-roles/--sms/
#                     --push to change which ones)
#   nirdosha      -- a copy of this executable, so the folder can be
#                     moved to another machine and run standalone (same
#                     OS/arch only -- no cross-compilation)
#   run.sh        -- launches it: nirdosha serve shop.nir ... (run.bat
#                     on Windows)
#   jwks.json     -- an empty placeholder key set so run.sh works out of
#                     the box; requires(role: ...) routes 401 until real
#                     identity-provider values replace the placeholder
#                     --jwks-file/--issuer/--audience in run.sh

cd shop && ./run.sh

--dest <path> puts the shop/ folder under <path> instead of the current directory; --force overwrites an existing one. This is tooling convenience only — Nirdosha has no compiler-level notion of "a project" beyond the one .nir file inside the folder.

Generate / serve a UI

nirdosha emit-ui examples/store.nir -o store.html   # self-contained CRUD HTML
nirdosha serve   examples/store.nir --port 8080     # JSON API server

Structured diagnostics (for LLM/agent loops)

nirdosha examples/broken.nir --format=json   # Diagnostic JSON on failure

Explore the language

• Full feature reference: LANGUAGE.md
• Full grammar: GRAMMAR.md
• Design rationale: goal.md, Nirdosha_Unified_Plan.md — see also Design Philosophy
• Sandboxing: SANDBOXING.md · Transactions: TRANSACT.md
• Agent API: nirdosha-agent-api.md — see also LLM Integration

Start small (hello.nir → factorial.nir → ownership.nir → borrow.nir), then concurrency (threads.nir, channels.nir, sandbox.nir), then the domain-scale examples (store.nir, transact.nir, rev-assurence/, trade-finance/).