Skip to main content
First off, thanks for taking the time to contribute! This guide will help you get started with contributing to oboromi.

​
Getting Started

​
Prerequisites

To build and run oboromi, you will need the following tools installed:
1

Install Rust

Install the latest stable version of Rust from rust-lang.org.
2

Install CMake

Version 3.16 or higher is required for building dependencies.
3

Install Ninja

The Ninja build system is used for faster compilation.
4

Install C++ Compiler

  • Windows: MSVC (Visual Studio Build Tools)
  • macOS/Linux: Clang

​
Building the Project

Once you have the prerequisites installed, follow these steps:
1

Clone the repository

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

Build and run

cargo run
This will compile the project and launch the GUI.
The first build will take some time as Cargo downloads and compiles all dependencies, including the Unicorn engine bindings.

​
Code Style

We follow standard Rust community guidelines to maintain code quality and consistency.

​
Formatting

All code must be formatted using rustfmt. Before submitting a PR, run: 
cargo fmt
This ensures consistent code style across the project.

​
Linting

Use clippy to catch common mistakes and improve code quality: 
cargo clippy
Currently, it’s normal if clippy fails in some areas as the project is in early development. However, please ensure your new code doesn’t introduce additional clippy warnings.

​
Running Tests

We prioritize correctness. Please ensure all tests pass before submitting a PR. 
cargo test
The project currently has limited test coverage as it’s in early development. See the Testing page for more details on the existing test suite.

​
Submitting a Pull Request

Follow these steps when submitting a pull request:
1

Fork and create a branch

Fork the repository and create your branch from main.
git checkout -b feature/your-feature-name
2

Add tests

If you’ve added code that should be tested, add tests. This helps ensure the emulator remains correct as it evolves.
3

Run the test suite

Ensure all tests pass:
cargo test
4

Format and lint

Make sure your code is properly formatted and passes linting:
cargo fmt
cargo clippy
5

Submit the PR

Push your branch and create a pull request on GitHub with a clear description of your changes.

​
Reporting Bugs

Bugs are tracked as GitHub issues. When filing an issue, please include:
  • Clear and descriptive title - Help maintainers quickly identify the problem
  • Exact steps to reproduce - What actions led to the issue?
  • Expected behavior - What did you expect to happen?
  • Actual behavior - What actually happened?
  • Environment details - OS, Rust version, etc.
Title: CPU test hangs on macOS with M1 chipSteps to reproduce:
  1. Build oboromi on macOS M1
  2. Run cargo test
  3. Observe that test_multicore_initialization hangs
Expected: Test should complete in less than 100msActual: Test hangs indefinitelyEnvironment: macOS 14.0, Rust 1.75.0, Apple M1

​
License

By contributing, you agree that your contributions will be licensed under the GNU General Public License v3.

​
Project Structure

oboromi/
├── core/          # Core emulator library
│   └── src/
│       ├── cpu/   # CPU emulation (ARM64)
│       ├── gpu/   # GPU emulation (Vulkan)
│       └── tests/ # CPU instruction tests
├── gui/           # eframe/egui GUI frontend
│   └── src/
│       └── gui/   # GUI implementation
└── assets/        # Resources (logos, etc.)
For more information on testing and debugging, see the Testing and Debugging pages.

Build docs developers (and LLMs) love

Get started for freeTalk to us