Table of Contents

Getting Started

Prerequisites
Cloning
Building
Running the editor
Running examples
Running tests
Running benchmarks
Lint and format
Installing to the system (Linux)

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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:
```
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

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

Building

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

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

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:

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

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:

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:

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)

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:

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