librealmachine - fake a machine

Boot a transient virtual machine based on the host system.

C++ port of the Go project fakemachine.

Made for ferdiOS/build-tools.

Features

• Mount host volumes into the VM
• Create and expose disk images
• Configurable memory, CPU count, and sector size
• Scratch storage (tmpfs or disk-backed)
• Environment variable propagation with overrides
• Command execution inside VM
• Built-in integration test suite
• KVM based

Installation

cmake -Bbuild -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/ .
sudo make -Cbuild -j4 install

Dependencies

ferdiOS libraries:

• https://codeberg.org/ferdios/libcpiocpplame
• https://codeberg.org/ferdios/libflogger
• https://codeberg.org/ferdios/libshellescape

generic libraries:

sudo apt install -y pkg-config zlib1g-dev libzstd-dev liblzma-dev libcli11-dev

Dependencies: runtime

sudo apt install -y qemu-system-x86 busybox

CMake Integration

After install:

find_package(realmachine REQUIRED)
target_link_libraries(your_target PRIVATE realmachine::realmachine)

API usage

See tests/test.cpp

fakemachine::Machine

Main methods:

• run(command)
• run_in_machine_with_args(args)
• create_image(path, size)
• add_volume(path)
• add_volume_at(host, guest)
• set_memory(mb)
• set_num_cpus(n)
• set_scratch(size, path)
• set_sector_size(size)
• set_environ(env)

CLI Usage

Run a command inside a VM:

realmachine echo hello

Mount a directory:

realmachine -v /host/data:/data ls /data

Create and expose an image:

realmachine -i disk.img:1G bash

Increase memory and CPU count:

realmachine -m 4096 -c 4 bash

Enable verbose boot output:

realmachine --show-boot bash

Unit tests

cmake -Bbuild -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTS=1 .
sudo make -Cbuild -j4 install

# and run it
cd tests
../build/tests/realmachine_tests

License

Apache 2.0, same as original (fakemachine) project.