Building MiniOS

This guide covers the complete process for building MiniOS, including system builds, module development, and advanced configuration options.

Overview

MiniOS uses a modular build system where the operating system is constructed from individual modules in SquashFS format. Each module contains specific software packages or components, and they are loaded in a sequential order to form the complete system.

Getting Started

Prerequisites

Latest version of Debian or Ubuntu for building
Sufficient disk space (recommended: 20GB+ free space)
Internet connection for downloading packages
Required packages listed in linux-live/prerequisites.list

Installing Prerequisites

The prerequisites.list file uses condinapt format with conditional markers. Install the required packages manually:

bash

sudo apt-get update
sudo apt-get install sudo binutils debootstrap squashfs-tools xz-utils lz4 zstd xorriso mtools rsync curl
sudo apt-get install grub-efi-amd64-bin grub-pc-bin

Alternatively, you can use condinapt to process the prerequisites list if available on your system.

Build Tools

MiniOS provides two main tools for building:

minios-cmd (Recommended)

A command-line utility that simplifies configuration and initiation of builds. It provides a user-friendly interface for setting various build parameters:

Target distribution (buster, bookworm, trixie, etc.)
Architecture (amd64, i386)
Desktop environment (core, flux, xfce, lxqt)
Package variant (minimum, standard, toolbox, ultra)
Kernel options
Locale and timezone settings

Usage:

bash

# Build with default configuration
minios-cmd -d bookworm -a amd64 -de xfce -pv standard

# Build with custom options
minios-cmd -d bookworm -a amd64 -de xfce -pv toolbox -c zstd -l en_US -tz "Europe/Prague"

For detailed usage information, see the minios-cmd documentation.

minios-live (Advanced)

The core build script that orchestrates the step-by-step build process:

Setting up the build environment
Installing the base system
Integrating the chosen desktop environment
Creating the SquashFS filesystem
Configuring the boot process
Generating the bootable ISO image

Usage:

bash

# Complete build
./minios-live -

# Specific stages
./minios-live build-bootstrap
./minios-live build-chroot - build-live

For detailed usage information, see the minios-live documentation.

Project Structure

The MiniOS build system is organized as follows:

plaintext

minios-live/
├── linux-live/                 # Core scripts and build libraries
│   ├── bootfiles/              # Files and templates for booting (GRUB, ISOLINUX, EFI, etc.)
│   ├── environments/           # Environment descriptions and settings
│   ├── initramfs/              # Scripts for creating initramfs
│   ├── scripts/                # Module scripts and templates
│   ├── build-initramfs         # Script for separate initramfs build
│   ├── build.conf              # Main build configuration file
│   ├── condinapt               # Script/tool for working with package lists
│   ├── install-chroot          # Script for installing into the chroot environment
│   ├── minioslib               # Core Bash function library
│   └── prerequisites.list      # List of required packages for installation on the host for building
├── tools/                      # Auxiliary build scripts
├── minios-cmd                  # CLI utility for setting build parameters
└── minios-live                 # Main script for building MiniOS

Build Process

The build process follows a structured sequence of stages:

Build Stages Explained

build-bootstrap - Creates the minimal base system using debootstrap
build-chroot - Installs packages and configures the system in chroot environment
build-live - Creates the main SquashFS image with core system
build-modules - Builds additional SquashFS modules for extra software
build-boot - Prepares bootloader and kernel files
build-config - Generates boot configuration files
build-iso - Creates the final bootable ISO image

Build Options

Complete System Build

bash

# Full automated build
./minios-live -
# or
./minios-live build-bootstrap - build-iso

Incremental Builds

bash

# Run only bootstrap stage
./minios-live build-bootstrap

# Run from chroot to live stages
./minios-live build-chroot - build-live

# Run from modules to completion
./minios-live build-modules -

# Build only ISO from existing data
./minios-live build-iso

Configuration System

Build Configuration Files

Main Configuration: `linux-live/build.conf`

This is the primary configuration file that defines:

Distribution settings: Target distribution (buster, bookworm, trixie, sid)
Architecture: amd64, i386, i386-pae (bookworm and earlier only; trixie and sid support amd64 only)
Desktop environment: core, flux, xfce, lxqt
Package variant: minimum, standard, toolbox, ultra
Compression: xz, lzo, gz, lz4, zstd
Kernel settings: type, AUFS support, DKMS compilation
Locale settings: language, timezone, keyboard layout

Runtime Configuration: `minios_build.conf`

Generated automatically during the build process and contains runtime-specific settings for the chroot environment.

Package Variants

MiniOS supports different package variants that determine which software is included:

minimum: Essential packages only
standard: Standard desktop applications
toolbox: Development tools and advanced utilities
ultra: Complete software suite with additional applications

Package selection is controlled using conditional markers in packages.list files:

# Install only in toolbox and ultra variants
firefox +pv=toolbox +pv=ultra

# Install only in minimum variant
basic-tool +pv=minimum

Module System

Module Structure

The build system uses a numbered module structure located in linux-live/scripts/:

00-core/          # Base system packages
01-kernel/        # Linux kernel
02-firmware/      # Hardware firmware
03-gui-base/      # Basic GUI libraries
04-xfce-desktop/  # Desktop environment
05-apps/          # Desktop applications
10-example/       # Example module template

Module Components

Each module directory contains:

packages.list: List of packages to install with conditional markers
install: Bash script executed during module build
rootcopy-install/: Files copied to the system during build
rootcopy-postinstall/: Files copied after package installation
skip_conditions.conf: Conditions for skipping module build
patches/: Patches applied before building (not available for 00-core)

Example Module Template

The 10-example/ module serves as a template for creating new modules. It contains:

A complete packages.list with conditional markers examples
A basic install script showing proper condinapt usage
Example rootcopy-install/ and rootcopy-postinstall/ directories
Documentation comments explaining each component

To create a new module: Copy the 10-example directory and modify it for your needs:

bash

cp -r linux-live/scripts/10-example linux-live/scripts/06-my-module

This template is used throughout this documentation and provides the best starting point for custom modules.

Environment-Based Module Loading

The module system works through environment configurations in linux-live/environments/. Each environment directory contains symbolic links to the modules that should be included for that specific desktop environment and package variant.

Available Environments

bash

linux-live/environments/
├── core/          # Core system (no desktop)
├── flux/          # Flux desktop environment
├── lxqt/          # LXQt desktop environment
├── xfce/          # XFCE desktop environment
└── xfce-debug/    # XFCE with debug modules

Each environment directory contains symbolic links to module directories in linux-live/scripts/:

bash

# Example: XFCE environment
linux-live/environments/xfce/
├── 01-kernel -> ../../scripts/01-kernel
├── 02-firmware -> ../../scripts/02-firmware
├── 03-gui-base -> ../../scripts/03-gui-base
├── 04-xfce-desktop -> ../../scripts/04-xfce-desktop
├── 05-apps -> ../../scripts/05-apps
└── 06-firefox -> ../../scripts/10-firefox

Building Modules

To build modules, use the build-modules command:

bash

# Build all unbuilt modules for the current environment
./minios-live build-modules

# This will build all modules that:
# 1. Are linked in the current environment directory
# 2. Haven't been built yet
# 3. Meet the skip conditions (if any)

Module Install Scripts

The install script in each module:

Sources /minioslib for common functions
Sources /minios_build.conf for build configuration
Sets up debconf selections for automated package configuration
Performs custom configuration and file modifications
Uses console colors for output formatting

Example structure:

bash

#!/bin/bash
set -e          # exit on error
set -o pipefail # exit on pipeline error
set -u          # treat unset variable as error

. /minioslib
. /minios_build.conf

SCRIPT_DIR="$(dirname "$(readlink -f "$0")")"
console_colors

# Debconf pre-configurations
DEBCONF_SETTINGS=(
    "package-name package-name/option boolean true"
)

# Apply debconf settings
for SETTING in "${DEBCONF_SETTINGS[@]}"; do
    echo "${SETTING}" | debconf-set-selections -v
done

# Custom installation and configuration logic
# ...

Package Management with CondinAPT

CondinAPT is MiniOS's conditional package installation system that handles package selection based on build parameters like desktop environment, distribution, and package variant.

Basic Usage

Each module contains a packages.list file with conditional package specifications:

bash

# Basic syntax examples
package-name                    # Always install
package-name +pv=toolbox       # Install only for toolbox variant
package-name +de=xfce          # Install only for XFCE desktop
package-name -pv=minimum       # Install except for minimum variant
preferred-pkg || fallback-pkg  # Try first, use second if unavailable

Using CondinAPT in Module Scripts

Standard usage in module install scripts:

bash

# Load MiniOS library and install packages
. /minioslib || exit 1
/linux-live/condinapt \
    -l "$CWD/packages.list" \
    -c /linux-live/build.conf \
    -m /linux-live/condinapt.map

Complete Documentation

For comprehensive CondinAPT documentation including advanced syntax, filters, priority queues, debugging modes, and real-world examples, see: CondinAPT.md

Common Condition Filters

+pv=variant - Package variant (minimum, standard, toolbox, ultra)
+d=distribution - Distribution (bookworm, trixie, jammy, noble)
+de=desktop - Desktop environment (core, flux, xfce, lxqt)
+da=architecture - Architecture (amd64, i386)
+dt=type - Distribution type (debian, ubuntu)

Building Your First ISO

Quick Start

Clone the repository and prepare:

bash

git clone https://github.com/minios-linux/minios-live.git
cd minios-live

Install prerequisites:

bash

sudo apt-get update
sudo apt-get install sudo binutils debootstrap squashfs-tools xz-utils lz4 zstd xorriso mtools rsync grub-efi-amd64-bin grub-pc-bin

Build with minios-cmd (recommended):

bash

./minios-cmd -d bookworm -a amd64 -de xfce -pv standard

Or build with minios-live:

bash

./minios-live -

Customizing Your Build

Copy and edit the configuration:

bash

cp linux-live/build.conf linux-live/build-custom.conf
# Edit build-custom.conf with your preferences

Build with custom configuration:

bash

BUILD_CONF=linux-live/build-custom.conf ./minios-live -

Advanced Customization

Creating Custom Environments

You can create entirely new desktop environments by creating a new environment directory and configuring the appropriate modules. Here's how to create a GNOME environment as an example:

Create the environment directory:

bash

mkdir -p linux-live/environments/gnome

Create the base desktop module (04-gnome-desktop):

bash

# Start with the example template for a clean base
cp -r linux-live/scripts/10-example linux-live/scripts/04-gnome-desktop

# Configure GNOME-specific packages
cat > linux-live/scripts/04-gnome-desktop/packages.list << EOF
# Base GNOME desktop packages
gdm3
gnome-shell
gnome-session
gnome-settings-daemon
gnome-control-center
nautilus
gnome-terminal

# Standard GNOME applications
gnome-calculator +pv=standard +pv=toolbox +pv=ultra
gnome-text-editor +pv=standard +pv=toolbox +pv=ultra
eog +pv=standard +pv=toolbox +pv=ultra
evince +pv=standard +pv=toolbox +pv=ultra

# Additional GNOME tools
gnome-tweaks +pv=toolbox +pv=ultra
gnome-extensions-app +pv=toolbox +pv=ultra
dconf-editor +pv=toolbox +pv=ultra
EOF

# Create a custom install script for GNOME-specific configuration
cat > linux-live/scripts/04-gnome-desktop/install << 'EOF'
#!/bin/bash
set -e
set -o pipefail
set -u

. /minioslib
. /minios_build.conf

SCRIPT_DIR="$(dirname "$(readlink -f "$0")")"

# Install packages using condinapt
/condinapt -l "${SCRIPT_DIR}/packages.list" -c "${SCRIPT_DIR}/minios_build.conf" -m "${SCRIPT_DIR}/condinapt.conf"
if [ $? -ne 0 ]; then
    echo "Failed to install packages."
    exit 1
fi

# Set GNOME as default session
echo 'gnome' > /etc/skel/.dmrc
echo '[Desktop]' > /etc/skel/.dmrc
echo 'Session=gnome' >> /etc/skel/.dmrc

EOF
chmod +x linux-live/scripts/04-gnome-desktop/install

Create GNOME applications module (05-gnome-apps):

bash

cp -r linux-live/scripts/10-example linux-live/scripts/05-gnome-apps

cat > linux-live/scripts/05-gnome-apps/packages.list << EOF
# GNOME Applications
gnome-software +pv=standard +pv=toolbox +pv=ultra
gnome-system-monitor +pv=standard +pv=toolbox +pv=ultra
gnome-disk-utility +pv=standard +pv=toolbox +pv=ultra
gnome-screenshot +pv=standard +pv=toolbox +pv=ultra
gnome-calendar +pv=toolbox +pv=ultra
gnome-weather +pv=toolbox +pv=ultra
gnome-maps +pv=ultra
rhythmbox +pv=toolbox +pv=ultra
totem +pv=toolbox +pv=ultra
EOF

# Create a custom install script for GNOME applications
cat > linux-live/scripts/05-gnome-apps/install << 'EOF'
#!/bin/bash
set -e
set -o pipefail
set -u

. /minioslib
. /minios_build.conf

SCRIPT_DIR="$(dirname "$(readlink -f "$0")")"

# Install packages using condinapt
/condinapt -l "${SCRIPT_DIR}/packages.list" -c "${SCRIPT_DIR}/minios_build.conf" -m "${SCRIPT_DIR}/condinapt.conf"
if [ $? -ne 0 ]; then
    echo "Failed to install packages."
    exit 1
fi

# Configure default applications for GNOME
mkdir -p /etc/skel/.config

# Set default applications
cat > /etc/skel/.config/mimeapps.list << 'MIME_EOF'
[Default Applications]
text/plain=gnome-text-editor.desktop
image/jpeg=eog.desktop
image/png=eog.desktop
application/pdf=evince.desktop
video/mp4=totem.desktop
audio/mpeg=rhythmbox.desktop
MIME_EOF

EOF
chmod +x linux-live/scripts/05-gnome-apps/install

Link modules to the GNOME environment:

bash

# Link base system modules (same for all environments)
ln -s ../../scripts/01-kernel linux-live/environments/gnome/01-kernel
ln -s ../../scripts/02-firmware linux-live/environments/gnome/02-firmware
ln -s ../../scripts/03-gui-base linux-live/environments/gnome/03-gui-base

# Link GNOME-specific modules
ln -s ../../scripts/04-gnome-desktop linux-live/environments/gnome/04-gnome-desktop
ln -s ../../scripts/05-gnome-apps linux-live/environments/gnome/05-gnome-apps

# Link additional modules as needed
ln -s ../../scripts/10-firefox linux-live/environments/gnome/06-firefox

Configure build for GNOME environment:

bash

# Copy and modify build configuration
cp linux-live/build.conf linux-live/build-gnome.conf
sed -i 's/DESKTOP_ENVIRONMENT=".*"/DESKTOP_ENVIRONMENT="gnome"/' linux-live/build-gnome.conf
sed -i 's/PACKAGE_VARIANT=".*"/PACKAGE_VARIANT="standard"/' linux-live/build-gnome.conf

# Build the GNOME system
BUILD_CONF=linux-live/build-gnome.conf ./minios-live -

Environment Structure Best Practices

When creating custom environments:

Base modules (01-03): Usually the same across all environments
Desktop module (04): Contains the core desktop environment packages and configuration
Apps module (05): Desktop-specific applications
Optional modules (06+): Additional software packages

Module naming convention:

Use the format 04-{desktop}-desktop for the main desktop module
Use 05-{desktop}-apps or 05-apps for applications
Number additional modules sequentially (06, 07, 08, etc.)

Configuration considerations:

Each environment needs appropriate skip conditions in modules
Desktop-specific packages should use +de={environment} conditions
Test thoroughly with different package variants (minimum, standard, toolbox, ultra)

Adding Custom Modules

Create a new module using the template:

bash

cp -r linux-live/scripts/10-example linux-live/scripts/06-custom-module

Edit the packages.list:

bash

# Edit linux-live/scripts/06-custom-module/packages.list
# Add your packages with appropriate conditional markers

Customize the install script:

bash

# Edit linux-live/scripts/06-custom-module/install
# Add custom configuration and setup commands

Link the module to your environment:

bash

ln -s ../../scripts/06-custom-module linux-live/environments/xfce/06-custom-module

Build the modules:

bash

./minios-live build-modules

Troubleshooting

Common Issues

Build fails to start - Internet connectivity required:
- Issue: minios-live performs mandatory internet connectivity check on startup
- Solution: Ensure stable internet connection before starting build
- Check: Verify DNS resolution: nslookup deb.debian.org
- Proxy: Configure proxy settings if behind corporate firewall
- Note: Build cannot proceed without internet access
Build fails during bootstrap:
- Verify target distribution repositories are available
- Ensure prerequisites are installed
- Test: wget -q --spider http://deb.debian.org
Module build errors:
- Check package availability in target distribution
- Verify conditional markers syntax
- Review install script for errors
Missing packages:
- Check condinapt conditions
- Verify package names for target distribution
- Review package variant settings
Boot issues:
- Check GRUB configuration
- Verify kernel and initramfs generation
- Review bootloader files

Debug Mode

Enable debug output by setting the verbosity level in your build configuration:

Option 1: Edit build.conf

bash

# Edit linux-live/build.conf and set:
VERBOSITY_LEVEL=2   # Very verbose output with detailed tracing
# or
VERBOSITY_LEVEL=1   # Verbose output (default)
# or
VERBOSITY_LEVEL=0   # Minimal output

Option 2: Create custom config with debug settings

bash

cp linux-live/build.conf linux-live/build-debug.conf
sed -i 's/VERBOSITY_LEVEL=.*/VERBOSITY_LEVEL=2/' linux-live/build-debug.conf

# Enable additional debug options
sed -i 's/DEBUG_SSH_KEYS="false"/DEBUG_SSH_KEYS="true"/' linux-live/build-debug.conf
sed -i 's/DEBUG_SET_ROOT_PASSWORD="false"/DEBUG_SET_ROOT_PASSWORD="true"/' linux-live/build-debug.conf

# Build with debug configuration
BUILD_CONF=linux-live/build-debug.conf ./minios-live -

Verbosity levels:

0: Minimal output - only essential messages
1: Verbose output - standard build information (default)
2: Very verbose output - detailed tracing with bash debugging enabled

Log Files

Build logs are stored in:

build/log/ - General build logs

Getting Help

Check the official wiki
Review existing issues on GitHub
Join the community forums at minios.dev

Creating Modules - Learn how to create custom SquashFS modules with additional software
Rebuilding ISO - Repack your running live system into a bootable ISO using sb2iso
CondinAPT - Understand the conditional package management system used in builds

Building MiniOS ​

Overview ​

Getting Started ​

Prerequisites ​

Installing Prerequisites ​

Build Tools ​

minios-cmd (Recommended) ​

minios-live (Advanced) ​

Project Structure ​

Build Process ​

Build Stages Explained ​

Build Options ​

Complete System Build ​

Incremental Builds ​

Configuration System ​

Build Configuration Files ​

Main Configuration: linux-live/build.conf ​

Runtime Configuration: minios_build.conf ​

Package Variants ​

Module System ​

Module Structure ​

Module Components ​

Example Module Template ​

Environment-Based Module Loading ​

Available Environments ​

Building Modules ​

Module Install Scripts ​

Package Management with CondinAPT ​

Basic Usage ​

Using CondinAPT in Module Scripts ​

Complete Documentation ​

Common Condition Filters ​

Building Your First ISO ​

Quick Start ​

Customizing Your Build ​

Advanced Customization ​

Creating Custom Environments ​

Environment Structure Best Practices ​

Adding Custom Modules ​

Troubleshooting ​

Common Issues ​

Debug Mode ​

Log Files ​

Getting Help ​

Related Documentation ​

Building MiniOS

Overview

Getting Started

Prerequisites

Installing Prerequisites

Build Tools

minios-cmd (Recommended)

minios-live (Advanced)

Project Structure

Build Process

Build Stages Explained

Build Options

Complete System Build

Incremental Builds

Configuration System

Build Configuration Files

Main Configuration: `linux-live/build.conf`

Runtime Configuration: `minios_build.conf`

Package Variants

Module System

Module Structure

Module Components

Example Module Template

Environment-Based Module Loading

Available Environments

Building Modules

Module Install Scripts

Package Management with CondinAPT

Basic Usage

Using CondinAPT in Module Scripts

Complete Documentation

Common Condition Filters

Building Your First ISO

Quick Start

Customizing Your Build

Advanced Customization

Creating Custom Environments

Environment Structure Best Practices

Adding Custom Modules

Troubleshooting

Common Issues

Debug Mode

Log Files

Getting Help

Related Documentation