vmrunner-sysroot

Helpers for extracting compiler sysroots and other files from VM disk images.

The crate uses bindgen-generated libguestfs bindings directly rather than mounting guest filesystems with the host kernel. Building this crate requires the libguestfs development headers plus libclang for bindgen. Disk images are opened read-only by default, guest filesystems are mounted read-only, and filesystem parsing happens inside the libguestfs appliance instead of in the host kernel.

libguestfs does not boot the guest OS, so the guest CPU architecture usually does not need to match the host. Any disk image format and guest filesystem supported by the installed libguestfs/QEMU stack can be used. Pass --image-format raw, --image-format qcow2, etc. to avoid format probing; --image-format auto asks libguestfs to autodetect the format.

Generic copy-out

Copy arbitrary absolute guest paths out of a QEMU/libguestfs-readable image:

cargo run -p vmrunner-sysroot -- \
  copy-out \
  --image root.qcow2 \
  --image-format qcow2 \
  --path /etc/os-release \
  --path /usr/include \
  --output target/guest-copy

By default the command uses libguestfs inspection to find and mount the guest filesystems. If inspection cannot identify the guest, pass one or more manual mounts using DEVICE[:MOUNTPOINT[:OPTIONS[:FSTYPE]]] syntax:

cargo run -p vmrunner-sysroot -- \
  copy-out \
  --image root.raw \
  --image-format raw \
  --mount /dev/sda3:/ \
  --path /usr/include \
  --output target/guest-copy

Manual mount options are forced to include ro. If you need to steer which QEMU binary or backend libguestfs uses, prefer libguestfs' standard environment variables such as LIBGUESTFS_HV and LIBGUESTFS_BACKEND.

BSD sysroot from a QEMU disk image

BSD sysroot extraction is optional. Enable the bsd feature to expose the library module and CLI subcommand:

cargo run -p vmrunner-sysroot --features bsd -- \
  bsd \
  --target aarch64-unknown-freebsd \
  --image target/vmrunner-qcow2-imag/freebsd.qcow2 \
  --image-format qcow2 \
  --output-parent target/vmrunner-sysroot

The BSD sysroot special case copies /usr/include and /usr/lib out through the libguestfs API. The extracted tree is normalized to:

target/vmrunner-sysroot/freebsd-aarch64/
  usr/include/...
  lib/...

/usr/lib from the guest becomes lib in the output. FreeBSD sysroots are validated for the startup objects and libc.a; other BSD triples use a generic usr/include plus lib directory check.

BSD output directories are derived from the Rust target OS and architecture, so x86_64-unknown-freebsd becomes freebsd-x86_64, x86_64-unknown-openbsd becomes openbsd-x86_64, and so on.

If libguestfs inspection cannot find the root filesystem, pass one or more manual mounts:

cargo run -p vmrunner-sysroot --features bsd -- \
  bsd \
  --target x86_64-unknown-freebsd \
  --image FreeBSD.qcow2 \
  --mount /dev/sda3:/ \
  --output-parent target/vmrunner-sysroot

Linux sysroot from a QEMU disk image

cargo run -p vmrunner-sysroot -- \
  linux \
  --target x86_64-unknown-linux-gnu \
  --image ubuntu.qcow2 \
  --image-format qcow2 \
  --output-parent target/vmrunner-sysroot

The Linux sysroot special case copies required /usr/include and /usr/lib paths, plus optional library directories when present:

/lib
/lib64
/usr/lib64

The extracted tree keeps Linux's usual layout:

target/vmrunner-sysroot/linux-x86_64-gnu/
  usr/include/...
  usr/lib/...
  lib/...        # if present in the guest
  lib64/...      # if present in the guest
  usr/lib64/...  # if present in the guest

Linux sysroots are validated for libc headers plus a libc.so, libc.so.6, or libc.a somewhere under lib, lib64, usr/lib, or usr/lib64. Cloud images that only contain runtime libc files must be updated before extraction, for example by producing a mkosi image with the required development packages.