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.

Install and verify

Install the toolchain, then make sure the command is on PATH. The direct installer provisions stable Rust through rustup when needed and installs the wasm32-wasip1 target used by package vocab companions:

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

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

You can also install through Homebrew, npm, or pipx; those package-manager channels use the same GitHub Release payloads as the shell installer. pipx routes through the shared installer and can provision Rust automatically. npm installs a host-specific optional platform package without running lifecycle scripts, and Homebrew installs the prebuilt command binaries from the Encero tap; both npm and Homebrew expect Rust to be managed separately.

brew tap encero-systems/tap
brew install incan

Native Windows and Linux arm64 are not supported by the initial toolchain installer. Use WSL2 or a source build for those hosts for now.

Create your first project

Create a small starter project:

incan new hello --yes
cd hello

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

Run it:

incan run

Test it:

incan test

Build the release binary:

incan build --release

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

What 0.4 is good for

0.4 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.

What 0.4 is not yet good for

0.4 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 project 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.