refactor(libkrun): libkrun API migration (oomol-lab#79)

Author: ihexon

README.md

@@ -1,98 +1,135 @@
 # revm
 
-English | [中文](./README_zh.md) 
+A lightweight Linux VM launcher for macOS, powered by [libkrun](https://github.com/containers/libkrun) and Apple's Hypervisor.framework. Launch a Linux shell in under a second.
 
+## Features
 
-`revm` helps you quickly launch Linux VMs / Containers, lightning fast
+- **Fast startup** - Enter a Linux shell in ~1 second, no heavy VM overhead
+- **Zero configuration** - No system modifications, no daemons, just run
+- **Docker/Podman compatible** - Full Docker CLI compatibility via built-in Podman
+- **Two execution modes** - Rootfs mode for direct Linux execution, Container mode for Docker workflows
+- **Disk mounting** - Mount virtual disk images (ext4/btrfs/xfs) into the guest
+- **Directory sharing** - Share host directories with the guest via VirtIO-FS
+- **Multi-terminal** - Attach multiple terminals to a running instance via SSH
+- **Proxy passthrough** - Inherit host proxy settings in the guest
 
----
+## Requirements
 
-## ✨ Features
+- macOS 13.1+ (Ventura or later)
+- Apple Silicon (ARM64)
 
-- ⚡ **Lightweight**: enter a Linux shell within a second, start container engine (podman) in one second
-- 🧹 **Clean**: does not modify any configuration on your machine
-- 🐳 **Container compatible**: 100% compatible with the Docker CLI ecosystem
-- 📦 **Flexible execution**: Rootfs mode and Container mode
-- 💽 **Disk mounting**: automatically mount external virtual disk files (multiple formats: ext4/btrfs/xfs)
-- 📂 **Directory mounting**: supports mounting host files into the VM
-- 🖥 **Multiple terminals**: attach to running instances at any time to execute any command
+## Installation
 
----
+```bash
+# Download the latest release
+wget https://github.com/ihexon/revm/releases/latest/download/revm.tar.zst
 
-## 🚀 Quick Start
+# Remove quarantine attribute (required for downloaded binaries)
+xattr -d com.apple.quarantine revm.tar.zst
 
-### Quick install
-```shell
-$ wget https://github.com/ihexon/revm/releases/latest/download/revm.tar.zst
-$ tar -xvf revm.tar.zst
-$ ./out/bin/revm --help # help message
-```
+# Extract
+tar -xvf revm.tar.zst
 
-if you download tar from release or github action(head build), remember to:
-```shell
- xattr -d com.apple.quarantine revm.tar.zst
+# Run
+./out/bin/revm --help
 ```
 
-### Container mode
-Container mode requires specifying an image file as the container storage area. Use `--data-storage` to reuse & generate image files (ext4 format)
-```shell
-revm docker-mode --data-storage ~/data.disk
+## Quick Start
+
+### Rootfs Mode
+
+Run commands directly in a Linux rootfs:
+
+```bash
+# Download Alpine Linux rootfs
+mkdir alpine && cd alpine
+wget -qO- https://dl-cdn.alpinelinux.org/alpine/v3.21/releases/aarch64/alpine-minirootfs-3.21.3-aarch64.tar.gz | tar -xz
+cd ..
+
+# Launch a shell
+revm rootfs-mode --rootfs ./alpine -- /bin/sh
+
+# Or run a specific command
+revm rootfs-mode --rootfs ./alpine -- /bin/echo "Hello from Linux!"
 ```
 
-Set the `CONTAINER_HOST` variable (used by podman CLI) or `DOCKER_HOST` (used by docker CLI) to `unix:///tmp/docker_api.sock` to use docker/podman CLI commands.
+### Container Mode
+
+Run Docker/Podman containers with persistent storage:
+
+```bash
+# Start container engine (creates data.disk if not exists)
+revm docker-mode --data-storage ~/data.disk
 
-```shell
-# Docker CLI 
+# In another terminal, use Docker CLI
 export DOCKER_HOST=unix:///tmp/docker_api.sock
-docker info
+docker run --rm alpine echo "Hello from container!"
 
-# Podman CLI
-export CONTAINER_HOST=unix:///tmp/docker_api.sock 
-podman system info
+# Or use Podman CLI
+export CONTAINER_HOST=unix:///tmp/docker_api.sock
+podman run --rm alpine echo "Hello from container!"
 ```
 
-### rootfs mode
+### Attach to Running Instance
 
-Quickly run any program in rootfs
 ```bash
-# Download and extract Alpine rootfs
-mkdir alpine_rootfs
-wget -qO- https://dl-cdn.alpinelinux.org/alpine/v3.22/releases/aarch64/alpine-minirootfs-3.22.1-aarch64.tar.gz | tar -xv -C alpine_rootfs
-
-# Start the isolated environment
-revm rootfs-mode --rootfs alpine_rootfs -- /bin/sh
+# Attach a new terminal to a running VM
+revm attach ./alpine -- /bin/sh
 
-# Attach to a running instance
-revm attach ./alpine_rootfs
+# Run a command in the running VM
+revm attach ./alpine -- cat /etc/os-release
 ```
 
-# ⚙️ Advanced Usage
+## Advanced Usage
+
+### Mount Disk Images
+
+Mount ext4/btrfs/xfs disk images into the guest:
 
-## Mount image files into the guest
-```shell
-# Automatically mount data1.disk and data2.disk inside the guest at /var/tmp/mnt/
-revm rootfs-mode --rootfs alpine_rootfs \
+```bash
+# Create a disk image (if needed)
+truncate -s 10G data.disk
+
+# Mount disk images (auto-mounted at /var/tmp/mnt/...)
+revm rootfs-mode --rootfs ./alpine \
   --data-disk ~/data1.disk \
   --data-disk ~/data2.disk \
   -- /bin/sh
+```
+
+### Share Host Directories
 
-# Log output
-INFO[2025-09-09T17:34:27+08:00] mount "/Users/danhexon/data1.disk" -> "/var/tmp/mnt/Users/danhexon/data1.disk"
-INFO[2025-09-09T17:34:27+08:00] mount "/Users/danhexon/data2.disk" -> "/var/tmp/mnt/Users/danhexon/data2.disk"
+Mount host directories into the guest via VirtIO-FS:
+
+```bash
+# Mount host directory to guest path
+revm rootfs-mode --rootfs ./alpine \
+  --mount /Users/me/projects:/mnt/projects \
+  -- /bin/sh
 ```
 
-## Mount host folder into the guest
-```shell
-# Mount /Users/danhexon from the host to /tmp/hostfs/danhexon inside the guest
-revm rootfs-mode --rootfs alpine_rootfs --mount /Users/danhexon:/tmp/hostfs/danhexon -- /bin/sh
+### Proxy Passthrough
+
+Inherit the host's HTTP/HTTPS proxy settings:
+
+```bash
+revm rootfs-mode --rootfs ./alpine --system-proxy -- /bin/sh
 ```
 
+### Resource Configuration
 
-## Inherit the host's proxy settings
-Use `--system-proxy` to pass proxy settings into the guest:
-```shell
-revm rootfs-mode --rootfs alpine_rootfs --system-proxy -- /bin/sh
+```bash
+# Customize CPU and memory
+revm rootfs-mode --rootfs ./alpine \
+  --cpus 4 \
+  --memory 4096 \
+  -- /bin/sh
 ```
 
-# BUG Reports
-https://github.com/ihexon/revm/issues
+## Bug Reports
+
+https://github.com/ihexon/revm/issues
+
+## License
+
+See [LICENSE](./LICENSE) for details.