# dustbox-rs: a Rust DOS emulator that is honest about being unfinished

> dustbox-rs is an early-stage x86 emulator written in Rust, aimed at running MS-DOS games on Windows, macOS, and Linux. The README openly admits it is incomplete and points users to dosbox-x for a production-ready alternative.

**martinlindhe/dustbox-rs** — DOS emulator (semi-abandoned)

- Repository: https://github.com/martinlindhe/dustbox-rs
- Website: https://martinlindhe.github.io/dustbox-rs/
- Stars: 50 · Forks: 6
- Language: Rust
- License: MIT
- Published: 2026-08-17 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/martinlindhe-dustbox-rs

## What dustbox-rs actually is

dustbox-rs is a PC x86 emulator written in Rust, with the stated goal of running MS-DOS games on Windows, macOS, and Linux. The README calls it "Early WIP" and says it "runs a some demos". That is the entire scope. It is not a DOSBox replacement, and the author says so directly: "If you are looking for a more complete dos emulator, I suggest you check out dosbox-x." The project is semi-abandoned, as the description notes, and the README's status table from June 2019 confirms that most components are below 10% complete. For an engineer evaluating this, the first thing to understand is that this is a learning project or a foundation for further work, not a usable product.

## The component status table is the real specification

The README contains a rough status table dated June 2019. It lists 16-bit CPU at 95%, 32-bit CPU at 20%, FPU at 5%, PIT and PIC at 1% each, MS-DOS simulation at 5%, keyboard at 1%, mouse at 25%, CGA/EGA/VGA at 5% each, and sound, CD-ROM, and hard drive as not started. That table is the most concrete information available about the emulator's capabilities. It tells you that the core CPU is the most developed part, but interrupts are incomplete. That means any DOS program relying on BIOS or DOS interrupts will fail. The table also shows that the graphics and sound subsystems are essentially absent, so even if a demo runs, you will not get proper video or audio output. This is a project where the README's honesty is more useful than any feature list.

## How the emulator is structured: debugger and front-end

The repository layout shows two packages: dustbox_debugger and dustbox_frontend. The debugger is launched with cargo run --package dustbox_debugger, and you interact with it through an input box, with 'help' to get started. The front-end takes a path to a DOS executable: cargo run --package dustbox_frontend path-to-dos-executable. That separation suggests the emulator core is shared, with a text-based debugger for development and a graphical front-end for running programs. The README does not describe the internal architecture beyond that, so the data flow is not documented. But the existence of two entry points implies that the CPU and device emulation are separate from the UI layer, which is a reasonable design for an emulator. Still, without more documentation, you have to infer the architecture from the code.

## Getting it running: dependencies and build commands

The README lists dependencies for three platforms. On Ubuntu, you need nasm, libgtk-3-dev, libcairo2-dev, libpango1.0-dev, libatk1.0-dev, gdk-pixbuf2.0-dev, libsdl2-dev, and libsdl2-gfx-dev. On Windows, it suggests vcpkg install sdl2 gtk plus scoop install nasm. On macOS, brew install nasm sdl2 sdl2_gfx. The build itself is standard cargo: cargo test --all for normal tests, and cargo run --package dustbox_debugger or cargo run --package dustbox_frontend. The front-end requires a DOS executable path, but the README does not specify which format or how to obtain one. The dependencies include GTK and Cairo, which are unusual for an emulator, suggesting the front-end uses GTK for its UI rather than SDL alone. That adds installation friction, especially on Windows where vcpkg and scoop are needed. If you are on a minimal system, the dependency list is a hurdle.

## The tests: normal and expensive with external repo

The README describes two test levels. Normal tests run with cargo test --all. There are also expensive tests that generate render demo images, and they require checking out the dos-software-decoding repository in the parent directory, then running cargo test --release -- --ignored. That external dependency means the test suite is not self-contained. The dos-software-decoding repo presumably contains DOS executables or disk images used to test the emulator. This is a concrete constraint: if you want to run the full test suite, you must clone another repository with a specific name and location. The README gives the command: cd .. && git clone --depth 1 https://github.com/martinlindhe/dos-software-decoding, then cargo test --release -- --ignored. This is a real workflow, but it is brittle. If the external repo changes, the tests may break. It also means the project's test coverage is tied to a separate project that may have its own maintenance issues.

## A genuine failure mode: the 16-bit CPU is not complete

The status table says 16-bit CPU is 95% complete, but interrupts are incomplete. In a DOS emulator, interrupts are not a peripheral feature; they are the primary mechanism for DOS and BIOS services. Programs use INT 21h for file I/O, INT 10h for video, INT 16h for keyboard. If those are incomplete, most real DOS games will not run. The README also lists MS-DOS simulation at 5%, which means the command.com environment and DOS API are largely absent. So even if the CPU executes instructions correctly, the software environment is missing. This is the wrong tool for any game that expects a working DOS. The author acknowledges this by pointing to dosbox-x. For an engineer, this is the key limitation: the project is not a viable emulator for its stated goal yet.

## The alternative: dosbox-x and the difference in approach

The README explicitly recommends dosbox-x as a more complete DOS emulator. The difference in approach is significant. dosbox-x is a fork of DOSBox, a mature C++ emulator with decades of development, supporting dynamic recompilation, full VGA/SVGA emulation, Sound Blaster and other audio cards, and a configuration system. dustbox-rs is written in Rust, which offers memory safety and modern tooling, but it is at a fraction of the feature completeness. The author's own recommendation is the clearest comparison: if you want to run games, use dosbox-x. If you want to work on a Rust emulator, dustbox-rs is a starting point, but you would be building most of the emulation from scratch. The trade-off is between a production-ready but older codebase and a modern language with a long way to go.

## Maintenance and license implications

The repository is marked as semi-abandoned, and the README's status is from June 2019. There are no recent releases listed, and the last push date is unknown. That means the project has not seen active development for a significant period. The license is MIT, which is permissive and allows commercial use, modification, and redistribution, with attribution. For an engineer, adopting this as a dependency would require forking and maintaining it yourself. The MIT license is a positive: you can take the code and build on it without legal friction. But the maintenance cost is high because you would be responsible for fixing the incomplete components, and the lack of recent activity suggests upstream fixes are unlikely. The test suite's dependency on an external repo adds to the maintenance burden, as you would need to monitor that repo as well.

## Conclusion

dustbox-rs is for developers who want to explore or contribute to a Rust-based DOS emulator and are comfortable with incomplete components like interrupts, video, and sound. It is not for users who want to play MS-DOS games; they should use dosbox-x. Before adopting it, verify the current commit state, run the provided tests, and check whether the 16-bit CPU coverage meets your needs, since the README reports only 95% with incomplete interrupts.

## FAQ

### What is a dustbox in the dustbox-rs repository?

It is an early work-in-progress PC x86 emulator written in Rust, with the goal of easily running MS-DOS games on Windows, macOS and Linux. In its current state it runs a few demos, and the repository description calls it semi-abandoned.

### How do I build and run the dustbox-rs emulator?

Start the debugger with `cargo run --package dustbox_debugger` and drive it from its input box, where help gets you started, or launch the front end with `cargo run --package dustbox_frontend path-to-dos-executable`. The Makefile wraps the debugger as run and run-release.

### What system dependencies does dustbox-rs need?

Three separate lines in the README. Ubuntu uses apt to install nasm plus the GTK, cairo, pango, atk, gdk-pixbuf and SDL2 development packages, Windows uses vcpkg install sdl2 gtk with scoop install nasm, and macOS uses brew install nasm sdl2 sdl2_gfx.

### How complete is the dustbox-rs emulator?

The status table is dated June 2019: the 16-bit CPU is at 95% with interrupts incomplete, the 32-bit CPU at 20%, the mouse at 25%, and the FPU, MS-DOS and video modes between 1% and 5%. EMS/XMS, sound, CD-ROM and hard drive support are marked not started.

## Sources

- [Official documentation](https://martinlindhe.github.io/dustbox-rs/)
- [Official README](https://github.com/martinlindhe/dustbox-rs#readme)
- [Project repository](https://github.com/martinlindhe/dustbox-rs)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/martinlindhe-dustbox-rs