Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Quickstart

Official packaging policy: docs/operations/packaging.md.

Audience and install path

  • End users and external adopters: install a pinned binary from GitHub Releases (primary path).
  • Rust-native fallback: cargo install archkit --locked --version <x.y.z>.
  • Contributors to this repo: use source workflow below (cargo make onboarding), with optional cargo install --path . for local install checks.

0) Install prerequisites

Rust toolchain is pinned by this repo to 1.94.1 via rust-toolchain.toml.

Required for onboarding:

  • rustc
  • cargo

Optional (warn-only in onboarding preflight):

  • dot (Graphviz render gate)
  • git (doc drift checks like cargo make autodoc-check; docgen-check is a compatibility alias)
  • nu (parity script)

Install cargo-make once:

cargo install cargo-make --version 0.37.24 --locked

1) One-command onboarding

Run the local onboarding flow:

cargo make onboarding

This runs a preflight, verifies formatting, builds the workspace, runs the production-like dogfood validate/project path, and regenerates docs artifacts.

Discoverability commands:

cargo make
cargo make help
cargo make --list-all-steps --output-format short-description

Use the canonical AKS path (Tier 1):

cargo make dev

This emits deterministic artifacts under generated/ephemeral/dogfood/main/, including canonical JSON, DOT, and Mermaid outputs.

3) Docs and artifacts

Generate docs and rustdoc artifacts:

cargo make docs-artifacts

4) Full local test suite

cargo make test-all

Recommended first 5-10 minutes after clone:

cargo make onboarding
cargo make dev
cargo make docs-artifacts
cargo make test-all

5) Optional Graphviz render gate

Requires Graphviz (dot -V):

cargo make render

5b) Canonical project architecture workflow

Run the canonical self-model for this repository:

cargo make architecture-self

Canonical source model: architecture/models/archkit_self.ncl.

6) Direct CLI flow (contributor/source workflow)

Enter the Nix dev shell:

nix develop -c bash

Validate a Nickel spec:

cargo run -p archkit-cli -- validate -i docs/dogfood/examples/workspace.ncl

Project a named view to DOT (+ Mermaid companion):

cargo run -p archkit-cli -- view -i docs/dogfood/examples/workspace.ncl --view-id container_main -o generated/ephemeral/run/container.dot

This also writes generated/ephemeral/run/container.document.json and generated/ephemeral/run/container.mmd.

6b) (Optional, experimental) Generate AKS from canonical JSON

cargo run -p archkit-cli -- export-aks -i generated/ephemeral/run/container.document.json -o generated/ephemeral/run/container.aks

6c) (Optional) Generate Nickel from canonical JSON

cargo run -p archkit-cli -- export-nickel -i generated/ephemeral/run/container.document.json -o generated/ephemeral/run/container.ncl

6d) Render DOT to SVG

cargo run -p archkit-cli -- render -i generated/ephemeral/run/container.dot -f svg -o generated/ephemeral/run/container.svg

This also writes generated/ephemeral/run/container.document.json, generated/ephemeral/run/container.dot, and generated/ephemeral/run/container.mmd (copied canonical JSON and Mermaid companion from projection artifacts).

7) Clean-room setup verification (sprint baseline)

Use this checklist to verify a new machine can run the documented CLI path without hidden assumptions.

  1. Build:
cargo build

Expected: build succeeds.

  1. Validate Nickel example:
cargo run -p archkit-cli -- validate -i docs/dogfood/examples/workspace.ncl

Expected: exit 0, workspace valid.

  1. View named diagram:
cargo run -p archkit-cli -- view -i docs/dogfood/examples/workspace.ncl --view-id container_main -o generated/ephemeral/run/container.dot

Expected: generated/ephemeral/run/container.dot, generated/ephemeral/run/container.mmd, and generated/ephemeral/run/container.document.json.

  1. Render when Graphviz is installed:
dot -V
cargo run -p archkit-cli -- render -i generated/ephemeral/run/container.dot -f svg -o generated/ephemeral/run/container.svg

Expected: exit 0, generated/ephemeral/run/container.svg plus render companions.

  1. Graphviz-absent behavior:
  • If dot -V fails, onboarding and validate/project checks are still valid baseline success.
  • render is expected to fail with error[render] and exit class 4 until Graphviz is installed.
  1. Feature-flag variants:
cargo test --no-default-features
cargo test --features dot-import

Expected: both commands pass; feature-disabled command paths report exit class 5 where applicable.

architecture/
  workspace.aks
generated/ephemeral/run/
  *.dot
  *.mmd
  *.document.json
  *.svg

Use validate and view in CI to keep architecture specs reviewable and deterministic.

AKS is Tier 1 canonical specification language. Nickel is Tier 2 complementary for contracts.

Dogfood target

The repository includes a realistic end-to-end target under dogfood/:

archkit validate -i dogfood/architecture/main.ncl
archkit view -i dogfood/architecture/main.ncl --view-id container_main -o generated/ephemeral/dogfood/main/container.dot