Skip to content

UNDERPANTS_GNOMES_FIELD_GUIDE.md

Latest commit

 

History

History
167 lines (128 loc) · 11 KB

UNDERPANTS_GNOMES_FIELD_GUIDE.md

File metadata and controls

167 lines (128 loc) · 11 KB
Raw

🧙 Underpants Gnomes Pacman Engine — Comprehensive Field Guide

Universal Arch & CachyOS Package Transmutation for Slackware Linux

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

Important

TARGET DISTRIBUTION REQUIREMENT & VERSION DISCLAIMER
Underpants Gnomes and Slacky-Update are engineered strictly for Slackware 15+ (slackware-current / Slackware 16 alpha).
Legacy Slackware 15.0 (stable) is strictly unsupported due to older host glibc, toolchains, and sonames that cause conflicts that cannot be detected or resolved. Slackware 15.0 users must upgrade to -current before using this suite.

Warning

EXPERIMENTAL STATUS & HOST-SOVEREIGN SAFETY NOTICE
The Underpants Gnomes Universal Pacman Transmutation Engine is an Experimental feature. Because upstream repositories contain over 31,800+ packages, we cannot manually audit every possible application.
Host Safety Guarantee: Underpants Gnomes is a completely benign addition that never modifies host system libraries (/lib64, /usr/lib64, glibc, /etc/pam.d). Packages run isolated in /opt/underpants/pkgs/. If a package fails to run due to unmet deep runtime dependencies, you can safely remove it via gnomes -R <pkg>. Please report broken packages on GitHub!

🧒 ELI5: What is Underpants Gnomes and How Does It Work?

Explain Like I'm 5 (ELI5): Imagine your Slackware system is a clean, well-organized house. You want to run a fancy toy from Arch Linux, but normally that toy requires changing the walls, doors, and plumbing (glibc, systemd, core libraries) of your whole house!

Underpants Gnomes fixes this:

  1. Step 1: Steal Underpants — It downloads the Arch/CachyOS package and all its dependencies.
  2. Step 2: Transmutation — It puts the application safely into its own sandbox room inside /opt/underpants/pkgs/<app>/, rewrites all internal paths so the app only looks inside its own room and the shared /opt/underpants/runtime/ pool, and builds a genuine native Slackware .txz package.
  3. Step 3: PROFIT! 💰 — It places a small launcher script into /usr/bin/ so you can launch the app from your terminal or application menu just like any native Slackware program!

Your Slackware base system (/lib64, /usr/lib64, glibc, init, pam) remains 100% pristine, untouched, and safe.

🚀 Getting Started: Step 1 is Installing the Runtime Pool

Before installing complex GTK4, Qt6, or multimedia applications, you should install the Underpants Gnomes Shared Runtime Pool.

The runtime pool provides over 3,500+ pre-staged shared libraries (GTK3/4, Qt5/6, WebKitGTK, GStreamer, Mesa/Vulkan, FFmpeg, Python 3.14) in /opt/underpants/runtime/. This avoids re-downloading hundreds of megabytes of duplicate dependencies for every single app.

To install the complete runtime pool:

gnomes runtime install all

Note

The engine automatically creates all necessary directory structures (/opt/underpants/runtime/, /opt/underpants/pkgs/, /opt/underpants/common/), relocates configurations (such as Glycin image loaders), and compiles schemas and module caches automatically.

You can check the status of your runtime pool at any time:

gnomes runtime status

📜 Golden Rules & Best Practices

1. 🛡️ Always Check Slackware Base & SBo First!

Before installing a package via gnomes -S, always check if it is already provided natively by Slackware (/var/log/packages) or available via SlackBuilds (sbopkg / slacky-update --sbo). Native Slackware packages should always be your first choice.

2. 🎮 For Gaming Packages & Desktop Suites, Use Curated Modules!

For core gaming components such as Steam, MangoHud, Gamescope, GOverlay, ProtonPlus, Faugus Launcher, and Ananicy-Cpp, complete desktop environments like hyprland-noctalia (Mac-like Wayland desktop with Noctalia Shell) and hyprland-core, or settings suites like hyprmod (GTK4 visual settings editor for Hyprland), we strongly recommend installing them through slacky-update --party-on, slacky-update --hyprland, slacky-update --hyprmod, or the curated Underpants Gnomes menu (gnomes -S hyprland-noctalia). These curated packages are tuned and patched specifically for optimal Slackware desktop and gaming performance:

  • PipeWire AT_SECURE Protection: Automatically strips conflicting file capabilities from pipewire and wireplumber (setcap -r), preventing session DBus drops under Wayland.
  • HyprMod Visual Configuration: Visual GTK4/Libadwaita management for monitors, 10-bit OLED color modes, animations, and keybindings via modular hyprland-gui.lua.
  • Systray Daemon Integration: Built-in autostart and StatusNotifierItem registration for slacky-update-tray, openrgb (with automatic profile loading), and easyeffects.
  • Hardware-Accelerated Browsers: Installing google-chrome, brave, or microsoft-edge automatically detects NVIDIA hardware and provisions hardware-accelerated Wayland and VA-API flags (--ozone-platform=wayland, VaapiOnNvidiaGPUs, --enable-gpu-rasterization, --enable-zero-copy).

3. ⚠️ KERNELS MUST NEVER BE INSTALLED VIA gnomes -S!

Do NOT attempt to install Linux kernels, kernel headers, or out-of-tree kernel modules via gnomes -S (e.g. gnomes -S linux or gnomes -S linux-zen).
The pacman engine has built-in guardrails (CORE_EXCLUDES) that block kernel packages from transmuting to protect your bootloader.
👉 Kernel lifecycle management (CachyOS, Arch vanilla linux, and Arch linux-zen kernels) must strictly be managed through slacky-update --kernel / mod_kernel.sh!

4. ⚡ Fast-Race Mirror Benchmarking Engine

When fetching Chaotic-AUR packages (such as hyprpicker, easyeffects, or coolercontrol), the engine evaluates global mirrors concurrently via concurrent.futures.as_completed. A sub-55ms response triggers an instant win, returning the fastest node immediately and terminating slower mirror checks with a strict 750ms timeout.

5. 🔄 Transparent 404 Self-Healing Auto-Sync

If an upstream repository rolls out an update while local database manifests are cached, returning HTTP 404, Gnomes automatically traps the error, runs a silent forced resynchronization (sync_repositories(force=True, verbose=False)), updates the URL to the latest version, and retries the download seamlessly.

💻 Full Terminal Command Reference

You can use gnomes directly from Konsole, Bash, or Zsh just like pacman — there is no need to navigate through the slacky-update TUI menu unless you prefer it.

1. Database Synchronization & Repository Management

Action Pacman Syntax Long-form Syntax Description
Sync Repositories gnomes -Sy gnomes sync Downloads latest database indexes from Arch/CachyOS
Force Full Resync gnomes -Syy gnomes sync -f Forces a fresh download of all database archives
List Active Mirrors — gnomes list-repos Lists active repository matrix and priority ordering

2. Searching & Inspecting Packages

Action Pacman Syntax Long-form Syntax Description
Search Packages gnomes -Ss <query> gnomes search <query> Sub-50ms search across package names and descriptions
View Package Info gnomes -Si <pkg> gnomes info <pkg> Displays upstream version, size, dependencies, and URL
Simulate Dependency Plan gnomes -Sp <pkg> gnomes deps <pkg> Solves the DAG and shows what will be downloaded vs host-provided

3. Installing & Transmuting Packages

Action Pacman Syntax Long-form Syntax Description
Install Package(s) gnomes -S <pkg...> gnomes transmute <pkg...> Resolves deps, downloads, transmutes to .txz, and installs
Force Re-transmute gnomes -S --force <pkg> gnomes transmute -f <pkg> Rebuilds and reinstalls even if already installed
Non-interactive Install gnomes -S --noconfirm <pkg> gnomes transmute -y <pkg> Skips confirmation prompts (useful in scripts)
Build Only (No Install) gnomes -S --build-only <pkg> gnomes transmute --build-only <pkg> Generates the .txz package in /tmp without installing

4. Updating & Managing Installed Packages

Action Pacman Syntax Long-form Syntax Description
Check for Updates gnomes -Syu gnomes list-updates Checks installed gnomes packages against upstream repos
List Installed Packages gnomes -Q gnomes list-installed Lists all transmuted packages in /var/log/packages
Remove Transmuted App gnomes -R <pkg> removepkg underpants-<pkg> Uninstalls package cleanly from Slackware package database

5. Runtime & Storage Management

Action Command Description
Inspect Runtime Pool gnomes runtime status Reports soname count, active profiles, and Python version
List Runtime Profiles gnomes runtime profiles Shows available profiles (core, gui, media, graphics, all)
Install Runtime Profile gnomes runtime install <prof> Transmutes and deploys a shared runtime profile
Reclaim Storage (Dedup) gnomes dedup Hardlinks identical libraries across /opt/underpants/ via SHA256
Clean Uninstalled Cache gnomes -Sc gnomes clean-cache (removes old downloaded packages)
Purge Entire Cache gnomes -Scc gnomes clean-cache --all (prunes all build files and caches)
Check Host Sovereignty gnomes check-host Displays CPU tier, max GLIBC version, and indexed sonames

🗂️ Filesystem Layout

/opt/underpants/
├── runtime/              ← Shared runtime pool (GTK, Qt, Mesa, Python, GStreamer)
│   ├── bin/              ← Runtime helper binaries
│   ├── lib/              ← 3,500+ shared libraries
│   ├── share/            ← Icons, GSettings schemas, Glycin loaders, MIME
│   └── include/          ← Header files
├── pkgs/                 ← Isolated per-application payloads
│   ├── drawio-desktop/   ← App binaries, assets, and app-specific dependencies
│   ├── obsidian/
│   └── filezilla/
└── common/               ← Deduplicated hardlinked shared libraries

/usr/bin/                 ← Lightweight launcher wrapper scripts deployed for each app
/usr/share/applications/  ← Standard XDG desktop entry files for application menus
/var/log/packages/        ← Standard Slackware package logs (e.g. underpants-<app>-<ver>)

🛠️ Troubleshooting

If an application fails to launch or displays missing library warnings:

  1. Verify the runtime pool is installed: 
    gnomes runtime status
  2. Force re-transmutation of the application: 
    gnomes -S --force <app-name>
  3. Run storage deduplication to reclaim disk space: 
    gnomes dedup
  4. Purge old package cache: 
    gnomes -Sc