# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Common Commands
| **Build** | `cargo build --release` | Builds all binaries (sl, gti, etc.) in release mode. For static linking on Linux use `RUSTFLAGS="-C target-feature=+crt-static" cargo build --release`.
| **Run a binary** | `cargo run --bin sl` | Replace `sl` with any binary name (e.g., `gti`, `pc`).
| **Install to $HOME/.cargo/bin** | `cargo install coretilus` | Adds all binaries to your path.
| **Run tests** | `cargo test` | Runs all unit tests.
| **Run a single test** | `cargo test <test_name>` | Replace `<test_name>` with the test function name.
| **Run doctests** | `cargo test --doc` | Executes documentation tests.
| **Coverage** | `cargo llvm-cov --doctests --open` | Requires the `cargo-llvm-cov` tool.
| **Lint** | `cargo clippy --all-targets --all-features -- -D warnings` | Treats warnings as errors.
| **Generate docs** | `cargo doc --no-deps --open` | Opens docs in browser.
| **Generate GIFs** | `RUSTFLAGS="-C target-feature=+crt-static" cargo build --release` then run the docker commands in `README.md`.
## How to run a single test
`cargo test <test_name>` runs only the test function named `<test_name>`. To filter tests, use `cargo test -- --nocapture` to see output.
## High‑Level Architecture
* **`src/coretilus.rs`** – The library entry point exposing sub‑modules: `engine_v2`, `commands`, `engine`, etc.
* **`src/engine_v2`** – The core rendering engine that manages a scene, objects, movement, collision detection, and terminal rendering via `crossterm`.
* **`src/commands`** – One directory per command (e.g., `sl`, `gti`, `pc`, `mr`, `dog`, `gb`). Each binary defines a struct implementing `CommandV2`. The `cli_v2.rs` file builds the object list and handles CLI flags.
* **`src/commands/mod.rs`** – Registers all command structs so the binary can dispatch the right one.
* **`Cargo.toml`** – Builds the library and a binary for each command. Dependencies include `crossterm`, `rand`, `regex`, and `uuid`.
The application works by compiling all command binaries; running a binary directly (`sl`, `gti`, …) invokes its `CommandV2::execute` method, which builds the engine with the chosen objects and starts the terminal loop.
## CI & Release
* The repository uses GitHub Actions (`ci.yml` and `release.yml`). CI runs tests, linting, and builds for all targets. The release workflow builds cross‑compiled binaries and publishes them to GitHub releases, crates.io, and a Homebrew tap.
* To manually trigger a release, tag a commit with `v<semver>` and push the tag.
## Useful Flags & Environment Variables
* `RUST_LOG` – Controls log level for the engine.
* `CARGO_TARGET_DIR` – Optional output directory for build artifacts.
## Contributing
The repository follows the same conventions as `uutils/coreutils`. Use the existing `README.md` for detailed usage, license, and contribution guidelines.
---
*Generated by Claude Code*
