# Build Aura from Source

*Clone the repo, build the binary, and get set up to ship your first patch.*

Aura is open source under the Apache 2.0 license. The canonical repository lives at [github.com/Naridon-Inc/aura](https://github.com/Naridon-Inc/aura). Building from source is the right path when you want to run an unreleased commit, test a pull request locally, target a platform without a prebuilt binary, or contribute a patch. This guide covers the toolchain requirements, the build itself, local install of your freshly built binary, and the mechanics of opening your first pull request.

If you just want a working `aura` binary, use the [macOS](/install-macos), [Linux](/install-linux), or [Windows](/install-windows) installers instead. Building from source is slower and has more moving parts.

## Prerequisites

- **Rust 1.80 or newer.** Aura uses features from the 2024 edition and several stabilizations landed in 1.80. Check with `rustc --version`.
- **A C compiler** (`cc` or `clang`) and `make`. Tree-sitter grammars compile native shared objects as part of the build.
- **git** 2.30+.
- **pkg-config** and **OpenSSL development headers** if you are on Linux. `libssl-dev` on Debian/Ubuntu, `openssl-devel` on Fedora/RHEL.
- Roughly 4 GB of free disk for the full debug build, 1.5 GB for a release build and its target cache.
- 4 GB of RAM minimum, 8 GB comfortable. The release build is CPU-bound and benefits from all cores.

Install Rust with `rustup` if you do not already have it:

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
rustup default stable
rustup component add rustfmt clippy
```

On Debian/Ubuntu, install the system dependencies:

```bash
sudo apt install -y build-essential pkg-config libssl-dev git
```

On Fedora/RHEL:

```bash
sudo dnf install -y gcc openssl-devel pkgconf-pkg-config git
```

On macOS, the Xcode Command Line Tools provide everything you need:

```bash
xcode-select --install
```

## Clone and build

```bash
git clone https://github.com/Naridon-Inc/aura.git
cd aura
```

The repository is a Cargo workspace. The top-level `Cargo.toml` lists several crates:

- `aura-cli` — the `aura` binary.
- `aura-core` — the semantic engine, AST parsing, snapshot store.
- `aura-merge` — the semantic merge algorithm.
- `aura-mothership` — the P2P team hub daemon.
- `aura-mcp` — the Model Context Protocol server Aura agents speak.

A full release build produces a single binary:

```bash
cargo build --release
```

Expect 3 to 8 minutes on a modern laptop for the first build. Subsequent incremental builds are a few seconds. The resulting binary lives at `target/release/aura`.

For a faster developer loop, use the debug profile:

```bash
cargo build
./target/debug/aura --version
```

Debug builds are noticeably slower at runtime but build in seconds after the first compile.

### Running the test suite

Before sending any patch upstream, run the suite:

```bash
cargo test --workspace
```

The tests cover the core semantic engine, the merge algorithm, the hook scripts, and a set of end-to-end scenarios that spawn temporary repos. Some tests require `git` on `PATH`; CI catches the rest.

Lint:

```bash
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all -- --check
```

The project treats clippy warnings as errors in CI. Run them locally before pushing.

## Installing your build

Copy the binary to any directory on your `PATH`. The simplest pattern:

```bash
cargo install --path aura-cli
```

This places `aura` at `~/.cargo/bin/aura`. Ensure `~/.cargo/bin` is on your `PATH` — rustup adds it by default.

For a system-wide install on Linux:

```bash
sudo install -m 0755 target/release/aura /usr/local/bin/aura
```

Verify:

```bash
aura --version
# aura 0.14.1 (dev build, commit abcdef0)
```

The `(dev build, ...)` suffix distinguishes a locally-built binary from a signed release. When you report bugs, include that suffix so maintainers know you are on a custom build.

## Contributing your first patch

The Aura codebase is organized to make small contributions approachable. A first patch typically touches one file, adds a test, and updates a small surface of the CLI. Good starter areas:

- **Shell completions** — missing tab-completion for a subcommand.
- **Error messages** — making an existing error more actionable.
- **Documentation** — the `docs/` tree in the repo mirrors the website.
- **Doctor checks** — extending `aura doctor` with a new environment assertion.

### Workflow

1. Fork the repo on GitHub.
2. Clone your fork, add the upstream remote:

```bash
git clone git@github.com:<your-user>/aura.git
cd aura
git remote add upstream https://github.com/Naridon-Inc/aura.git
```

3. Create a feature branch off `main`:

```bash
git checkout -b fix/doctor-inotify-check
```

4. Make the change. Run tests, clippy, and fmt locally. Importantly, since you are working on an Aura repo, **log your intent**:

```bash
cargo build --release
./target/release/aura init
./target/release/aura log-intent "Added aura doctor check for inotify watch limit"
```

The repo's own pre-commit hook runs against your changes and verifies that the intent you logged matches the AST-level diff. This is the same mechanism you will use in your own projects — dogfooding is mandatory.

5. Commit and push:

```bash
git add .
git commit -m "doctor: check inotify watch limit on Linux"
git push origin fix/doctor-inotify-check
```

6. Open a pull request against `Naridon-Inc/aura:main`. The PR template asks for:

- A one-line summary.
- A link to a related issue if one exists.
- The `aura log-intent` message you recorded.
- Test coverage notes.

CI will run the full test matrix (Linux, macOS, Windows) plus clippy and fmt. A green CI is a prerequisite for review.

### Coding conventions

- **Module layout** follows `aura-<crate>/src/<module>.rs`. One module per file; flat is better than deeply nested.
- **Error handling** uses `anyhow::Result` in binaries and `thiserror`-derived typed errors in libraries. Do not `unwrap()` outside of tests.
- **Logging** uses `tracing`. Prefer structured fields over interpolated strings.
- **Formatting** is whatever `cargo fmt` produces. Do not fight it.
- **Unsafe** is allowed only with justification in a comment.

### Architecture orientation

A few pointers for reading the codebase:

- The AST parse-and-hash pipeline starts in `aura-core/src/parse.rs`. Each language has a tree-sitter grammar wired in `aura-core/src/lang/`.
- The snapshot store is `aura-core/src/snapshot/`. It is content-addressed and lives in `.aura/snapshots/` in every tracked repo.
- The semantic diff is `aura-core/src/diff.rs`. This is the heart of the system.
- The CLI's subcommand routing is `aura-cli/src/main.rs`; each subcommand has a module under `aura-cli/src/commands/`.
- The MCP server lives in `aura-mcp/`. The 29+ tools exposed to AI agents — `aura_status`, `aura_log_intent`, etc. — are registered in `aura-mcp/src/tools/`.

For any patch larger than ~200 lines, open an issue or a draft PR *before* writing the code. The project has a small core team and they are happy to discuss design up front.

## Cross-compiling

To build for a different target from your development machine:

```bash
rustup target add aarch64-unknown-linux-gnu
cargo build --release --target aarch64-unknown-linux-gnu
```

For cross-compiling C code (the tree-sitter grammars), you may need the appropriate cross-compiler toolchain. On Ubuntu for aarch64:

```bash
sudo apt install gcc-aarch64-linux-gnu
CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc \
  cargo build --release --target aarch64-unknown-linux-gnu
```

The release pipeline uses `cross` ([github.com/cross-rs/cross](https://github.com/cross-rs/cross)) for cross-builds. It produces reproducible binaries inside container images. If your development platform differs from your target, `cross` is usually easier than wrestling linker flags.

## Keeping your fork current

```bash
git fetch upstream
git checkout main
git merge --ff-only upstream/main
git push origin main
```

For topic branches:

```bash
git checkout fix/doctor-inotify-check
git rebase upstream/main
```

Aura itself handles the rebase carefully — semantic identity of functions survives across rebases, so any intent logs you recorded remain valid. That is the same guarantee you get in your own repos. See [CLAUDE.md integration](/claude-md-integration) for how this behavior is exposed to AI agents working on your branches.

## Next steps

- [Initialize your first repository](/first-repo) with your freshly built binary.
- [Write your first intent-logged commit](/first-commit-with-intent).
- [Troubleshooting install issues](/troubleshooting-install) — applicable to source builds too.

If your build fails, the most common causes are: an old Rust toolchain (run `rustup update`), a missing C compiler, or missing OpenSSL headers on Linux. Open an issue on the GitHub repo with your `rustc --version` output and the full error log.