x86-native

x86-native is a cross-platform native Rust library for building x86 machine hosts without a browser, DOM, WebAssembly runtime or web frontend. The package name on crates.io is x86-native; the Rust library target remains x86, so applications use use x86::....

Project status: the native resource and machine-host API is implemented and tested. ExecutionBackend is the stable boundary for the future CPU, memory, interrupt and device implementation. The current release does not pretend that a metadata/state loader is already a complete PC emulator.

Languages

The documentation index contains the API map, examples, architecture diagrams, console screenshots and release notes.

Install from Cargo

Add the package to your application:

[dependencies]
x86-native = "0.1"

Then import the library target as x86:

use x86::{Image, ImageKind, Machine, MachineConfig};

fn main() -> x86::Result<()> {
    let mut machine = Machine::new(
        MachineConfig::default().with_ram_bytes(512 * 1024 * 1024),
    );

    machine.set_disk(Image::from_file(ImageKind::RawDisk, "disk.img")?)?;
    println!("machine status: {:?}", machine.status());
    Ok(())
}

The package is designed for stable Rust and native targets supported by Cargo. Run cargo add x86-native or edit Cargo.toml manually as shown above.

Features

For a strictly offline build:

cargo build --no-default-features

Main API

The Image type represents BIOS, VGA BIOS, raw disks, ISO images, kernels, initrds, bootloaders and memory-backed resources. It supports local file loading, SHA-256 calculation and checksum verification.

Resource and Bootloader provide a single interface for local paths, in-memory bytes and optional HTTP(S) URLs. SavedState validates v86-compatible state headers, metadata, buffer counts, memory size and compressed state data.

MachineConfig describes RAM, VGA memory, CPU frequency hints, command line and console mode. Machine attaches the machine resources and exposes prepare, run and stop. ExecutionBackend is a platform-neutral trait for connecting the actual native CPU/device engine.

use x86::{Bootloader, Image, ImageKind, Machine, MachineConfig, Resource, SavedState};

fn main() -> x86::Result<()> {
    let mut machine = Machine::new(
        MachineConfig::default()
            .with_ram_bytes(512 * 1024 * 1024)
            .with_command_line("rw console=ttyS0"),
    );

    machine.set_bios(Image::from_file(ImageKind::Bios, "seabios.bin")?)?;
    machine.set_vga_bios(Image::from_file(ImageKind::VgaBios, "vgabios.bin")?)?;
    machine.set_disk(Image::from_file(ImageKind::RawDisk, "disk.img")?)?;
    machine.set_saved_state(SavedState::from_file("state.bin.zst")?);
    machine.set_bootloader(Bootloader::load(Resource::url(
        "https://example.org/bootloader.bin",
    ))?);

    println!("state: {:?}", machine.status());
    Ok(())
}

Native console

Build and launch the terminal application:

cargo run --bin x86-console

The console is a normal native process. It does not start a web server or require a browser:

x86> load bios seabios.bin
x86> load vga-bios vgabios.bin
x86> load disk disk.img
x86> load state arch_state-v3.bin.zst
x86> load bootloader https://example.org/bootloader.bin
x86> info
x86> checksum state
x86> prepare
x86> run
x86> quit

prepare and run return a typed BackendUnavailable error until an ExecutionBackend is attached. This is intentional: the library never reports a guest as running when no CPU/device backend exists.

Architecture

The source diagram is available as docs/assets/architecture.mmd. The host layer is platform-neutral; platform-specific console, filesystem and networking adapters remain outside the core API.

Releases

The GitHub Releases page contains versioned native artifacts and source packages. The release workflow is configured to build Linux, macOS Intel, macOS Apple Silicon and Windows artifacts when a version tag is pushed.

Build from source

git clone https://github.com/illussioon/x86.git
cd x86
cargo check
cargo test
cargo package
cargo run --bin x86-console

For native release builds:

cargo build --release

License

Licensed under either of BSD-2-Clause or MIT, at your option.

References

The API follows standard Cargo package conventions 1 and uses the repository's native Rust implementation as the source of truth 2.