Ripes: watching machine code execute, cycle by cycle, on a RISC-V processor

What the simulator is for

Ripes is a visual computer architecture simulator and assembly code editor built for the RISC-V instruction set architecture. The description is precise and modest at once: this is a teaching and exploration tool for the RISC-V ISA, not a full system emulator and not a hardware design tool.

The README lists four things Ripes may be used to explore, and they are the clearest statement of its scope:

- How machine code is executed on a variety of microarchitectures, RV32IMC and RV64IMC based - How different cache designs influence performance - How C and assembly code is compiled and assembled to executable machine code - How a processor interacts with memory-mapped I/O

That list is the right lens. The third item means you can follow a C function down through compilation to assembly to the actual instruction words in memory, which is a genuinely useful debugging path when a compiler generates something surprising. The fourth means the memory-mapped I/O model is exposed rather than hidden, so you can write a program that reads and writes device registers and watch the values change as the processor runs.

Newcomers are pointed at the introduction and tutorial in `docs/introduction.md`, and the broader Ripes documentation is at `docs/README.md`. Discussions are for questions and feature requests; issues are for bugs. Both exist, which for a teaching tool maintained largely by one person is a good sign of engagement.

At 3426 stars, 374 forks and 89 open issues, Ripes is well established in the computer architecture education space. Topics list the audience plainly: computer architecture, cpu-emulator, education, processor architecture, risc, risc-v, simulator, and qt.

Three ways to run it, one of them experimental

Prebuilt binaries are available for Linux, Windows and Mac through the releases page, and Ripes is also available in the browser at ripes.dk through a Qt for WebAssembly deployment. That last one is marked `Experimental` in the README, and the distinction matters if you plan to rely on it.

For Linux, releases are distributed in AppImage format. Running one is two steps: `chmod a+x` on the AppImage file, then run the file. The README states the AppImage should be compatible with most Linux distributions, which is about as broad a claim as AppImage gets you.

For Windows there is one documented dependency, and it is a common one. The C++ runtime library must be available, or an `msvcp140.dll` error is produced. The README's advice is that you probably already have it, and links to Microsoft's download page if not. That is a much better release story than a traditional installer, since there is no setup wizard and no registry residue.

The build badges tell you more about the project than the download instructions do. There are separate release workflows for Windows, Mac, Linux and WASM, and they are pinned to different Qt versions: Windows, Mac and Ubuntu workflows are labelled Qt 6.5.0 while the WASM workflow is labelled Qt 6.6.0. So the browser build tracks a slightly newer Qt than the desktop builds, which is a small detail that explains some of the difference between the two experiences.

There is no Docker image in the release story, though the tree does contain a `docker/` directory for development. There is also an `appdir/` directory at the root, which is the AppImage staging layout, and `prepareRelease.py` which is presumably what drives the packaging.

Building from source, and what the build actually needs

Ripes builds as a standard CMake project. The dependency list is short, with one entry that trips people up.

You need a recent version of Qt, meaning 6.5.0 or later, plus Qt Charts, which is explicitly noted as not bundled with Qt by default but selectable during Qt installation. You need CMake. On Linux you also need `sudo apt-get install libegl1-mesa-dev`, which is there for Qt's OpenGL support.

The build itself is the ordinary clone, configure, make sequence:

git clone --recursive https://github.com/mortbopet/Ripes.git
cd Ripes/
cmake .
Unix:               Windows:
make                jom.exe / nmake.exe / ...

Two details in that block matter. The `--recursive` flag on the clone is not optional; the tree contains a `.gitmodules` entry, so there are submodules to fetch, and skipping them produces a confusing configure failure rather than a clear message. And `cmake .` in the current directory rather than a separate build directory is the documented approach, which is old-fashioned but means the generated artifacts land next to the sources.

The README also states that Qt must be available in `CMAKE_PREFIX_PATH`, and links to the Qt CMake manual for the details. If you have multiple Qt installations, that environment variable is where the ambiguity gets resolved.

The repository layout follows the conventions of a Qt desktop application: `main.cpp` at the root, `src/` for the implementation, `resources/` for assets including the images, `test/` for tests, `docs/` for documentation, `appdir/` for packaging, `external/` for vendored dependencies, `examples/` for sample programs, and `.clang-format` for C++ formatting. `examples/` has three subdirectories, `C/`, `ELF/` and `assembly/`, registered through a Qt resource file `examples.qrc`. The `ELF/` one implies Ripes can load pre-built ELF binaries rather than only assembling from source, which is what makes it useful for testing against compiled output rather than your own hand-written assembly.

What the continuous release tells you about the direction

There is one release, and it is not a version number. It is tagged `continuous`, named Continuous release, and published on 2026-08-18, which matches the last push to the default branch `master` to the minute. A continuously rebuilt binary that always reflects the tip of the main branch.

Its notes are the most informative commit list you will find for this project, because they show what the author is actually working on rather than what the release headline claims:

- Avoid cross-thread signal emission during 'run' - Cache .text section in processor handler to avoid linear lookup on every cycle - Add real-time clock peripheral - Add raster screen peripheral - Add edge-capture/latch d-pad peripheral

Three of those five are peripherals, which is a coherent direction: a teaching simulator becomes far more useful when a student can write a program that draws to a raster screen, reads a clock, or reads a d-pad, because then the program does something visible rather than only producing numbers. Memory-mapped I/O is in the README's own list of exploration targets, so the peripherals are the visible payoff of that claim.

The other two entries are performance and correctness work on the simulator's own hot path. Caching the .text section in the processor handler to avoid a linear lookup on every cycle is a real fix for a simulator that has to be fast enough to animate execution at a watchable rate. Avoiding cross-thread signal emission during 'run' is the kind of change that fixes intermittent hangs, and it tells you the execution engine runs its stepping on a worker thread and communicates with the UI through signals.

The project is published under `mortbopet` in the repository and the author is Morten Borup Petersen, who also maintains the related Gitter channel `Ripes-VSRTL`. MIT licensed, with the license file in the tree root.

Citing it, and where the published description lives

The README asks that papers and reports refer to Ripes in one of two ways: as `Morten Borup Petersen. Ripes. https://github.com/mortbopet/Ripes`, or by referring to the WCAE'21 paper on the project.

That paper is Ripes: A Visual Computer Architecture Simulator, published in the 2021 ACM/IEEE Workshop on Computer Architecture Education, pages 1 to 8, available through IEEE Xplore. The README supplies BibTeX for both a misc entry for the repository and an inproceedings entry for the paper, so citing this properly is a copy-paste job rather than an exercise.

The homepage is ripes.dk, and that is also the address of the experimental browser build, which makes the two hard to tell apart if you only see the URL. The repository description and the topic list are the clearer indicators of which is which.

For documentation beyond the README, `docs/` is where the real material lives, with an introduction and tutorial for first-time users and a documentation index at `docs/README.md`. The tutorial-first structure is worth noting, because it tells you the author expects people to arrive with no prior exposure to a simulated datapath, which in turn suggests the interface is usable without a computer architecture background, at least at the entry level.

One thing that is conspicuously absent from the README is any statement about which RISC-V extensions beyond the base IMC set are supported, or about custom instruction support. The microarchitectures are described as RV32IMC and RV64IMC based, which sets a reasonable expectation: this is not a tool for experimenting with novel instruction set extensions or for validating a custom decoder, it is a tool for understanding how a conventional RISC-V processor executes code.

Editorial conclusion

Ripes earns its keep in the places where intuition about a processor is wrong. Showing that a cache miss costs you a stall, that a store buffer reorders a visible memory access, or that the same assembly produces different cycle counts on a single-cycle and a pipelined design is not something a spreadsheet or a lecture slide does. It is a teaching tool first and a research sandbox second, and the interface assumes you already know what a hazard is. Two practical notes if you plan to use it. The browser version at ripes.dk is labelled Experimental, so treat it as a preview of the desktop application rather than the primary way to work. And the native build needs Qt 6.5.0 or later plus Qt Charts, which is not bundled with Qt by default and has to be selected during installation, plus CMake and libegl1-mesa-dev on Linux. The continuous release tag is the one to watch: its notes list the real development direction, and the recent entries are a real-time clock peripheral, a raster screen peripheral, an edge-capture d-pad peripheral, and a change caching the .text section to avoid a linear lookup every cycle. For citation, use the project URL or the WCAE'21 paper, both of which the README supplies as BibTeX.

Frequently asked questions

Official sources

1. License: MIT
2. mortbopet/Ripes on GitHub
3. Project website
4. README
5. Releases