Skip to content

Getting started with Incan

This tutorial is the shortest public path from an installed toolchain to running, testing, and release-building a project. It does not require cloning the compiler repository.

  1. InstallVerify the toolchain
  2. CreateScaffold a project
  3. PrepareSeal project plans
  4. RunExecute the entry point
  5. TestCheck behavior
  6. BuildProduce a release binary

Install and verify

The supported release channels install the same Incan toolchain payload. Choose the command manager that already fits your environment:

curl -fsSL https://github.com/encero-systems/incan/releases/latest/download/install.sh | bash

export PATH="$HOME/.local/bin:$PATH"
incan --version
incan-lsp --version

This path verifies the release manifest and checksum and can provision the stable Rust backend through rustup.

brew tap encero-systems/tap
brew install incan
incan --version

Homebrew installs the prebuilt command binaries. Manage Rust separately.

npm install -g @incan/toolchain
incan --version

npm installs command shims without a lifecycle script; the first incan run provisions the checksum-verified toolchain for your host. Manage Rust and the wasm32-wasip1 target separately.

pipx install incan
incan --version

pipx keeps the command package isolated and routes installation through the shared release installer.

Native Windows and Linux arm64 are not supported by the current binary installer. Use WSL2 or a source build on those hosts.

Create your first project

Create a small starter project and complete the canonical first-contact loop:

incan new hello --yes
cd hello
incan oven bake --project .
incan run
incan test
incan build --release

This is the canonical first-contact loop: scaffold one project, prepare its receipt-bound debug and release plans once, run its entry point, execute its tests, and produce a native release build. Normal run, test, and build commands then reuse the sealed plans without invoking Cargo.

This creates:

hello/
├── src/
│   └── main.incn          # Entry point and a small greeting function
├── tests/
│   └── test_main.incn     # Starter test for the greeting function
├── README.md
├── .gitignore
└── incan.toml             # Project manifest with a main script and requires-incan constraint

The explicit Oven bake records the source, lock, compiler, SDK, target, and build intent that make this project reusable. The starter then prints its greeting from src/main.incn; at this point the manifest, source root, entry point, and Rust-backed build path are all connected.

incan build already uses the release Cargo profile; --release is accepted so the first-contact command spells out the intent.

You now have a runnable project, a passing starter test, and a native release build. Continue with Your first project to split the starter into modules and add meaningful tests.

What this release line is good for

The canonical installer resolves the Incan 0.5 release line verified by this first-contact tutorial. It is intended for trying Incan as an installed toolchain, creating small projects, running tests, checking diagnostics, inspecting generated artifacts, and evaluating how Incan fits into Rust-backed application tooling.

Each tutorial identifies its compatible compiler range in the Verified field. Use that field with the docs version selector when reading documentation for an older release.

Continue with the 0.5 project tutorials

The representative project tutorials use the same 0.5 language, toolchain, and release envelope installed above:

Use Build the 0.5 toolchain from source only when contributing to Incan or when a prebuilt archive is unavailable. The 0.4 documentation remains available for an older installed toolchain.

What this release line is not yet good for

Incan is not a Python compatibility runtime, a native Windows installer release, a full package registry, or a promise that generated Rust is a stable ABI. Generated Rust is inspectable current backend output; public compatibility should be based on Incan source, manifests, checked metadata, and documented CLI report schemas.

Next steps

  • Your first project: split the starter into modules and add real tests.
  • CLI reference: commands, flags, and machine-readable outputs.
  • Incan vs Python: where Incan tries to win and where Python is still the better choice.
  • Incan vs Rust: why Incan compiles through Rust but does not replace Rust.
  • Encero stack: where Incan sits relative to IncQL, Pallay, Omerus, Hees.ai, and Hees.io.