herolib-virt

Virtualization and containerization tools for building, managing, and deploying containers, virtual machines, and filesystem layers.

Features

• Buildah: OCI/Docker image building with a fluent builder pattern API
• Nerdctl: Container lifecycle management with containerd
• RFS: Remote filesystem mounting and layer management
• QCOW2: Disk image creation and management with snapshot support
• Cloud Hypervisor: Virtual machine creation and lifecycle management
• Cross-Platform: Works across Windows, macOS, and Linux
• Rhai Integration: Full support for Rhai scripting language (optional feature)
• Error Handling: Comprehensive error types and handling

Installation

Add to your Cargo.toml:

[dependencies]
herolib-virt = { path = "../virt", features = ["rhai"] }

Or install the library:

./install.sh

Building

./build.sh

Usage

Rust API

use herolib_virt::buildah;

// Create a container builder
let mut builder = buildah::Builder::new("mybuilder", "alpine:latest")?;
builder.run("apk add curl")?;
let image = builder.commit("myimage")?;

Rhai Scripting

When the rhai feature is enabled, you can use the virt module in Rhai scripts:

// Create a container using Buildah
let builder = bah("mybuilder", "alpine:latest");
builder.run("apk add curl");
builder.commit("myimage");

// Create a disk image
qcow2_create("/tmp/disk.qcow2", 20);

// Create a VM
let vm_spec = #{
    id: "test-vm",
    firmware_path: "/usr/share/OVMF/CLOUDHV.fd",
    disk_path: "/tmp/disk.qcow2",
    vcpus: 2,
    memory_mb: 2048
};
let vm = cloudhv_vm_create(vm_spec);

Modules

Buildah (Container Image Building)

Build OCI/Docker container images with a fluent builder API.

Key Types

• Builder: Main builder type for creating container images
• BuildahError: Error type for Buildah operations

Examples

See Rhai examples under rhaiexamples/buildah/ for detailed examples.

Nerdctl (Container Management)

Manage containers with containerd/nerdctl.

Key Types

• Container: Container representation
• ContainerStatus: Container status enumeration
• NerdctlError: Error type for Nerdctl operations

Examples

See Rhai examples under rhaiexamples/nerdctl/ for detailed examples.

RFS (Remote Filesystem)

Mount and manage remote filesystems and pack/unpack filesystem layers.

Key Types

• RfsBuilder: Builder for filesystem operations
• Mount: Mount point representation
• MountType: Filesystem type enumeration
• RfsError: Error type for RFS operations

Examples

See Rhai examples under rhaiexamples/rfs/ for detailed examples.

QCOW2 (Disk Image Management)

Create and manage QCOW2 disk images with snapshot support.

Key Types

• Qcow2Manager: Manager for QCOW2 operations
• Qcow2Error: Error type for QCOW2 operations

Examples

See Rhai examples under rhaiexamples/qcow2/ for detailed examples.

Cloud Hypervisor (VM Management)

Manage virtual machines using Cloud Hypervisor.

Key Types

• CloudHvManager: Manager for Cloud Hypervisor operations
• CloudHvError: Error type for Cloud Hypervisor operations

Examples

See Rhai examples under rhaiexamples/cloudhv/ for detailed examples.

Rhai Examples

The rhaiexamples/ directory contains comprehensive examples for all modules:

• buildah/ - Container image building examples
• nerdctl/ - Container management examples
• rfs/ - Remote filesystem examples
• qcow2/ - QCOW2 disk image examples
• cloudhv/ - Cloud Hypervisor VM examples
• kubernetes/ - Kubernetes cluster management examples

Features

• rhai (default): Enable Rhai scripting support
• full: Enable all features

Platform Support

• Linux (primary)
• macOS
• Windows

Dependencies

Core dependencies:

• tokio - Async runtime
• serde - Serialization framework
• anyhow - Error handling
• thiserror - Error types

Optional dependencies (with rhai feature):

• rhai - Scripting language support

Documentation

Generate documentation:

cargo doc --no-deps --open

License

Apache 2.0

Repository

https://forge.ourworld.tf/lhumina_code/herolib