zosbuilder/scripts/functionlist.md

Function List - scripts/lib Library

This document provides a comprehensive description of all functions available in the scripts/lib library that are to be sourced by build scripts.

alpine.sh - Alpine Linux Operations

Core Functions

• alpine_extract_miniroot() - Downloads and extracts Alpine miniroot to target directory
• alpine_setup_chroot() - Sets up chroot environment with essential filesystem mounts
• alpine_cleanup_chroot() - Unmounts and cleans up chroot environment
• alpine_install_packages() - Installs packages from packages.list (excludes OpenRC)
• alpine_aggressive_cleanup() - Removes documentation, locales, dev files for size optimization
• alpine_configure_repos() - Configures Alpine package repositories
• alpine_configure_system() - Sets up basic system configuration (hostname, hosts, timezone)
• alpine_install_firmware() - Installs firmware packages for hardware support

common.sh - Core Utilities

Logging Functions

• log_info() - Log informational messages with timestamp and color
• log_warn() - Log warning messages with timestamp and color
• log_error() - Log error messages with timestamp and color
• log_debug() - Log debug messages (only when DEBUG=1)

Execution and System Functions

• safe_execute() - Execute commands with error handling and logging
• section_header() - Creates formatted section headers for output
• command_exists() - Check if command is available in PATH
• in_container() - Detect if running inside a container
• check_dependencies() - Verify required tools are installed

File System Operations

• safe_mkdir() - Create directories safely with error handling
• safe_rmdir() - Remove directories safely with error handling
• safe_copy() - Copy files/directories safely with error handling
• resolve_path() - Convert relative to absolute paths
• get_file_size() - Get human-readable file size
• wait_for_file() - Wait for file to exist with timeout
• cleanup_on_exit() - Cleanup function for exit traps

components.sh - ThreeFold Component Management

Component Processing

• components_parse_sources_conf() - Parse and build all components from sources.conf
• components_download_git() - Clone Git repositories with specific versions
• components_download_release() - Download pre-built release binaries
• components_process_extra_options() - Handle rename/extract options for components
• components_build_component() - Build component using specified build function

Build Environment

• components_setup_rust_env() - Configure Rust environment for musl builds

Component-Specific Build Functions

• build_zinit() - Build zinit init system from source (Rust)
• build_rfs() - Build rfs (rootfs) from source (Rust)
• build_mycelium() - Build mycelium networking from source (Rust, subdirectory)
• install_rfs() - Install pre-built rfs binary
• install_corex() - Install pre-built corex binary

Verification and Cleanup

• components_verify_installation() - Verify all components were installed correctly
• components_cleanup() - Clean build artifacts

docker.sh - Container Runtime Management

Runtime Detection and Setup

• docker_detect_runtime() - Detect available container runtime (Docker/Podman)
• docker_verify_rootless() - Verify rootless container setup works
• docker_check_capabilities() - Check container runtime capabilities
• docker_setup_rootless() - Setup rootless environment (subuid/subgid)

Container Image Management

• docker_build_container() - Build container image with build tools
• docker_create_dockerfile() - Create optimized Dockerfile for build environment
• docker_commit_builder() - Commit container state for reuse
• docker_cleanup() - Clean up container images

Container Execution

• docker_start_rootless() - Start rootless container for building
• docker_run_build() - Run build command in container with proper mounts

initramfs.sh - Initramfs Assembly

Core Assembly Functions

• initramfs_setup_zinit() - Setup zinit as init system (replaces OpenRC completely)
• initramfs_install_init_script() - Install critical /init script for initramfs boot
• initramfs_setup_modules() - Setup 2-stage module loading with dependencies

Module Management

• initramfs_resolve_module_dependencies() - Recursively resolve module dependencies using modinfo
• initramfs_create_module_scripts() - Create stage1/stage2 module loading scripts for zinit

Optimization and Packaging

• initramfs_strip_and_upx() - Strip debug symbols and UPX compress binaries for size optimization
• initramfs_create_cpio() - Create final compressed initramfs archive (xz/gzip/zstd/uncompressed)

Validation and Testing

• initramfs_validate() - Validate initramfs contents and structure
• initramfs_test_archive() - Test initramfs archive integrity

kernel.sh - Kernel Building

Source Management

• kernel_download_source() - Download Linux kernel source code from kernel.org
• kernel_apply_config() - Apply kernel configuration with embedded initramfs path
• kernel_modify_config_for_initramfs() - Modify kernel config for embedded initramfs support

Build Functions

• kernel_build_with_initramfs() - Build kernel with embedded initramfs (complete process)
• kernel_build_modules() - Build kernel modules for initramfs inclusion

Cleanup

• kernel_cleanup() - Clean kernel build artifacts (with option to keep source)

testing.sh - Virtualization Testing

QEMU Testing

• testing_qemu_boot() - Test kernel boot with QEMU (multiple modes: basic/serial/interactive)
• testing_qemu_basic_boot() - Basic automated QEMU boot test with timeout
• testing_qemu_serial_boot() - QEMU serial console test for debugging
• testing_qemu_interactive_boot() - Interactive QEMU session (no timeout)

Cloud Hypervisor Testing

• testing_cloud_hypervisor_boot() - Test with cloud-hypervisor VMM
• testing_cloud_hypervisor_basic() - Basic cloud-hypervisor test with timeout
• testing_cloud_hypervisor_serial() - cloud-hypervisor serial console test

Analysis and Orchestration

• testing_analyze_boot_log() - Analyze boot logs for success/failure indicators
• testing_run_all() - Run comprehensive test suite (QEMU + cloud-hypervisor)

Usage Notes

Function Availability

All functions are exported for sourcing and can be called from any script that sources the respective library file. The common pattern is:

# Source the library
source "${SCRIPT_DIR}/lib/common.sh"
source "${SCRIPT_DIR}/lib/alpine.sh"
# ... other libraries as needed

# Use the functions
alpine_extract_miniroot "/path/to/target"
components_parse_sources_conf "/path/to/sources.conf" "/path/to/components"

Error Handling

All functions follow consistent error handling patterns:

• Return non-zero exit codes on failure
• Use safe_execute() for command execution
• Provide detailed logging via log_*() functions
• Clean up resources on failure

Dependencies

Functions have dependencies on:

• External tools (checked via check_dependencies())
• Other library functions (noted in function descriptions)
• Configuration files and environment variables
• Proper directory structures

Configuration

Most functions respect environment variables for configuration:

• DEBUG=1 enables debug logging
• ALPINE_VERSION, KERNEL_VERSION set versions
• RUST_TARGET configures Rust builds
• Various *_DIR variables set paths