Readme

v86 emulates an x86-compatible CPU and hardware. Machine code is translated to WebAssembly modules at runtime in order to achieve decent performance. Here's a list of emulated hardware:

About V86 Lite

Documentation

How it works — Networking — Alpine Linux guest setup — Arch Linux guest setup — Windows 2000/XP guest setup — 9p filesystem — Linux rootfs on 9p — Profiling — CPU Idling

Compatibility

Here's an overview of the operating systems supported in v86:

Linux works pretty well. 64-bit kernels are not supported.
- Damn Small Linux (2.4.31 kernel) works.
- Fedora 30 works.
- All tested versions of TinyCore work.
- Buildroot can be used to build a minimal image. humphd/browser-vm and darin755/browser-buildroot have some useful scripts for building one.
- SkiffOS (based on Buildroot) can cross-compile a custom image.
- Arch Linux 32 works. See archlinux.md for building an image.
- Debian works.
- Ubuntu works up to the latest version that supported i386 (16.04 LTS or 18.04 LTS for some variants).
- Alpine Linux works. An image can be built from a Dockerfile, see tools/docker/alpine/.
- Slackware works.
- Void Linux works.
ReactOS works.
FreeDOS, Windows 1.01 and MS-DOS run very well.
KolibriOS works.
Haiku works.
Android-x86 has been tested up to 4.4-r2.
Windows 1, 3.x, 95, 98, ME, NT and 2000 work reasonably well.
- In Windows 2000 and higher the PC type has to be changed from ACPI PC to Standard PC
- There are some known boot issues (#250, #433, #507, #555, #620, #645)
Windows XP, Vista and 8 work under certain conditions (see #86, #208)
- See Windows 2000/XP guest setup
Many hobby operating systems work.
9front works.
Plan 9 doesn't work.
QNX works.
OS/2 doesn't work.
FreeBSD works.
OpenBSD works with a specific boot configuration. At the boot> prompt type boot -c, then at the UKC> prompt disable mpbios and exit.
NetBSD works only with a custom kernel, see #350.
SerenityOS works (only 32-bit versions).
SkiftOS works.

You can get some information on the disk images here: https://github.com/copy/images.

How to build, run and embed?

You need:

make
Rust with the wasm32-unknown-unknown target
A version of clang compatible with Rust
java (for Closure Compiler, not necessary when using debug.html)
nodejs (a recent version is required, v16.11.1 is known to be working)
To run tests: nasm, gdb, qemu-system, gcc, libc-i386 and rustfmt

See tools/docker/test-image/Dockerfile for a full setup on Debian or WSL.

Run make to build the debug build (at debug.html).
Run make all to build the optimized build (at index.html).
ROM and disk images are loaded via XHR, so if you want to try out index.html locally, make sure to serve it from a local webserver. You can use make run to serve the files using Python's http module.
If you only want to embed v86 in a webpage you can use libv86.js. For usage, check out the examples. You can download it from the release section.

Alternatively, to build using Docker

If you have Docker installed, you can run the whole system inside a container.
See tools/docker/exec to find the Dockerfile required for this.
You can run docker build -f tools/docker/exec/Dockerfile -t v86:alpine-3.19 . from the root directory to generate docker image.
Then you can simply run docker run -it -p 8000:8000 v86:alpine-3.19 to start the server.
Check localhost:8000 for hosted server.

Running via Dev Container

If you are using an IDE that supports Dev Containers, such as GitHub Codespaces, the Visual Studio Code Remote Container extension, or possibly others such as Jetbrains' IntelliJ IDEA, you can setup the development environment in a Dev Container.
Follow the instructions from your development environment to setup the container.
Run the Task "Fetch images" in order to download images for testing.

Testing

The disk images for testing are not included in this repository. You can download them directly from the website using:

wget -P images/ https://i.copy.sh/{linux3.iso,linux.iso,linux4.iso,buildroot-bzimage68.bin,openbsd-floppy.img,kolibri.img,windows101.img,os8.img,freedos722.img}

Run integration tests: make tests

Run all tests: make jshint rustfmt kvm-unit-test nasmtests nasmtests-force-jit expect-tests jitpagingtests qemutests rust-test tests

See tests/Readme.md for more information.

API examples

Using v86 for your own purposes is as easy as:

var emulator = new V86({
            screen_container: document.getElementById("screen_container"),
            bios: {
                url: "../../bios/seabios.bin",
            },
            vga_bios: {
                url: "../../bios/vgabios.bin",
            },
            cdrom: {
                url: "../../images/linux.iso",
            },
            autostart: true,
        });

See starter.js.

License

v86 is distributed under the terms of the Simplified BSD License, see LICENSE. The following third-party dependencies are included in the repository under their own licenses:

Credits

CPU test cases via QEMU
More tests via kvm-unit-tests
zstd support is included for better compression of state images
Berkeley SoftFloat is included to precisely emulate 80-bit floating point numbers
The jor1k project for 9p, filesystem and uart drivers
WinWorld sources of some old operating systems
OS/2 Museum sources of some old operating systems
ArchiveOS sources of several operating systems

Author

Fabian Hemmer (https://copy.sh/, copy@copy.sh)