# 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:
```sh
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:
```sh
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:
```sh
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:
```text
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:
```sh
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
```sh
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:
```text
/lib
/lib64
/usr/lib64
```
The extracted tree keeps Linux's usual layout:
```text
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 `usr/include` and a `libc.so`, `libc.so.6`, or
`libc.a` somewhere under `lib`, `lib64`, `usr/lib`, or `usr/lib64`. Development
headers and libraries must already be installed inside the guest image you are
extracting from.