Developer Setup

For contributors, extractor authors, and anyone who wants to run OpenRemap from source, modify the code, or run the test suite.

Prerequisites

Install uv

uv manages the virtual environment, dependencies, and Python version automatically.

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
winget install astral-sh.uv

Full documentation: docs.astral.sh/uv

Install git

Download from git-scm.com or use your system package manager.

Clone and set up

git clone https://github.com/v-arapidis/openremap-core.git
cd openremap-core
uv sync

uv sync creates a virtual environment at .venv/ inside the project folder, installs all dependencies, and pins them to the exact versions in uv.lock. It does not affect anything outside the project folder.

Build the Rust native extension

The performance-critical core (checksum engine, map scanner, diff, entropy, and the migrated hot loops) is a mandatory Rust extension — there is no pure-Python fallback. Build it once after cloning, and again after any Rust change:

uv run maturin develop --release

You need a Rust toolchain (rustup): rustup.rs. The extension lives in openremap/_rs/; if the CLI behaves differently than the source suggests, the installed extension is stale — rebuild it.

Running commands

You have two options after uv sync.

Option A — prefix with uv run (no activation needed)

uv run openremap identify ecu.bin
uv run openremap scan ./my_bins/
uv run pytest

uv run automatically activates the project environment for that single call. This works from anywhere inside the project folder and requires no setup step.

Option B — activate the environment once per session

# macOS / Linux
source .venv/bin/activate

# Windows (Command Prompt)
.venv\Scripts\activate.bat

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

After activation, the bare command works for the rest of the terminal session:

openremap identify ecu.bin
pytest

Run deactivate to leave the environment, or just close the terminal.

💡 For interactive use, just run openremap (or uv run openremap) with no arguments to launch the TUI.

Running the test suite

uv run pytest tests/ -q

All tests must pass before submitting a pull request. Expected output on a clean install:

5,692 passed, 12 skipped, 1 xfailed in X.XXs

To run a specific test file:

uv run pytest tests/tuning/manufacturers/test_edc17_extractor.py -v

Project structure

openremap-core/
├── openremap/
│   ├── cli/
│   │   └── commands/       ← identify.py, scan.py, cook.py, health.py, etc.
│   ├── core/
│   │   ├── manufacturers/  ← one sub-package per OEM (Bosch, Siemens, …)
│   │   │   └── bosch/
│   │   │       └── edc17/  ← extractor.py + patterns.py per family
│   │   └── services/       ← domain folders: identify/, checksums/,
│   │       │                  maps/, recipes/ (+ entropy.py at root)
│   │       └── …
│   └── _rs/                ← Rust native extension (mandatory)
│       └── src/            ← primitives/, identify/, maps/, checksums/, recipes/
├── tests/                  ← mirrors the package layout
├── notes/                  ← private dev folder (gitignored — not in the repo)
├── pyproject.toml
└── uv.lock

The most impactful contribution is adding a new ECU extractor — every new family added makes the full pipeline (identify, scan, recipe, validate, patch) work for that family automatically. See CONTRIBUTING.md for a full step-by-step guide.

Shell completion (development install)

uv run openremap --install-completion

Restart your terminal after running this.

Updating dependencies

git pull
uv sync

uv sync installs any new or changed dependencies automatically.

Publishing a release

Releases are built and published from the project root:

uv build
uv publish

Artifacts appear in dist/.

← Back to README