# Installation

> Add Carte to a Rust project, and what the pre-release state means for you.

> **Pre-release.** Carte is not on crates.io yet. Until the first release, you depend on it by Git or by path. The crate is named `carte`, but the name `carte` on crates.io is currently held by an unrelated project. TODO: the published crate name is undecided.

## Requirements

- Rust 1.80 or newer, edition 2021.
- Nothing else. Carte has no dependencies, not even optional ones, and builds anywhere the standard library does.

## Add the crate

Until it is published, depend on the repository:

```toml
[dependencies]
carte = { git = "https://github.com/fian-team/carte" }
```

> TODO: the public repository URL is not settled. If you have a local checkout, use `path = "../carte"` in place of `git`.

Once Carte is published, this becomes:

```sh
cargo add carte
```

Every page in these docs writes `carte::`, which compiles as written.

## What you get

The crate root re-exports everything you need for ordinary use:

```rust
use carte::{
    Departure, Escape, EscapeOutcome, Node, Occlusion, Outbox, Refusal, RouteId, RouteTable,
    Router, Scope, Store,
};
use carte::schema::{Field, Kind, Lit, Schema};
use carte::set;
```

The modules are `table`, `router`, `guard`, `outbox`, `store`, `schema`, `intent` and `validate`. Most types are also re-exported at the root.

## No dependencies, enforced

Carte's `[dependencies]` table is empty, and a test in the crate (`tests/independence.rs`) fails the build if anyone adds an entry to it. `cargo tree` on Carte shows nothing at all. This is the guarantee that lets you put any UI layer on top: Carte cannot pull a toolkit, a runtime or an async executor into your build.

The examples have a dev-dependency on `eframe` so they can open a window. That never reaches your build.

## Run the example

The repository ships one example, a notes app drawn with egui. From a checkout:

```sh
cargo run --example notes
```

It has five screens, one of them reachable from two places, a guarded screen, a prompt that stacks over the editor, and a side panel that shows the router and the store as they run. Its tests drive the same frames with no window:

```sh
cargo test --example notes
```

## Things to know before you start

- **Not `Send`.** The store holds scopes as `Box<dyn Any>` and the router holds a boxed closure, neither with a `Send` bound. Keep Carte on your UI thread.
- **No derive macros yet.** You implement `Schema` and `Intents` by hand. The derives exist in a separate, unpublished crate. See [Schemas](/docs/state/schemas).
- **The API will change.** The crate is at 0.1.0 and has made no stability promise.

## Next

Build something small in the [Quick start](/docs/quick-start).