Homer Simpson
9eead719b0
Full project snapshot migrated to new Gitea remote without history: engine, editor, physics, script, examples, tests, docs, and assets. Relicensed from GPLv3 to MIT and updated repo URLs. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
114 lines
3.2 KiB
Markdown
114 lines
3.2 KiB
Markdown
# 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
|
||
```
|