Skip to content

Projects today

This page explains how "projects" work in Incan.

The current model

Incan source files (.incn) are the source of truth.

When you run:

incan build path/to/main.incn

Incan generates a Rust project and builds it via Cargo.

No-install fallback

If you did not run make install, you can still run the incan binary directly:

  • from the repository root:
./target/release/incan ...
  • or via an absolute path (from anywhere):
/absolute/path/to/incan run path/to/file.incn

Where outputs go

On build, Incan prints the generated project directory and the compiled binary path. In practice, outputs live under:

  • Generated Rust project: target/incan/<name>/
  • Built binary: target/incan/<name>/target/release/<name>

See: CLI reference.

What gets regenerated

The generated Rust project under target/incan/ is tool-managed output. Treat it as generated:

  • It is safe to delete: rm -rf target/incan/
  • Manual edits inside target/incan/<name>/ may be overwritten on the next build

If an incan.lock exists, the embedded Cargo.lock payload is materialized into the generated project directory so Cargo resolves the same dependency versions every time.

Dependencies

Rust crate dependencies are resolved through a three-tier system:

  1. incan.toml (highest priority): Project manifest declares explicit dependencies with versions, features, and sources.
  2. Inline annotations: import rust::foo @ "1.0" specifies versions directly in source files.
  3. Known-good defaults: For common crates, the compiler provides tested version/feature defaults.

If none of these apply, the compiler emits an error.

See: Rust Interop and Managing dependencies.

Project configuration

Projects can optionally have an incan.toml manifest at the project root:

my_project/
├── src/
│   └── main.incn
├── tests/
│   └── test_main.incn
├── incan.toml         # Project manifest (optional)
└── incan.lock         # Lock file (auto-generated, commit to VCS)

Create one with incan init. See: Project configuration reference.

Lock files

incan.lock stores resolved dependency versions for reproducible builds. It is generated by incan lock (or automatically on first build) and should be committed to version control.

Use --locked or --frozen in CI to enforce that the lock is present and up to date.

See: Managing dependencies.

What's planned

  • "Project lifecycle" commands (incan new, incan doctor): RFC 015