Installation #
MenuForge utilizes a universal deployment strategy designed to work across the major Linux families (Arch, Debian, Fedora, OpenSUSE). The installer automatically identifies the host's package manager and bootstraps the environment by configuring official repositories for the gum TUI framework.
./install.sh --needed
The deployment process involves three distinct phases: Environment Validation (Hardware/OS detection), Dependency Resolution (Dynamic package mapping), and Binary Linkage (Deploying scripts to ~/.local/bin and generating XDG-compliant desktop entries).
Core Functions #
The architectural foundation of MenuForge is menuforge-lib.sh. This shared module ensures that all suite components—the installer, the dependency manager, and the main TUI—operate on the same hardware intelligence and theming logic. It eliminates code redundancy and provides a unified API for third-party expansion.
| Function | Returns | Detailed Description |
|---|
detect_nvidia() | HAS_NVIDIA | Conducts a deep scan of the PCI bus using lspci -nn to identify proprietary NVIDIA 3D controllers, essential for hybrid graphics orchestration. |
detect_pkg_manager() | PKG_MANAGER | Interrogates the system binary path to route installation commands through apt, dnf, zypper, or pacman (including AUR support). |
get_deps() | DEPS | A hardware-aware resolver that returns a curated list of high-performance libraries (mangohud, gamescope, etc.) specifically mapped to the host's OS naming conventions. |
detect_theme() | PRIMARY | A multi-tiered engine that attempts to sync TUI colors with user-defined overrides, KDE Plasma's active accent colors, or official distribution branding. |
banner(title, sub) | void | Renders a standardized, high-fidelity ASCII header with consistent project metadata across all interactive modules. |
TUI Application #
The main menuforge script provides a terminal-native control center for desktop entry lifecycle management. It uses recursive file picking to locate binaries and allows users to inject multi-layered performance hooks (like Gamescope resolution virtualization) without editing raw text files. Every link generated is metadata-tagged for clean auditing and one-click removal.
menuforge # Initiates the system controller
Hardware Engine #
Unlike simple generators, MenuForge is hardware-aware. The Hardware Engine prevents infrastructure bloat by only offering optimizations that your hardware can actually execute. For example, the NVIDIA Prime Run layer is hidden on single-GPU systems to prevent configuration errors.
lspci -nn | grep -iE "vga|3d" | grep -iq "nvidia"
This surgical detection logic ensures that generated .desktop files are optimized for the specific machine they were forged on, leading to higher stability in gaming and professional workloads.
Theme Engine #
MenuForge features a sophisticated hybrid theme engine designed to make the TUI feel like a native part of your operating system. It respects the visual identity of the host distribution while allowing for deep customization.
| Priority | Source | Description |
|---|
| 1. Manual Override | gum.env.conf | Users can define custom HEX codes in ~/.config/omarchy/ for complete visual control. |
| 2. DE Integration | kreadconfig5 | On KDE Plasma, MenuForge interrogates the system API to adopt the user's active Accent Color. |
| 3. OS Branding | /etc/os-release | Fallback to official colors: Arch Blue, Mint Green, Ubuntu Orange, or Fedora Blue based on distribution ID. |
CLI Reference #
The menuforge binary serves as the primary system entry point. It intelligently routes CLI arguments to their respective technical modules.
| Flag | Description |
|---|
(no args) | Initiates the primary high-fidelity TUI environment. |
--doctor | Triggers a four-phase system integrity audit (Env, Deps, HW, Shortcuts). |
--version, -v | Displays the active system version and official authorship credits. |
--help, -h | Renders the comprehensive technical usage and example reference. |
