Oxide/docs/getting-started.md

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