Builder: Technical Documentation

Builder is Meowrch’s automatic Arch Linux setup tool written in Python. It runs an interactive survey, installs packages, and applies dotfiles for Hyprland (Wayland) and/or BSPWM (X11) based on your choices.

For end-user step-by-step installation, see the complete installation guide.

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.