mirror of https://github.com/LinuxBeginnings/OpenSuse-Hyprland.git synced 2026-01-11 15:00:59 -03:00

Files

Don Williams f5b4a9cca0 docs: add WARP.md with essential commands, architecture, and AGS/SSH caveats

Context:
- Investigated report that `ags -t overview` returns "undefined" when executed over SSH on the openSUSE host.
- Over SSH there is no graphical session (DISPLAY/WAYLAND_DISPLAY unset) and typically no running AGS instance to receive the toggle command, so `ags` prints "undefined". This is expected behavior in a headless shell.

What this change does:
- Introduces project-scoped WARP.md to accelerate future work in this repo.
- Captures essential commands: interactive install, preset usage, re-running individual modules from repo root, auto-install wrapper, uninstall, and log tailing.
- Summarizes the high-level modular architecture (entrypoint flow, environment detection, module library with Global_functions helpers, and automation scripts).
- Notes key usage constraints pulled from README (don’t run as root, SDDM disabled if other display managers are active, NVIDIA G06 path, VM 3D accel requirement).
- Documents the practical caveat uncovered during AGS debugging: headless/SSH shells will not be able to toggle AGS UI and will show "undefined" unless an AGS instance is running in the user’s Wayland session.

Why now:
- The lack of a repo-scoped WARP.md made it slower to reason about installer modules and the AGS behavior. This doc helps future troubleshooting and contributions.

Follow-ups (not in this commit):
- Consider adding a guard to the AGS wrapper created by install-scripts/ags.sh to detect missing DISPLAY/WAYLAND_DISPLAY or missing running AGS instance and print a helpful message instead of surfacing the raw "undefined".
- Optional: shellcheck/shfmt pass for bash modules (no configured linters here).

2025-11-04 16:49:35 -05:00

3.9 KiB

Raw Permalink Blame History

WARP.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

Essential commands

Install (interactive)
- chmod +x install.sh && ./install.sh

Install with a preset file

./install.sh --preset presets/my-desktop.preset

Example preset (ON/OFF strings are read via source):

gtk_themes="ON"
bluetooth="OFF"
thunar="ON"
ags="ON"
sddm="OFF"
sddm_theme="OFF"
xdph="ON"
zsh="ON"
pokemon="OFF"
rog="OFF"
dots="ON"
input_group="OFF"
nvidia="OFF"

Re-run a specific module (from repo root; do not cd into install-scripts)
- ./install-scripts/<script-name>.sh
- Examples: ./install-scripts/gtk_themes.sh, ./install-scripts/sddm.sh, ./install-scripts/04-Final-Check.sh
Auto installer (local wrapper)
- ./auto-install.sh
Uninstall (guided)
- chmod +x uninstall.sh && ./uninstall.sh
Logs
- All runs write timestamped logs to Install-Logs/
- Tail last log: ls -t Install-Logs | head -n1 | xargs -I{} tail -n 200 -f Install-Logs/{}

Notes from README that affect usage

Do not run as root; run from a directory where you have write permissions (e.g., your home).
If a login manager like GDM/LightDM is active, SDDM install options will be disabled until you stop/disable them and reboot.
On NVIDIA systems, the script can configure the G06 driver when you select the NVIDIA option.
In VMs, enable 3D acceleration or Hyprland may not start.

High-level architecture

This repo is a modular Bash installer for Hyprland on openSUSE Tumbleweed. There is no build or test suite; development involves editing shell modules and running them.

Entry point: install.sh
- Guards: not-root, ensures whiptail/pciutils exist, logs to Install-Logs/.
- Interactive flow (whiptail) selects features; supports --preset <file> by sourcing ON/OFF flags.
- Environment detection: active login managers (disables SDDM path), NVIDIA GPU prompt.
- Orchestration order (core): adds Packman repo → installs base deps → fonts → Hyprland core → ecosystem → forced installs → OBS/opi pkgs → wallust → optional selections → final cleanup → final package check.
- Executes modules via a helper that keeps paths and executability consistent.
Module library: install-scripts/
- Global_functions.sh: shared helpers used by all modules
  - zypper/opi install variants (normal, no-recommends, force, auto-agree), cargo install, package removal
  - progress spinner, colorized output, central logging
- Core modules (representative)
  - 00-add-repo.sh (Packman), 01-dependencies.sh (patterns + opi), hyprland.sh (Hyprland packages)
  - 02-hypr-pkgs.sh (main and secondary desktop packages, no-recommends list, uninstall conflicts), 03-opi-pkgs.sh (OBS via opi)
  - force-install.sh (reinstall edge cases), 04-Final-Check.sh (verifies essential packages and /usr/local tools)
- Optional feature modules (selected in install.sh)
  - Examples: sddm.sh and sddm_theme.sh, gtk_themes.sh, xdph.sh (xdg-desktop-portal-hyprland), bluetooth.sh, thunar.sh (+ thunar_default.sh), ags.sh (builds AGS v1.9.0 via git/npm/meson and installs wrapper in /usr/local/bin), nvidia.sh, rog.sh, dotfiles-main.sh, wallust.sh, InputGroup.sh, zsh.sh, zsh_pokemon.sh
Automation/maintenance
- auto-install.sh: clone-or-update then run install.sh
- uninstall.sh: interactive package and config removal (zypper removes, deletes ~/.config/* selections)

Repository documents considered

README.md: usage, prerequisites, uninstall availability, and operational caveats (NVIDIA, SDDM, VM acceleration, re-running modules from repo root).
CONTRIBUTING.md and .github/PULL_REQUEST_TEMPLATE.md: contribution flow; no repo-defined lint/typecheck/test commands.

What’s not here

No configured linter, formatter, or test suite in this repo. If you need linting, run your preferred shell tools locally (e.g., shellcheck, shfmt) but there are no project scripts for them.