Development Setup

This page walks through everything needed to build and run aphid from source on your local machine.

Prerequisites

Rust toolchain

aphid is written in Rust. Install the toolchain via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Follow the on-screen prompts to complete the installation. Once finished, make sure ~/.cargo/bin is on your PATH (rustup normally sets this up for you). Verify the installation:

rustc --version
cargo --version

aphid requires Rust 1.75 or later. If you already have Rust installed, make sure you are up to date:

rustup update

Git

You will need Git to clone the repository. Most systems ship with it, but you can verify:

git --version

On macOS you can install it via Xcode Command Line Tools (xcode-select --install) or Homebrew (brew install git). On Linux, use your distribution's package manager.

Clone and build

git clone https://github.com/LHelge/aphid
cd aphid
cargo build

The first build downloads and compiles all dependencies, so it takes a while. Subsequent builds are incremental and much faster.

Run the test suite

cargo test

To run a single test by name:

cargo test <test_name_substring>

Linting and formatting

Before committing, always run:

cargo fmt
cargo clippy --all-targets -- -D warnings

These are the same checks that CI enforces on every pull request.

Running locally

The repository includes a documentation site under docs/ that doubles as a convenient test fixture. Build it:

cargo run -- --config docs/aphid.toml build

Or start the dev server with live reload:

cargo run -- --config docs/aphid.toml serve

Then open http://localhost:3000 in your browser. Any changes to content or templates trigger an automatic rebuild and browser refresh.

Next steps

  • Read Contributing for the pull request workflow and commit conventions.
  • See CLI reference for the full list of commands and flags.
  • Browse the Configuration reference to understand aphid.toml.
Linked from