qemu

This crate provides an installer for QEMU binaries. You can use it to install QEMU system and user mode emulators and use them in your code.

Table of Contents

• qemu
  • Table of Contents
  • Dependencies
    • Install Required Dependencies on Ubuntu
    • Install Required Dependencies on Fedora
  • Installation
  • Usage
    • Rust-executable wrapper for user emulator
      • Cargo.toml
  • Feature Flags
    • Just install qemu-x86_64 usermode emulator with default options
    • Install an optimized qemu-x86_64 usermode emulator
    • Install qemu-system-arm emulator with customized options
  • Contributing

Dependencies

To install this crate, you need all the dependencies required to build QEMU for your system. There are some packages that are always required. The updated list can be found here. As of QEMU 7.3, you can install the required packages with the distro-specific commands below. If you encounter any other problems building, try checking the build instructions for your platform. If you are unable to fix your issue, please file an issue here!

Install Required Dependencies on Ubuntu

$ sudo apt-get install git libglib2.0-dev libfdt-dev \
    libpixman-1-dev zlib1g-dev ninja-build

Install Required Dependencies on Fedora

$ sudo dnf install git glib2-devel libfdt-devel \
    pixman-devel zlib-devel bzip2 ninja-build python3

Installation

To install QEMU binaries (see feature flags for direction on customizing the build):

cargo install qemu --features=binaries,lto,plugins

Usage

See the feature flags section for information on enabling targets, but once you have an installation, you can use the binary!

Rust-executable wrapper for user emulator

There are crates available for binary distributions of each qemu program, and they all essentially implement this pattern. This executable will run qemu-aarch64 as a wrapper and pass through command line args and stdio to the executable. Much more complicated things are possible now that we have a binary available straight in Rust though, so the sky is the limit!

Cargo.toml

[package]
name = "qemu-aarch64"
version = "0.1.0"
edition = "2021"
description = "QEMU binary installer for qemu-aarch64"
license = "MIT"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
[dependencies]
memfd-exec = "2.1.0"
qemu = { version = "8.2.2", features = ["qemu-aarch64"] }

use memfd_exec::{MemFdExecutable, Stdio};
use qemu::QEMU_AARCH64_LINUX_USEr;

use std::env::args;

fn main() {
    let qemu = QEMU_AARCH64_LINUX_USEr;
    let mut args: Vec<String> = args().collect();
    args.remove(0);
    MemFdExecutable::new("qemu-aarch64", qemu)
        .args(args)
        .stdin(Stdio::inherit())
        .stdout(Stdio::inherit())
        .stderr(Stdio::inherit())
        .spawn()
        .expect("Failed to start qemu process")
        .wait()
        .expect("Qemu process failed");
}

Feature Flags

The feature flags of this crate provide an interface to the configure options for QEMU. By default, all flags are set just as QEMU's configure script sets them with the exception of targets (see Important Note). Some examples of how to configure this crate as a dependency:

Just install qemu-x86_64 usermode emulator with default options

This will make the qemu-x86_64 binary available.

qemu = { version = "8.2.2", features = ["qemu-x86_64"] }

Install an optimized qemu-x86_64 usermode emulator

This will also make the qemu-x86_64 binary available, but will strip and optimize it with lto.

qemu = { version = "8.2.2", features = ["qemu-x86_64", "lto", "strip"]

Install qemu-system-arm emulator with customized options

We can also selectively opt in to features. Use this only if you really need it! These are all enabled by default if they are available anyway! See the qemu documentation about configure options for more details.

Contributing

Contributions are welcome for any reason!