zosbuilder/README.md

# Alpine-based Zero-OS Initramfs

Modern Alpine Linux based approach to building Zero-OS initramfs with source compilation for Zero-OS components and Alpine packages for system tools.

## Architecture Overview

This system uses:
- **Alpine Linux 3.22** as base system with latest packages
- **Rust workspace** with git subtrees for Zero-OS Rust components (zinit, mycelium, rfs)
- **Unified compilation** via `cargo build --workspace` for all Rust components
- **Alpine packages** for system tools (busybox, openssh, btrfs-progs, etc.)
- **Smart caching** with Docker layers and volumes
- **Same init flow** as original Zero-OS

## Directory Structure

```
alpine-initramfs/
├── Cargo.toml                 # Rust workspace configuration
├── build/                     # Build orchestration
│   ├── Dockerfile.alpine      # Alpine build environment
│   ├── Dockerfile.cached      # Multi-stage cached build
│   └── docker-compose.yml     # Build orchestration with caching
├── components/                # Git subtrees (Rust workspace members)
│   ├── zinit/                 # Init system (Rust subtree)
│   ├── mycelium/              # Networking layer (Rust subtree)
│   └── rfs/                   # Filesystem (Rust subtree)
├── configs/                   # Configuration files
│   ├── packages-alpine.txt    # Alpine packages to install
│   ├── kernel-version         # Kernel version to build
│   ├── kernel-config-generic  # Kernel configuration
│   ├── init                   # Init script (Alpine → zinit)
│   └── zinit/                 # Zinit service configurations
├── scripts/                   # Build scripts
│   ├── build-initramfs.sh     # Main build orchestrator
│   ├── compile-components.sh  # Compile Rust workspace
│   ├── fetch-github.sh        # Download CoreX binary
│   ├── install-packages.sh    # Install Alpine packages
│   ├── setup-initramfs.sh     # Create initramfs structure
│   ├── build-kernel.sh        # Build kernel with embedded initramfs
│   ├── build-smart.sh         # Smart build with caching
│   └── cleanup.sh             # Clean build artifacts
├── target/                    # Rust workspace build artifacts
├── output/                    # Final build outputs
│   ├── vmlinuz.efi            # Final bootable kernel
│   ├── initramfs.cpio.xz      # Generated initramfs
│   └── version.txt            # Build information
└── docs/                      # Documentation
    ├── BUILD.md               # Build process guide
    ├── OVERVIEW.md            # Architecture overview
    └── *.md                   # Additional documentation
```

## Build Flow

1. **Environment Setup**: Alpine Docker container with Rust and build tools
2. **Workspace Compilation**: Single `cargo build --workspace` for all Rust components
3. **Binary Downloads**: Download CoreX (Go binary) from GitHub releases
4. **Package Installation**: Install Alpine packages to initramfs root
5. **Initramfs Assembly**: Create filesystem structure with compiled binaries
6. **Kernel Build**: Compile kernel with embedded initramfs
7. **Output**: Generate bootable vmlinuz.efi

## Quick Start

### Full Build
```bash
# Build everything
./build.sh

# Or with Docker Compose
cd build/
docker-compose up
```

### Development Build
```bash
cd build/
# Interactive development shell
docker-compose run dev-shell

# Build entire workspace
cargo build --workspace --release --target x86_64-unknown-linux-musl

# Build specific component
cargo build -p zinit --release --target x86_64-unknown-linux-musl
cargo build -p mycelium --release --target x86_64-unknown-linux-musl
cargo build -p rfs --release --target x86_64-unknown-linux-musl
```

### Smart Build (with caching)
```bash
cd build/
docker-compose run builder  # Uses build-smart.sh automatically
```

## Key Features

- ✅ **Rust workspace** - Unified build system for all Rust components
- ✅ **Git subtrees** - Source code included, no submodule complexity
- ✅ **Single build command** - `cargo build --workspace` builds everything
- ✅ **Shared dependencies** - Consistent versions across all components
- ✅ **Smart caching** - Docker layer and volume caching for fast rebuilds
- ✅ **Alpine packages** - System tools from Alpine repositories
- ✅ **Development mode** - Full IDE support and integrated tooling
- ✅ **Same functionality** - 100% compatible with original Zero-OS

## Development

### Building Individual Components
```bash
cd build/
docker-compose run dev-shell

# Inside container - workspace build:
cargo build --workspace --release --target x86_64-unknown-linux-musl

# Or build specific packages:
cargo build -p zinit --release --target x86_64-unknown-linux-musl
cargo build -p mycelium --release --target x86_64-unknown-linux-musl
cargo build -p rfs --release --target x86_64-unknown-linux-musl
```

### Cleanup
```bash
# Clean all build artifacts
./scripts/cleanup.sh
```

### Cache Management
Smart build uses Docker volumes for caching:
- `build-cache`: Build state markers
- `source-cache`: Downloaded sources
- `kernel-cache`: Kernel builds
- `target-cache`: Rust workspace build artifacts

### Updating Components
Update git subtree components:
```bash
# Update zinit to latest
git subtree pull --prefix=components/zinit https://github.com/threefoldtech/zinit.git master --squash

# Update mycelium to latest
git subtree pull --prefix=components/mycelium https://github.com/threefoldtech/mycelium.git master --squash

# Update rfs to latest
git subtree pull --prefix=components/rfs https://github.com/threefoldtech/rfs.git master --squash
```