Building from Source

Overview

oboromi uses Cargo as its primary build system with a workspace structure. The project includes native dependencies that require CMake, Ninja, and a C++ compiler.

Building oboromi requires both Rust and C++ toolchains due to the Unicorn Engine dependency used for ARM64 CPU emulation.

System Requirements

Minimum Requirements

OS: Linux, macOS, or Windows 10/11
RAM: 4GB (8GB recommended for debug builds)
Disk Space: 2GB for source code and build artifacts
Display: GPU with Vulkan 1.3 support (for GUI)

Required Tools

Linux
macOS
Windows

Ubuntu/Debian:

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Install build tools
sudo apt update
sudo apt install -y \
  cmake \
  ninja-build \
  clang \
  pkg-config \
  libvulkan-dev

Fedora:

sudo dnf install -y cmake ninja-build clang vulkan-devel

Arch Linux:

sudo pacman -S cmake ninja clang vulkan-headers vulkan-icd-loader

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Install build tools
brew install cmake ninja

# Xcode Command Line Tools (includes Clang)
xcode-select --install

MoltenVK (Vulkan for macOS) will be installed automatically via the ash crate.

Option 1: Visual Studio (Recommended)

Install Visual Studio 2019 or later
Select “Desktop development with C++” workload
Install Rust via rustup-init.exe
Install CMake
Install Ninja

Option 2: Chocolatey

# In PowerShell (Admin)
choco install rust cmake ninja

Option 3: Scoop

scoop install rustup cmake ninja

Ensure Visual Studio’s MSVC is in your PATH. Run builds from “Developer Command Prompt for VS” if you encounter linker errors.

Cargo Workspace Structure

oboromi uses a Cargo workspace defined in the root Cargo.toml:

Cargo.toml

[workspace]
resolver = "3"
members = [
  "core",
  "gui",
]

[workspace.dependencies]
cc = "1.2"
log = "0.4"
fern = { version = "0.7", features = ["colored"] }
crossbeam-channel = "0.5"
egui = "0.33"
eframe = "0.33"
serde = "1.0"
thiserror = "2.0"
oboromi-core = { path = "core" }
oboromi-gui = { path = "gui" }

Core Library (`core/`)

The main emulation engine:

core/Cargo.toml

[package]
name = "oboromi-core"
version = "0.0.1"
edition = "2024"
authors = ["Nikilite", "Elizabeth"]
license = "GPL-3.0"

[dependencies]
unicorn-engine = "2.1.1"  # ARM64 CPU emulation
libc = "0.2.177"           # System interfaces
memmap2 = "0.9.9"          # Memory mapping
log = { workspace = true } # Logging
ash = "0.38.0+1.3.281"     # Vulkan bindings

[features]
default = []
trace = []  # Enable instruction-level tracing

Key dependencies:

unicorn-engine: Provides ARMv8 CPU emulation via QEMU’s TCG backend
ash: Vulkan 1.3 bindings for GPU rendering
memmap2: Efficient memory-mapped I/O for filesystem emulation

GUI Frontend (`gui/`)

The eframe/egui-based interface:

gui/Cargo.toml

[package]
name = "oboromi-gui"
version = "0.0.1"
edition = "2024"
authors = ["Nikilite"]
license = "MPL-2.0"

[dependencies]
oboromi-core = { path = "../core", default-features = false }
egui = { workspace = true }   # Immediate mode GUI
eframe = { workspace = true }  # Cross-platform window management
fern = { workspace = true }    # Logging configuration
log = { workspace = true }
image = "0.25.6"               # Logo loading

[features]
default = []
trace = ["oboromi-core/trace"]  # Forward trace feature

[[bin]]
name = "oboromi"
path = "src/main.rs"

Building

Clone the repository

git clone https://github.com/0xNikilite/oboromi
cd oboromi

The repository includes git submodules if present:

git submodule update --init --recursive

Verify prerequisites

Check that all tools are installed:

# Check Rust
rustc --version
cargo --version

# Check build tools
cmake --version
ninja --version

# Check C++ compiler (Linux/macOS)
clang --version

# Check C++ compiler (Windows)
cl.exe  # Should be in PATH from VS

Build in debug mode

Debug builds include symbols and assertions:

cargo build

This compiles:

core/ → target/debug/liboboromi_core.rlib
gui/ → target/debug/oboromi (or oboromi.exe on Windows)

Build time: 2-5 minutes on first build (downloads and compiles ~200 crates)

Build in release mode

Release builds are optimized and significantly faster:

cargo build --release

Output: target/release/oboromiBuild time: 5-10 minutes (with full optimizations)

Build Features

Trace Feature

Enable instruction-level tracing for debugging:

cargo build --features trace

This activates logging in core/src/cpu/unicorn_interface.rs and shows:

Every ARM64 instruction executed
Register states after each instruction
System call interception
Memory access patterns

Trace mode generates massive log files and slows execution by 100-1000x. Only use for debugging specific issues.

Custom Feature Combinations

# Build only the core library
cargo build -p oboromi-core

# Build only the GUI
cargo build -p oboromi-gui

# Build with trace for specific package
cargo build -p oboromi-core --features trace

Build Output Structure

target/
├── debug/               # Debug builds
│   ├── oboromi          # Main executable
│   ├── liboboromi_core.rlib
│   ├── deps/            # Compiled dependencies
│   └── build/           # Build script outputs
├── release/             # Release builds
│   └── oboromi          # Optimized executable
└── doc/                 # Generated documentation

Development Builds

Quick Iteration

For fast rebuilds during development:

# Use cargo-watch for auto-rebuild on file changes
cargo install cargo-watch
cargo watch -x "build -p oboromi-core"

Check Without Building

Verify code compiles without full build:

cargo check

Format Code

cargo fmt

Lint Code

cargo clippy

Per CONTRIBUTING.md, it’s currently normal for cargo clippy to report warnings. The project is in early development.

Testing

Run Tests

cargo test

As noted in CONTRIBUTING.md, the test suite is still under development. The GUI provides a “Run CPU Tests” button that executes oboromi_core::tests::run::run_tests().

Test Specific Modules

# Test only core library
cargo test -p oboromi-core

# Test with trace output
cargo test -- --nocapture

Build Troubleshooting

error: linking with `cc` failed

Cause: Missing C++ compiler or linker.Linux: Install build-essential

sudo apt install build-essential

macOS: Install Xcode Command Line Tools

xcode-select --install

Windows: Ensure MSVC is in PATH via Developer Command Prompt

CMake error: Could not find Ninja

Cause: Ninja build system not found.Install Ninja:

# Linux
sudo apt install ninja-build

# macOS
brew install ninja

# Windows
choco install ninja

unicorn-engine build fails

Cause: Unicorn Engine requires CMake ≥3.16 and a C compiler.Solution: Ensure CMake and a C compiler are installed and in PATH:

cmake --version  # Should be ≥3.16
cc --version     # Should show gcc or clang

On Windows, use Visual Studio’s Developer Command Prompt.

error: failed to run custom build command for `ash`

Cause: Missing Vulkan SDK or headers.Linux:

sudo apt install libvulkan-dev vulkan-tools

macOS: MoltenVK should install automatically, but you can manually install:

brew install molten-vk

Windows: Install the Vulkan SDK

Out of memory during build

Cause: Rust debug builds can use significant RAM.Solution: Build in release mode or limit parallel jobs:

cargo build --release -j 2

edition 2024 is unstable

Cause: Rust Edition 2024 requires nightly Rust.Solution: Install nightly toolchain:

rustup install nightly
rustup override set nightly

Or wait for Edition 2024 to stabilize and use Edition 2021 in Cargo.toml.

Cross-Compilation

Linux → Windows

# Install MinGW
sudo apt install mingw-w64

# Add Windows target
rustup target add x86_64-pc-windows-gnu

# Build
cargo build --target x86_64-pc-windows-gnu --release

macOS → Linux

# Add Linux target
rustup target add x86_64-unknown-linux-gnu

# Build (requires Linux sysroot)
cargo build --target x86_64-unknown-linux-gnu --release

Build Performance Tips

Use sccache for faster rebuilds:

cargo install sccache
export RUSTC_WRAPPER=sccache

Increase parallel jobs (if you have RAM):
```
cargo build -j 8
```

Use lld linker for faster linking:

.cargo/config.toml

[target.x86_64-unknown-linux-gnu]
linker = "clang"
rustflags = ["-C", "link-arg=-fuse-ld=lld"]

Split debuginfo to reduce link time:

Cargo.toml

[profile.dev]
split-debuginfo = "unpacked"

Next Steps

Running the Emulator

Learn how to run oboromi and use the GUI

Architecture Overview

Understand the codebase structure

Contributing

Start contributing to development

CPU Emulation

Deep dive into ARM64 emulation

Get Started

Architecture

Core Components

Development

Building from Source

Overview

System Requirements

Minimum Requirements

Required Tools

Cargo Workspace Structure

Core Library (`core/`)

GUI Frontend (`gui/`)

Building

Build Features

Trace Feature

Custom Feature Combinations

Build Output Structure

Development Builds

Quick Iteration

Check Without Building

Format Code

Lint Code

Testing

Run Tests

Test Specific Modules

Build Troubleshooting

Cross-Compilation

Linux → Windows

macOS → Linux

Build Performance Tips

Next Steps

Running the Emulator

Architecture Overview

Contributing

CPU Emulation

Build docs developers (and LLMs) love

Get Started

Architecture

Core Components

Development

​Overview

​System Requirements

​Minimum Requirements

​Required Tools

​Cargo Workspace Structure

​Core Library (core/)

​GUI Frontend (gui/)

​Building

​Build Features

​Trace Feature

​Custom Feature Combinations

​Build Output Structure

​Development Builds

​Quick Iteration

​Check Without Building

​Format Code

​Lint Code

​Testing

​Run Tests

​Test Specific Modules

​Build Troubleshooting

​Cross-Compilation

​Linux → Windows

​macOS → Linux

​Build Performance Tips

​Next Steps

Running the Emulator

Architecture Overview

Contributing

CPU Emulation

Build docs developers (and LLMs) love

Overview

System Requirements

Minimum Requirements

Required Tools

Cargo Workspace Structure

Core Library (`core/`)

GUI Frontend (`gui/`)

Building

Build Features

Trace Feature

Custom Feature Combinations

Build Output Structure

Development Builds

Quick Iteration

Check Without Building

Format Code

Lint Code

Testing

Run Tests

Test Specific Modules

Build Troubleshooting

Cross-Compilation

Linux → Windows

macOS → Linux

Build Performance Tips

Next Steps