# 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`:

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

Or install the library:

```bash
./install.sh
```

## Building

```bash
./build.sh
```

## Usage

### Rust API

```rust
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:

```rhai
// 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 `rhaiexamples/01_buildah.rhai` 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 `rhaiexamples/02_nerdctl.rhai` 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 `rhaiexamples/03_rfs.rhai` 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 `rhaiexamples/04_qcow2.rhai` 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 `rhaiexamples/05_cloudhv.rhai` for detailed examples.

## Rhai Examples

The `rhaiexamples/` directory contains comprehensive examples for all modules:

- `01_buildah.rhai` - Container image building examples
- `02_nerdctl.rhai` - Container management examples
- `03_rfs.rhai` - Remote filesystem examples
- `04_qcow2.rhai` - QCOW2 disk image examples
- `05_cloudhv.rhai` - Cloud Hypervisor VM 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:

```bash
cargo doc --no-deps --open
```

## License

Apache 2.0

## Repository

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