zosbuilder/docs/PROMPT.md

Prompt for Building Custom Alpine Initramfs with zinit

Project Overview

Build a complete system for creating a custom initramfs based on Alpine Linux 3.22 x86_64, with zinit replacing OpenRC for process management. The initramfs will be embedded into a custom kernel and must be buildable in GitHub Actions using rootless containers (Docker/Podman).

Technical Requirements

Base System

• Alpine Version: 3.22 x86_64 miniroot as base
• Process Manager: zinit (complete OpenRC replacement - do not install OpenRC packages)
• Container Runtime: Rootless Docker/Podman compatible
• Build Tools: Include Go, Rust, standard build tools in builder container
• Target: Final vmlinuz.efi with embedded initramfs.cpio.xz

Directory Structure to Create

project-root/
├── config/
│   ├── zinit/
│   │   ├── services/          # zinit service definitions
│   │   └── zinit.conf         # main zinit configuration
│   ├── packages.list          # apk packages to install in initramfs
│   ├── sources.conf           # components to download/build (format below)
│   ├── kernel.config          # kernel config with initramfs path
│   └── modules.conf           # 2-stage module loading specification
├── scripts/
│   ├── lib/
│   │   ├── docker.sh          # container lifecycle, rootless setup
│   │   ├── alpine.sh          # miniroot extraction, apk operations
│   │   ├── components.sh      # download/build from sources.conf
│   │   ├── initramfs.sh       # assembly, aggressive cleanup, compression
│   │   ├── kernel.sh          # kernel build with embedded initramfs
│   │   └── testing.sh         # qemu/cloud-hypervisor test commands
│   ├── build.sh               # main orchestrator script
│   └── clean.sh               # cleanup all generated artifacts
├── initramfs/                 # final initramfs tree (generated)
├── components/                # component build staging (generated)
├── kernel/                    # kernel source tree (generated)
└── dist/                      # final build artifacts (generated)

Configuration File Formats

sources.conf Format

# TYPE:NAME:URL:VERSION:BUILD_FUNCTION
git:zinit:https://github.com/zdharma-continuum/zinit:main:build_zinit
release:tool:https://github.com/user/tool/releases/download/v1.0/tool-x86_64.tar.gz:v1.0:install_tool

packages.list Format

# One APK package per line, comments with #
busybox
musl
alpine-baselayout
# NO openrc packages

modules.conf Format

# STAGE:MODULE_NAME:FIRMWARE_FILES (optional)
stage1:e1000e:intel/e1000e-*.bin
stage1:ahci:
stage2:iwlwifi:intel/iwlwifi-*.ucode

Build Process Specifications

Container Requirements

• Alpine Linux base with build tools (gcc, musl-dev, go, rust, make, etc.)
• Rootless compatible: use --user $(id -u):$(id -g)
• Podman and Docker compatible
• Document subuid/subgid requirements in README
• Option to commit builder container for reuse

Initramfs Assembly Process

1. Extract Alpine 3.22 miniroot to initramfs/
2. Install packages from packages.list using apk (NO OpenRC)
3. Build/install components from sources.conf
4. Install zinit as /sbin/init
5. Copy zinit configuration from config/zinit/
6. Set up 2-stage module loading infrastructure
7. Aggressive cleanup: remove docs, locales, headers, apk cache
8. Strip and UPX all binaries in initramfs tree only
9. Create initramfs.cpio.xz

Component Build System

• Each component type (git/release) has specific build function
• Build in components/ directory, install to initramfs/
• Support custom build functions defined in components.sh
• Handle dependencies between components

Code Structure Requirements

Bash Scripting Standards

• Modular design: Each problem domain = separate sourced file
• Function naming: Prefix with domain (docker_start_container, alpine_install_packages)
• Error handling: set -euo pipefail in all scripts, script must stop on ANY error
• NO SILENT ERRORS: All commands must be verified for success
• Command echoing: Every command must be echoed with full parameter expansion before execution
• Logging: Standardized logging with timestamps and levels
• NO GLYPHS OR ICONS: Use plain text separators, titles, and lines only
• Sourcing pattern: Main script sources lib functions as needed

Command Execution Pattern

Every command must follow this pattern:

echo "Executing: command arg1 arg2 ${variable}"
command arg1 arg2 "${variable}"
if [ $? -ne 0 ]; then
    echo "ERROR: Command failed: command arg1 arg2 ${variable}"
    exit 1
fi

Section Separation Pattern

Use clear text separators like:

echo "=================================================="
echo "SECTION: Building Components"
echo "=================================================="

Function Categories Required

# docker.sh
docker_build_container()
docker_start_rootless()
docker_commit_builder()

# alpine.sh  
alpine_extract_miniroot()
alpine_install_packages()
alpine_aggressive_cleanup()

# components.sh
components_parse_sources_conf()
components_download_git()
components_download_release()
components_build_all()

# initramfs.sh
initramfs_setup_zinit()
initramfs_setup_modules()
initramfs_strip_and_upx()
initramfs_create_cpio()

# kernel.sh
kernel_download_source()
kernel_apply_config()
kernel_build_with_initramfs()

# testing.sh
testing_qemu_boot()
testing_cloud_hypervisor_boot()

Error Handling Requirements

• Strict mode: set -euo pipefail in every script
• Command verification: Check exit code of every command
• Explicit failures: No silent failures or ignored errors
• Cleanup on failure: Provide cleanup functions for partial builds
• Detailed error messages: Include command that failed and context

zinit Integration Specifications

• Replace /sbin/init completely
• Create service definitions for:
  • Stage 2 module loading
  • Network initialization
  • Serial getty (for testing)
  • Basic system services
• No OpenRC compatibility layer needed

Testing Requirements

• QEMU command with proper serial console
• cloud-hypervisor alternative command
• Serial console properly configured for zinit getty
• Boot process should reach serial login prompt

GitHub Actions Compatibility

• Rootless container execution
• No privileged operations required
• Cacheable build steps
• Artifact generation (vmlinuz.efi, build logs)

Documentation to Include

• subuid/subgid setup instructions
• Container runtime requirements
• Configuration file documentation
• Testing procedure
• GitHub Actions integration example

Deliverables

1. Complete bash script framework with all functions
2. Sample configuration files (packages.list, sources.conf, etc.)
3. Basic zinit service definitions
4. Container setup and build orchestration
5. Testing commands for QEMU/cloud-hypervisor
6. Documentation for setup and usage

Constraints

• Pure bash scripting (no Python/other languages)
• Rootless container compatible
• GitHub Actions compatible
• Reproducible builds
• No OpenRC dependencies
• Aggressive size optimization
• NO GLYPHS, ICONS, OR UNICODE DECORATIONS
• ECHO EVERY COMMAND WITH PARAMETER EXPANSION
• VERIFY EVERY COMMAND EXECUTION
• STOP ON ANY ERROR

Start by creating the complete directory structure and all bash script files with function stubs and proper sourcing patterns. Include the command echoing and error checking patterns in every function. Then implement each function systematically with strict error handling.