Skip to content

TECHNICAL_COMPANION_GUIDE.md

Latest commit

 

History

History
313 lines (243 loc) · 23.7 KB

TECHNICAL_COMPANION_GUIDE.md

File metadata and controls

313 lines (243 loc) · 23.7 KB
Raw

🛠️ Slacky-Update Technical Companion Guide: Under the Hood & Engine Architecture

A Deep-Dive Architectural Whitepaper & Technical Reference for Slackware Linux 15.0 & -current

v1.0_RC2 — "Dark Star" (Stability & Hardware Release Candidate)

Important

TARGET DISTRIBUTION REQUIREMENT & VERSION DISCLAIMER
Slacky-Update is engineered strictly for Slackware 15+ (slackware-current / Slackware 16 alpha).
It is NOT compatible with or supported on legacy Slackware 15.0 (stable). Legacy 15.0 systems feature older core packages, toolchains, and shared libraries (such as older glibc, GCC, Wayland/Mesa, PipeWire, and kernel headers) that cause package and soname conflicts which cannot be safely detected or resolved. Running Slacky-Update on Slackware 15.0 is unsupported. Users on Slackware 15.0 must migrate to slackware-current before using this suite.

Caution

COMPREHENSIVE TESTING, LIABILITY & USE-AT-YOUR-OWN-RISK DISCLAIMER

  • Hardware Testing & Verification: Slacky-Update has been extensively verified and field-tested on bare-metal workstations with dry-run/simulated test passes across diverse build environments. However, this in no way guarantees that it will operate seamlessly or without anomalies on your specific hardware configuration.
  • 100% User Responsibility: Slacky-Update executes deep, low-level modifications to foundational system components. All installation, upgrades, and system modifications are performed 100% at your own discretion and risk.
  • No Liability for Data Loss: The authors, maintainers, and contributors assume no liability, warranty, or responsibility for system malfunctions, unbootable states, hardware quirks, or loss of personal data.
  • Mandatory Backups: Always maintain current, tested backups of your personal data (/home, configuration files, and boot partitions) and keep a bootable Slackware Live-USB accessible before performing upgrades or modifying bootloaders.
  • Bug Reporting & Support Policy: If you encounter bugs, regressions, or hardware edge-cases, please report them on GitHub Issues so they can be addressed. Beyond this documentation, no individual customer support, warranties, or service level agreements are offered.

📑 Table of Contents

  1. 1. Philosophical Manifesto: Harmony with Slackware
  2. 2. Master Architecture Overview
  3. 3. The Master Internal Engines: Detailed Breakdown
  4. 4. Security, Sandboxing & Privilege Model
  5. 5. Data Layout & State Management
  6. 6. Auditing, Transparency & Debugging

1. Philosophical Manifesto: Harmony with Slackware

Note

🧩 ELI5 — What is Slackware harmony and why do you care?

Slackware is legendary for being clean, predictable, and indestructible. Our golden rule is that Slacky-Update must never behave like a reckless package manager that clobbers system files. We package everything as clean, native Slackware packages (.txz), never build software directly on your root filesystem, and always preserve your stock Slackware fallback kernels and bootloaders.

Slacky-Update was engineered with a strict guiding principle: augment Slackware without ever violating its unix philosophy, package management integrity, or system initialization purity.

┌─────────────────────────────────────────────────────────────────────────────┐
│                       SLACKWARE & SLACKY-UPDATE HARMONY                     │
├─────────────────────────────────────────────────────────────────────────────┤
│  SLACKWARE CORE LINUX (Canonical System of Record)                          │
│  ├── /var/log/packages/        (Native pkgtools database)                   │
│  ├── /etc/slackpkg/            (Official distribution mirrors)              │
│  ├── /etc/rc.d/                (BSD-style SysVinit scripts)                 │
│  └── /boot/vmlinuz-generic     (Official Slackware fallback kernels)        │
│                               ▲                                             │
│                               │ Strict Respect & Clean Boundaries           │
│                               ▼                                             │
│  SLACKY-UPDATE COMPANION LAYER (Zero-Destruction Augmentation)              │
│  ├── Isolated Builds          (Sandboxed in /tmp/slacky-build-XXXXXX)      │
│  ├── Isolated Workstation Apps (Contained in /opt/<app>/)                   │
│  ├── Non-Destructive Boot     (Limine + GRUB Coexistence Mode)              │
│  └── Pure Native Packaging    (100% native .txz with slack-desc & doinst)   │
└─────────────────────────────────────────────────────────────────────────────┘

100% Respect for Slackware Core

  • Native Tooling is Master: Slacky-Update does not replace pkgtools (installpkg, upgradepkg, removepkg) or slackpkg. It acts as an orchestrator and companion around them.
  • No Foreign Package Managers: No apt, dnf, or pacman binaries are ever installed or executed on the host system.
  • Canonical Logging: Every package installed by Slacky-Update is registered in /var/log/packages/ as a first-class citizen with standard slack-desc metadata.
  • BSD-Style SysVinit Integration: All background services deploy standard /etc/rc.d/rc.<service> scripts with clean chmod +x / chmod -x semantics.

The Zero-Rootfs Compilation Rule (Sandboxing)

Important

Slacky-Update NEVER compiles, builds, or mutates packages directly on the host root filesystem (/).

  1. Ephemeral Sandboxes: Every compilation, archive extraction, and transmutation occurs inside an isolated scratch space: /tmp/slacky-build-XXXXXX (in RAM via tmpfs).
  2. Deterministic Staging: Upstream files are organized into a strict root staging directory (/tmp/package-name/), permissions are normalized.
  3. Atomic Package Creation: makepkg -l y -c n /tmp/target-package.txz generates a clean Slackware package archive.
  4. Standard Installation: The resulting .txz is handed over to upgradepkg --install-new, guaranteeing complete tracking in /var/log/packages/.
  5. Guaranteed Sandbox Destruction: POSIX signal traps (trap cleanup INT TERM EXIT) automatically wipe /tmp/slacky-build-XXXXXX even if an operation is aborted midway.

2. Master Architecture Overview

Note

🧩 ELI5 — What is the master architecture and why do you care?

Think of Slacky-Update like a modular high-end stereo rack. Each component (the turbo downloader, the kernel manager, the graphics orchestrator, the bootloader manager) sits in its own dedicated chassis with its own isolated cables, so tuning your graphics card never interferes with your web browser or audio drivers.

┌─────────────────────────────────────────────────────────────────────────────┐
│                          SLACKY-UPDATE SUBSYSTEMS                           │
├─────────────────────────────────────────────────────────────────────────────┤
│  CLI INTERFACE (bin/slacky-update)       TRAY APPLET (bin/slacky-update-tray)│
│  └── common.sh & check_backend.sh        └── PyQt5 Event Loop & D-Bus / XDG │
├─────────────────────────────────────────────────────────────────────────────┤
│  TRANSACTION & PACKAGE ORCHESTRATION                                        │
│  ├── Parallel Pre-fetcher (10 Streams)  ├── .new Config Reconciler          │
│  ├── Multi-Pass Resume Controller       └── AlienBOB Multilib Health Guard  │
├─────────────────────────────────────────────────────────────────────────────┤
│  GRAPHICS, COMPUTE & WORKSTATION SUBSYSTEMS                                 │
│  ├── NVIDIA CachyOS Master & DKMS       ├── AMD ROCm / HIP Creator Toolkit  │
│  ├── VRAM Booster (615+ Preserver)      └── Underpants Gnomes App-Bundler   │
├─────────────────────────────────────────────────────────────────────────────┤
│  KERNEL & BOOTLOADER INFRASTRUCTURE                                         │
│  ├── CachyOS Kernel & CPU Tiering       ├── Limine Two-Zone Generator       │
│  ├── Dracut Hardware Guard (lib64)      └── sbctl / MOK Secure Boot Armor   │
└─────────────────────────────────────────────────────────────────────────────┘

3. The 12 Internal Engines: Detailed Breakdown

Note

🧩 ELI5 — What are the 12 engines and why do you care?

Under the hood, Slacky-Update runs 12 specialized robotic engines, each laser-focused on one job: one downloads at lightning speed, one tunes your CPU instructions, one maintains your GPU drivers, and one ensures your PC always boots. Below is the full engineering breakdown of each engine.

Engine 1: Core Orchestration & Lifecycle Controller

  • Source Files: bin/slacky-update, lib/common.sh, lib/mod_packages.sh
  • Role: Coordinates CLI argument parsing, transaction sequencing, slackpkg integration, and .new configuration file reconciliation.

Engine 2: 10-Worker Asynchronous Turbo Pre-Fetcher

  • Source File: lib/mod_packages.sh
  • Role: Spawns 10 concurrent curl download workers using HTTP range resume (-C -) to pre-populate /var/cache/packages/ before package installation starts.

Engine 3: Sandboxed Transmutation & App-Bundle Engine (Underpants Gnomes)

  • Source Files: lib/mod_gaming.sh
  • Role: Transmutes 51 upstream workstation packages, 9 OBS streamer plugins, and 6 DKMS hardware drivers into native .txz archives with GPG validation, /opt/<app>/ directory isolation, interactive 2-column TUI workstation manager, and timestamp-paced animated Gnome download progress bar.

Engine 4: CachyOS Kernel Lifecycle & CPU Microarchitecture

  • Source Files: lib/mod_kernel.sh, lib/mod_limine.sh
  • Role: Inspects host CPU features (x86_64_v4, v3, v2) and deploys optimized CachyOS kernels across 9 scheduler flavors (standard, bore, lto, eevdf, bmq, deckify, rt-bore, rc, lts) with a universal multi-kernel DKMS compilation engine, smart Realtek 2.5GbE (r8125) detection, and deterministic 2-kernel retention policy.

Engine 5: NVIDIA Driver & DKMS Pipeline

  • Source File: lib/mod_nvidia.sh
  • Role: Deploys pre-compiled modules for CachyOS kernels, DKMS for standard Slackware kernels, purges stale modules, and aligns 32-bit multilib drivers with strict DKMS collision shielding.

Engine 6: System Performance, Memory Architecture & 1M Resource Limits

  • Source File: lib/mod_tweaks.sh
  • Role: Applies 1 million file descriptor limits, PipeWire realtime priority (rtprio 95), Transparent HugePages (madvise + defer), TCP BBR, and KDE Plasma Wayland Dynamic VRAM Leak Guard & Memory Compaction.

Engine 7: AMD ROCm & HIP Compute Engine

  • Source File: lib/mod_rocm.sh
  • Role: Deploys full ROCm OpenCL/HIP compute runtimes for DaVinci Resolve Studio and purges conflicting Mesa OpenCL libraries.

Engine 8: Limine Two-Zone & Cryptographic Armor Engine

  • Source Files: lib/mod_limine.sh, lib/mod_secureboot.sh
  • Role: Generates /boot/limine.conf preserving Zone A (user settings) while atomically recalculating Zone B (kernels, BLAKE2B hashes, Snapper snapshots, and sbctl signing).

Engine 9: SBo SlackBuilds & sbotools Integration Engine

  • Source File: lib/mod_sbo.sh
  • Role: Auto-routes recipes to Ponce's git repository on -current or standard SBo on 15.0, enforces JOBS=$(nproc), and provides 26 curated recipes (including Plasticity 3D CAD).

Engine 10: Real-Time System Tray Telemetry & Notifications

  • Source Files: bin/slacky-update-tray, lib/slacky-update-tray, lib/check_backend.sh
  • Role: Lightweight PyQt6 background monitor polling on-demand and on schedule, featuring cascading submenus for Underpants Gnomes (TUI/GUI) and triggering D-Bus desktop notifications.

Engine 11: Internationalization & Fallback Engine (i18n)

  • Source Files: lib/slacky_update_i18n.py, locales/*.json
  • Role: High-performance multi-language translation engine providing 100% key parity across 24 global languages (213 keys each) with 90s pop-culture Radical Editions.

Engine 12: Documentation & Groff PDF / QR Export Engine

  • Source File: lib/mod_docs.sh
  • Role: Compiles Markdown documentation into professional Groff/Troff PDFs in ~/Documents/ and starts an ephemeral Wi-Fi QR web server for mobile reading during BIOS setup.

Engine 13: Universal HiDPI & Wayland Scaling Engine

  • Source Files: assets/profile.d/slacky-hidpi.sh, assets/profile.d/slacky-hidpi.csh, desktop/slacky-update.desktop, bin/slacky-update, lib/slacky-update-tray
  • Role: Configures system-wide Qt5, Qt6, and GTK environment defaults for modern high-resolution displays (4K/1440p) under Wayland and X11 sessions. Deploys QT_ENABLE_HIGHDPI_SCALING=1, QT_AUTO_SCREEN_SCALE_FACTOR=1, QT_SCALE_FACTOR_ROUNDING_POLICY=PassThrough, and routes Wayland compositor backends (QT_QPA_PLATFORM="wayland;xcb", GDK_BACKEND="wayland,x11,*"). Initializes QApplication.setAttribute(Qt.AA_EnableHighDpiScaling) in the PyQt tray monitor and ensures terminals and dialogs spawn with pixel-perfect integer/fractional scaling.

Engine 14: Fast-Race Chaotic-AUR Probing & Self-Healing 404 Engine

  • Source Files: lib/mod_gaming.sh, lib/gnomes_pacman.py
  • Role: Parallel, non-blocking latency evaluator and repository integrity recovery engine.
    • Fast-Race Mirror Benchmarking: Evaluates Chaotic-AUR global mirrors simultaneously using concurrent.futures.as_completed with aggressive 750ms cutoffs. Employs an instant-win short-circuit mechanism (sub-55ms response) to select the fastest mirror immediately without stalling on dead or high-latency nodes.
    • Self-Healing 404 Recovery: Dynamically intercepts upstream mirror 404 HTTP errors when package versions bump during database TTL intervals. Automatically triggers a silent resynchronization pass (sync_repositories(force=True, verbose=False)), updates target tarball URIs, and transparently retries the download in-flight without user intervention.

Engine 15: Gaming Overlay TrueType Compatibility Mesh

  • Source Files: lib/mod_gaming.sh
  • Role: Dynamic font indexer, symlinking orchestrator, and parser validation mesh for Vulkan/OpenGL gaming overlays (MangoHud, GOverlay).
    • Hierarchical Font Mesh: Automatically discovers all system-installed TTF and OTF fonts across /usr/share/fonts/ and /usr/local/share/fonts/ and constructs synchronized symlink trees in ~/.local/share/fonts/ and subdirectories (TTF, OTF, truetype, opentype).
    • stb_truetype Engine Compatibility: Eliminates GOverlay absolute path rendering errors and ensures MangoHud's Dear ImGui stb_truetype font rasterizer loads custom TrueType fonts natively without bitmap fallbacks.

4. Security, Sandboxing & Privilege Model

Note

🧩 ELI5 — What is the privilege model and why do you care?

Security means never giving administrative power to programs that don't need it. The background monitor and update checks run as a regular user with zero privileges. Only when kernels, drivers, or bootloaders are being modified does the tool request elevated root permissions via sudo.

┌─────────────────────────────────────────────────────────────────────────────┐
│                      SLACKY-UPDATE PRIVILEGE HIERARCHY                      │
├─────────────────────────────────────────────────────────────────────────────┤
│  USER SPACE (Standard UID - No Root Required)                               │
│  ├── slacky-update-tray   (Desktop Applet, D-Bus, GUI)                      │
│  ├── slacky-update --check (Read-only status inspection)                     │
│  └── ~/.config/slacky-update/config.json (User settings & language)         │
├─────────────────────────────────────────────────────────────────────────────┤
│  SANDBOX WORKSPACE (Ephemeral /tmp/slacky-build-XXXXXX, mode 0700)          │
│  ├── GPG signature validation with gpgv                                     │
│  ├── Archive unpacking and /opt staging                                     │
│  └── makepkg assembly of .txz package                                       │
├─────────────────────────────────────────────────────────────────────────────┤
│  ROOT PRIVILEGE (Elevated via sudo for atomic transaction only)             │
│  ├── slackpkg upgrade-all & installpkg / upgradepkg                         │
│  ├── dracut initramfs generation & sbctl / MOK signing                      │
│  └── Atomic limine.conf / grub.cfg replacement                              │
└─────────────────────────────────────────────────────────────────────────────┘

5. Data Layout & State Management

Note

🧩 ELI5 — What is the data layout and why do you care?

This is the filesystem map showing where Slacky-Update keeps its data. Everything is organized according to standard Linux file hierarchy standards, so you always know where configuration files, keys, and backups are stored.

Path Purpose Ownership / Permissions
~/.config/slacky-update/config.json User settings, language override User (0644)
/var/cache/slacky-update/ Download cache, SlackBuild recipes, update status Root (0755)
/var/cache/slacky-update/backup/ Offline backup of stock kernels and drivers Root (0700)
/usr/share/slacky-update/keys/ Machine Owner Keys (MOK) and vendor GPG keys Root (0644)
/usr/share/slacky-update/locales/ 24 JSON language translation files Root (0644)
/usr/share/slacky-update/docs/ System manuals, Survival Guide, Companion Guide Root (0644)
/etc/boot/hooks/post.d/ Post-kernel installation hooks (Limine hash enrollment) Root (0755)

6. Auditing, Transparency & Debugging

Note

🧩 ELI5 — What is auditing and why do you care?

Nothing in Slacky-Update is a mysterious black box. If you ever want to see exactly what the application is doing, you can read the shell scripts directly or run the diagnostic inspection commands listed below.

Key Diagnostic Commands

# Execute a read-only update status check
slacky-update --check

# Test bash script syntax across all modules
for f in /usr/local/lib/slacky-update/*.sh; do bash -n "$f"; done

# Inspect active language translations
python3 /usr/share/slacky-update/lib/slacky_update_i18n.py CLI_TITLE

# Verify active NVIDIA VRAM Booster parameter status
cat /sys/module/nvidia/parameters/PreserveVideoMemoryAllocations

# Verify Limine configuration and enrolled BLAKE2B hashes
cat /boot/limine.conf

# Verify Secure Boot signing state
sbctl status

For disaster recovery procedures: 👉 See docs/TROUBLESHOOTING_GUIDE.md
For disk partitioning and ESP setup: 👉 See docs/LIMINE_SECUREBOOT_FIELD_GUIDE.md

Slacky-Update Technical Companion Guide
Engineered for Transparency, Purity, and Performance on Slackware Linux
Canonical Source: GitHub | Secondary Mirror: Codeberg