# Getting Started

This guide takes you from a clean machine to building Oxide, running an example,
and running the test and benchmark suites.

## Prerequisites

- **Rust stable toolchain.** Install via [rustup](https://rustup.rs):
  ```sh
  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  ```
  Oxide tracks the stable channel and sets a minimum supported Rust version
  (MSRV) in the workspace `Cargo.toml` (`rust-version`).
- **Linux** is the primary target. Other platforms are not yet tested.
- **A GPU with Vulkan support** (`wgpu` is integrated since Stage 2; on Linux
  the Vulkan backend is the default). Backend selection can be overridden with
  the `WGPU_BACKEND` environment variable.

## Cloning

```sh
git clone https://git.houmeres.sk/Houmeres/Oxide.git
cd Oxide
```

## Building

Build the whole workspace (engine, editor, examples, tests):

```sh
cargo build            # debug
cargo build --release  # optimized
```

The workspace is a Cargo workspace with these members:

- `oxide-engine` — the core library
- `oxide-editor` — the in-engine editor binary
- `oxide-examples` — runnable examples (one or more per stage)
- `oxide-tests` — the integration test harness

## Running the editor

```sh
cargo run -p oxide-editor --release
```

The editor opens its own window with a placeholder viewport (Stage 2); editor
panels arrive with the systems they edit in later stages. Quit with `Ctrl+Q`.
Raw input logging is visible with `RUST_LOG=debug`.

## Running examples

Examples live in `examples/src/bin/` and each is a standalone binary:

```sh
cargo run -p oxide-examples --bin math_demo
```

| Example | Stage | Description |
|---------|-------|-------------|
| `math_demo` | 1 | Prints a tour of transforms, bounds, ray/plane queries, frustum culling, color, and value ranges |
| `hello_window` | 2 | Opens a window cleared to a configurable color — keys `1`–`5` pick presets, `Space` cycles, `Esc` quits; FPS logged once per second |

## Running tests

```sh
cargo test                       # the whole workspace
cargo test -p oxide-engine       # engine unit tests only
cargo test -p oxide-tests        # integration tests only
```

Unit tests live next to the code they test (a `#[cfg(test)] mod tests` block in
each module). End-to-end and cross-cutting tests live in the `oxide-tests` crate.

## Running benchmarks

Performance-sensitive systems use [criterion](https://github.com/bheisler/criterion.rs):

```sh
cargo bench -p oxide-engine
```

Stage 1 ships the `transform` benchmark, which includes `compose_1m` (the Stage 1
budget is 1,000,000 transform compositions in under 10 ms).

## Lint and format

Both must be clean before any change is committed:

```sh
cargo clippy --all-targets -- -D warnings
cargo fmt --check
```

The engine and editor crates are compiled with `#![deny(warnings)]`, so warnings
are hard errors.

## Installing to the system (Linux)

```sh
chmod +x install.sh
./install.sh                 # installs to /usr/local
PREFIX=$HOME/.local ./install.sh   # custom prefix
```

This builds in release mode and installs the `oxide-editor` binary plus assets.
To uninstall:

```sh
sudo rm /usr/local/bin/oxide-editor
sudo rm -rf /usr/local/share/oxide
```