Builder: Technical Documentation

Builder is an intelligent automatic installation and configuration system for the meowrch distribution, written in Python. The system conducts an interactive user survey and performs complete system configuration according to selected parameters.

System Architecture

Core Components

Builder consists of several key modules:

• install.py — main module coordinating the entire process
• question.py — interactive user survey system
• packages.py — package and category definitions
• managers/ — specialized managers for various installation aspects
• utils/ — utilities and data schemas

Installation Managers

• PackageManager — manages package installation via pacman and AUR
• FileSystemManager — handles file system operations and dotfiles
• DriversManager — automatic driver detection and installation
• AppsManager — configures specific applications
• ChaoticAurManager — manages Chaotic AUR repository
• PostInstallManager — final post-installation configurations

Installation Stages

1. Initialization and Survey

Interactive user survey:

self.build_options: BuildOptions = Question.get_answers()

The system asks the following questions:

1. Backup creation — save existing configurations
2. Window manager selection — Hyprland and/or BSPWM
3. AUR Helper — choice between yay, paru and their -bin versions
4. Chaotic AUR — use precompiled AUR packages
5. Drivers — auto-detection and installation of NVIDIA/Intel/AMD
6. Firefox extensions — Dark Reader, uBlock Origin, TWP, Unpaywall, Tampermonkey
7. Terminal shell — fish or zsh
8. User packages — interactive selection by categories

2. Backup Creation

if self.build_options.make_backup:
    FileSystemManager.make_backup()

The following configurations are saved:

• ~/.config/ — user configurations
• ~/.local/bin/ — user scripts
• ~/.local/share/nemo/ — file manager settings
• Dotfiles: .bashrc, .env, .Xresources, .xinitrc
• ~/.icons/default/index.theme — cursor theme

3. File System Preparation

FileSystemManager.create_default_folders()
FileSystemManager.copy_dotfiles(
    exclude_bspwm=not self.build_options.install_bspwm,
    exclude_hyprland=not self.build_options.install_hyprland,
)

Creating standard directories:

mkdir -p ~/.config ~/.themes Desktop Downloads Templates Public Documents Music Pictures Videos

Copying dotfiles with conditional exclusions:

• If BSPWM is not installed — exclude bspwm, polybar
• If Hyprland is not installed — exclude hypr, waybar
• Setting permissions chmod -R 700 for ~/.config and ~/.local/bin

4. Package Manager Configuration

PackageManager.update_pacman_conf(enable_multilib=True)
PackageManager.update_database()

Modifying /etc/pacman.conf:

# Enabling performance options
ParallelDownloads = 5
VerbosePkgLists
ILoveCandy
Color

# Enabling multilib repository
[multilib]
Include = /etc/pacman.d/mirrorlist

Updating package database:

sudo pacman -Sy

5. Chaotic AUR Installation (Optional)

if self.build_options.use_chaotic_aur:
    ChaoticAurManager.install()

If Chaotic AUR is selected, a repository with precompiled AUR packages is installed to speed up installation.

6. AUR Helper Installation

PackageManager.install_aur_helper(self.build_options.aur_helper)

Installation process:

1. Install dependencies: git, base-devel
2. Clone corresponding repository from AUR
3. Build and install via makepkg -si --noconfirm

Supported AUR Helpers:

• yay — classic helper
• paru — modern Rust alternative
• yay-bin — precompiled yay version
• paru-bin — precompiled paru version

7. Package Installation

self.packages_installation()

An example of a package classification system:

Base Packages

# Common packages for all configurations
BASE.pacman.common = [
    # Base tools
    "base-devel", "git", "networkmanager", "libnotify",
    # Audio subsystem
    "pipewire", "pipewire-pulse", "pipewire-alsa", "wireplumber",
    # CLI tools
    "jq", "fastfetch", "lsd", "bat", "micro", "btop", "yazi",
    # GUI applications
    "sddm", "plymouth", "firefox", "kitty", "nemo", "vlc",
    # Fonts
    "ttf-hack-nerd", "noto-fonts", "ttf-jetbrains-mono-nerd"
]

# BSPWM packages
BASE.pacman.bspwm_packages = [
    "xorg", "bspwm", "sxhkd", "polybar", "dunst", "feh"
]

# Hyprland packages
BASE.pacman.hyprland_packages = [
    "hyprland", "waybar", "hyprlock", "swww", "swaync", "uwsm"
]

User Packages (CUSTOM)

CUSTOM = {
    "useful": {"timeshift": PackageInfo("System restore utility")},
    "development": {"obsidian": PackageInfo("Knowledge base", recommended=True)},
    "social_media": {"telegram-desktop": PackageInfo("Messenger", selected=True)},
    "games": {"steam": PackageInfo("Gaming platform", selected=True)},
    "entertainment": {"yandex-music": PackageInfo("Music service", aur=True)},
    "office": {"onlyoffice-bin": PackageInfo("Office suite", aur=True)}
}

Package installation algorithm:

1. Form pacman and AUR package lists
2. Add packages depending on selected WM
3. Install in batches of 5 packages for optimization
4. On batch failure — individual installation with retries
5. Maintain list of uninstalled packages for final report

8. Driver Installation

self.drivers_installation()

Automatic hardware detection:

@staticmethod
def auto_detection() -> List[str]:
    drivers = []

    # Detection by PCI ID and other methods
    if "intel" in lspci_output.lower():
        drivers.append("Intel")
    if "nvidia" in lspci_output.lower():
        drivers.append("Nvidia")
    if "amd" in lspci_output.lower() or "ati" in lspci_output.lower():
        drivers.append("AMD")

    return drivers

Driver packages by vendor:

Intel:

"intel": [
    "lib32-mesa", "vulkan-intel", "lib32-vulkan-intel",
    "intel-media-driver", "libva-intel-driver", "xf86-video-intel"
]

AMD:

"amd": [
    "lib32-mesa", "vulkan-radeon", "lib32-vulkan-radeon"
]

NVIDIA:

"nvidia": [
    "nvidia-dkms", "nvidia-utils", "lib32-nvidia-utils",
    "nvidia-settings", "libva-nvidia-driver"
]

Setting up GPU modules for early boot:

DriversManager.setup_gpu_modules_for_early_boot()

Updating /etc/mkinitcpio.conf for correct Plymouth operation with graphics drivers.

9. Application Configuration

GRUB Bootloader

AppsManager.configure_grub()

Installing custom meowrch theme and updating configuration.

SDDM Display Manager

AppsManager.configure_sddm()

Setting up Sugar-Dark theme and autostart configuration.

Plymouth Boot Screen

AppsManager.configure_plymouth()

Installing animated boot screen.

Firefox

AppsManager.configure_firefox(
    darkreader=self.build_options.ff_darkreader,
    ublock=self.build_options.ff_ublock,
    # ... other extensions
)

Automatic installation of selected extensions and settings.

VS Code

AppsManager.configure_code()

Installing themes and basic development extensions.

Pawlette

AppsManager.configure_pawlette()

Integrating theme management system.

Mewline (only for Hyprland)

if self.build_options.install_hyprland:
    AppsManager.configure_mewline()

Setting up custom status bar for Hyprland.

10. System Services Configuration

self.daemons_setting()

Managing systemd services:

daemons = {
    "disable": ["sddm.service"],  # Disable for manual control
    "enable": ["NetworkManager", "bluetooth.service"],
    "start": ["bluetooth.service"]
}

11. Final Configuration

PostInstallation.apply(self.build_options.terminal_shell)

Terminal shell configuration:

• Fish: Installing custom functions and aliases
• Zsh: Setting up Oh My Zsh with Powerlevel10k theme

Final operations:

• Updating font database
• Setting up XDG directories
• Applying user settings
• Generating final report

Logging System

logger.add(
    sink="build_debug.log",
    format="{time} | {level} | {message}",
    level="DEBUG",
    encoding="utf-8",
)

The entire installation process is logged with detailed information in the build_debug.log file.

Error Handling

Recovery Strategies

1. Package installation: On batch failure — individual installation
2. Retry attempts: Up to 3 attempts for critical operations
3. Continue on non-critical errors: System continues work on non-critical errors
4. Detailed logging: Saving error information for diagnostics

Final Report

logger.warning("Pacman: " + ", ".join(self.not_installed_packages.pacman))
logger.warning("Aur: " + ", ".join(self.not_installed_packages.aur))

At the end of installation, Builder provides a report on packages that could not be installed automatically.

Installation Completion

is_reboot = inquirer.confirm("Do you want to reboot?")
if is_reboot:
    subprocess.run("sudo reboot", shell=True)

After successful installation, the system offers a reboot to apply all changes.

Technical Features

Performance

• Parallel downloads: ParallelDownloads = 5 in pacman
• Batch installation: Installing packages in groups of 5
• Chaotic AUR: Using precompiled packages
• Caching: Reusing downloaded packages

Security

• Backup creation: Automatic saving of existing settings
• Validation: Package integrity checking via pacman
• Logging: Detailed logging of all operations
• Access rights: Correct setting of user file permissions

Flexibility

• Modularity: Independent managers for different components
• Configurability: Wide customization possibilities through surveys
• Extensibility: Easy addition of new packages and functions
• Compatibility: Support for different hardware configurations

---

Note: For information on how to start the installation, see Complete Installation Guide.