Skip to content

Update README with system requirements and build info #274

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
fhackett merged 2 commits into from
Dec 15, 2025
Merged

Update README with system requirements and build info #274

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
363739d
docs: Update README of OmniLink
Qian-Cheng-nju Dec 11, 2025
748abb8
doc: Add System Prerequisites for README
Qian-Cheng-nju Dec 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 30 additions & 5 deletions omnilink/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,45 @@ This folder contains build definitions that automate most experiments.
For all commands, _run them from the repo root, not here_.
That's where `./mill` lives.

The build definitions are in `package.mill`, with dependencies on `util.mill` and `GitRepo.mill`.
The build definitions are in `package.mill`. Everything has been consolidated into a single build file.

Note: all system dependencies are installed by the Dockerfile inside `../.devcontainer`.
If you use devcontainers, it will "just work".
Otherwise, make sure you have the packages listed there installed, and consider running `./mill mill.tabcomplete/install` to get tab completions on build actions.
You will use them a lot.

Each evaluated system lives in one subfolder.
Currently, `setbench` and `wiredtiger` work.
Currently, `concurrentqueue`, `setbench`, `wiredtiger` and `atomic` work.
Note that you will need separate permission to check out a private form of `setbench`.

## System Prerequisites

### Actual Requirements

- **Linux** from recent few years. Linux must be running on **bare metal or a VM**; containers on other OS will not work.
- **Nix** installation (see `.devcontainer/devcontainer.json` for setup)

### System Configuration for rr

Two system-level configurations are required:

**1. Performance counter access:**
```bash
sudo sysctl kernel.perf_event_paranoid=1. # <=3
```

**2. AMD Zen CPU workaround (AMD EPYC/Ryzen only):**
```bash
curl -o /tmp/zen_workaround.py https://raw.githubusercontent.com/rr-debugger/rr/master/scripts/zen_workaround.py
sudo modprobe msr
sudo python3 /tmp/zen_workaround.py
```

In VMs, run these commands on the host machine.

## Data management

All data is stored in a local DuckDB database named `eval.duckdb`.
All data is stored in a local SQLite database named `eval.sqlite`.
It is not committed to source control, and acts as a persistent cache for recorded executions and validation results.
You should not need to interact with it directly.

Expand Down Expand Up @@ -46,10 +71,10 @@ Note that the actual count reflects any and all traces you already have in a giv
*Don't try to copy `out/`.*
It will just lead to broken paths and frustration.

The `omnilink/eval.duckdb` is a self-contained record of everything you did, including traces and counterexamples.
The `omnilink/eval.sqlite` is a self-contained record of everything you did, including traces and counterexamples.
Copy that into the target machines `omnilink/` dir and run the commands you need (like extracting counterexamples).

How to merge different `eval.duckdb` is an open question.
How to merge different `eval.sqlite` is an open question.
For best future proofing, add build configs rather than editing existing ones, because the same config name doing different things would be confusing.
The system is built so many contradictory configs / builds / etc can coexist under different names.

Expand Down
Loading