Debian-Hyprland/Debian-Hyprland-Install-Upgrade.md

Debian-Hyprland Install & Upgrade Guide

This guide covers the enhanced installation and upgrade workflows for KooL's Debian-Hyprland project, including new automation features, centralized version management, and dry-run capabilities.

Table of Contents

1. Overview
2. New Features
3. Flags Reference
4. Debian 13 (Trixie) Compatibility Mode
5. Central Version Management
6. Installation Methods
7. Upgrade Workflows
8. Dry-Run Testing
9. Log Management
10. Advanced Usage
11. Troubleshooting

Overview

The Debian-Hyprland project now includes enhanced automation and management tools while maintaining backward compatibility with the original install.sh script. The key additions are:

• Centralized version management via hypr-tags.env
• Automated dependency ordering for Hyprland 0.51.x requirements
• Dry-run compilation testing without system modifications
• Selective component updates via update-hyprland.sh
• GitHub latest tag fetching for automatic version discovery

New Features

Enhanced install.sh

The original install.sh script now includes:

• Tag consistency: Reads hypr-tags.env and exports version variables to all modules
• Automatic wayland-protocols: Installs wayland-protocols from source (≥1.45) before Hyprland
• Robust dependency ordering: Ensures prerequisites are built in the correct sequence

New Scripts

update-hyprland.sh

A focused tool for managing and building just the Hyprland stack:

chmod +x ./update-hyprland.sh
./update-hyprland.sh --help  # View all options

Key flags:

• --fetch-latest: pull latest release tags from GitHub
• --force-update: override pinned values in hypr-tags.env (equivalent to FORCE=1)
• --dry-run / --install: compile-only or compile+install
• --only / --skip: limit which modules run
• --build-trixie / --no-trixie: enable/disable Debian 13 (trixie) compatibility mode (auto-detected by default)

dry-run-build.sh

A testing tool that compiles components without installing:

chmod +x ./dry-run-build.sh
./dry-run-build.sh --help  # View all options

wayland-protocols-src.sh

A new module that builds wayland-protocols from source to satisfy Hyprland 0.51.x requirements.

Flags Reference

This repo provides several "control flags" that affect how the stack is built. These are intentionally consistent across tools.

update-hyprland.sh flags

• --install / --dry-run: compile+install vs compile-only
• --only <list> / --skip <list>: run a subset of modules
• --fetch-latest: query GitHub Releases and refresh tags
• --force-update: override pinned values in hypr-tags.env (equivalent to FORCE=1)
• --build-trixie / --no-trixie: enable/disable Debian 13 compatibility mode

Notes:

• When trixie mode is enabled, update-hyprland.sh exports HYPR_BUILD_TRIXIE=1 and forwards --build-trixie to module scripts.

install.sh flags

• --preset <file>: run unattended-ish using preset choices
• --build-trixie / --no-trixie: enable/disable Debian 13 compatibility mode

You can also force via env:

HYPR_BUILD_TRIXIE=1 ./install.sh

refresh-hypr-tags.sh flags

• --get-latest: refresh tags to latest GitHub releases (alias; refresh always checks latest)
• --force-update: force-override pinned values

Equivalent env form:

FORCE=1 ./refresh-hypr-tags.sh --get-latest

Debian 13 (Trixie) Compatibility Mode

Newer Hyprland versions (0.53.x+) may require source-level compatibility shims on Debian 13 (trixie) due to toolchain / standard-library feature gaps.

• Default behavior is auto-detect (via /etc/os-release): if ID=debian and VERSION_CODENAME=trixie, compatibility mode turns on.
• You can force it on/off:

# Force ON
./update-hyprland.sh --build-trixie --install

# Force OFF
./update-hyprland.sh --no-trixie --install

Central Version Management

hypr-tags.env

This file contains version tags for all Hyprland components:

# Current versions (example)
HYPRLAND_TAG=v0.53.2
AQUAMARINE_TAG=v0.10.0
HYPRUTILS_TAG=v0.11.0
HYPRLANG_TAG=v0.6.8
HYPRGRAPHICS_TAG=v0.5.0
HYPRTOOLKIT_TAG=v0.4.1
HYPRWAYLAND_SCANNER_TAG=v0.4.5
HYPRLAND_PROTOCOLS_TAG=v0.7.0
HYPRLAND_QT_SUPPORT_TAG=v0.1.0
HYPRLAND_QTUTILS_TAG=v0.1.5
HYPRLAND_GUIUTILS_TAG=v0.2.0
HYPRWIRE_TAG=v0.2.1
WAYLAND_PROTOCOLS_TAG=1.46

Refreshing tags (latest releases)

You can refresh hypr-tags.env to the latest GitHub release tags:

# Update only keys set to auto/latest (or unset)
./refresh-hypr-tags.sh --get-latest

# Force-override pinned keys
FORCE=1 ./refresh-hypr-tags.sh --get-latest
# or
./refresh-hypr-tags.sh --force-update

Version Override Priority

1. Environment variables (exported)
2. hypr-tags.env file values
3. Default hardcoded values in each module

Installation Methods

Method 1: Original Full Installation

# Standard installation with all components
chmod +x install.sh
./install.sh

This method now automatically:

• Loads versions from hypr-tags.env
• Installs wayland-protocols from source before Hyprland
• Maintains proper dependency ordering

Method 2: Hyprland Stack Only

# Install only Hyprland and essential components
./update-hyprland.sh --install

Method 3: Fresh Installation with Latest Versions

# Fetch latest GitHub releases and install
./update-hyprland.sh --fetch-latest --install

# If your hypr-tags.env has pinned values and you want to override them:
./update-hyprland.sh --fetch-latest --force-update --install

Method 4: Preset-Based Installation

# Use preset file for automated choices
./install.sh --preset ./preset.sh

Upgrade Workflows

Quick link: Upgrade 0.49/0.50.x → 0.51.1

Upgrading to Latest Hyprland Release

Option A: Automatic Discovery

# Fetch latest tags and install (respects pins in hypr-tags.env)
./update-hyprland.sh --fetch-latest --install

# Force-override pinned values (same effect as running refresh with FORCE=1)
./update-hyprland.sh --fetch-latest --force-update --install

Option B: Specific Version

# Set specific Hyprland version
./update-hyprland.sh --set HYPRLAND=v0.51.1 --install

Option C: Test Before Installing

# Test compilation first, then install if successful
./update-hyprland.sh --fetch-latest --dry-run
# If successful:
./update-hyprland.sh --install

Upgrading Individual Components

# Update only core libraries (often needed for new Hyprland versions)
./update-hyprland.sh --fetch-latest --install --only hyprutils,hyprlang

# Update aquamarine specifically
./update-hyprland.sh --set AQUAMARINE=v0.9.3 --install --only aquamarine

Selective Updates

# Install everything except Qt components
./update-hyprland.sh --install --skip hyprland-qt-support,hyprland-qtutils

# Install only specific components
./update-hyprland.sh --install --only hyprland,aquamarine

Upgrade: 0.49/0.50.x ➜ 0.51.1

If you’re currently on Hyprland 0.49 or 0.50.x, you can upgrade directly to 0.51.1 without a full reinstall.

Recommended path:

# Ensure hypr-tags.env pins the target version (skip if already v0.51.1)
./update-hyprland.sh --set HYPRLAND=v0.51.1

# Upgrade Hyprland (prerequisites are auto-included and ordered)
./update-hyprland.sh --install --only hyprland

Notes:

• The command will automatically ensure and run, as needed: wayland-protocols-src, hyprland-protocols, hyprutils, hyprlang, aquamarine, then hyprland.
• Full install via install.sh is not required for this upgrade unless you also want to install/refresh optional modules (e.g., SDDM, Bluetooth, Thunar, AGS, dotfiles) or you’re recovering from a failed/partial setup.
• Optional: add --with-deps to re-run dependency installation first:

./update-hyprland.sh --with-deps --install --only hyprland

• You can dry-run first to validate:

./update-hyprland.sh --dry-run --only hyprland

Dry-Run Testing

Why Use Dry-Run?

• Test compilation compatibility before installing
• Validate version combinations
• Debug build issues without system changes
• CI/CD pipeline integration

Basic Dry-Run Usage

# Test current tag configuration
./update-hyprland.sh --dry-run

# Test with latest GitHub releases
./update-hyprland.sh --fetch-latest --dry-run

# Test specific version
./update-hyprland.sh --set HYPRLAND=v0.51.1 --dry-run

Advanced Dry-Run Testing

# Use alternative summary format
./update-hyprland.sh --via-helper

# Test with dependencies installation
./dry-run-build.sh --with-deps

# Test only specific components
./dry-run-build.sh --only hyprland,aquamarine

Dry-Run Limitations

• Dependencies still install: apt operations run to ensure compilation succeeds
• pkg-config requirements: Some components need system-installed prerequisites
• No system changes: No files installed to /usr/local or /usr

Log Management

Build Artifacts & Cleanup

All source clones and build outputs now live under ~/Debian-Hyprland/build/:

• Sources: build/src/<project>
• Build output: build/<project>

This keeps the repo root clean. To remove all build artifacts:

rm -rf ~/Debian-Hyprland/build

Note: This only removes build artifacts and downloaded sources; it does not uninstall anything from your system.

Log Location

All build activities generate timestamped logs in:

Install-Logs/
├── 01-Hyprland-Install-Scripts-YYYY-MM-DD-HHMMSS.log  # Main install log
├── install-DD-HHMMSS_module-name.log                   # Per-module logs
├── build-dry-run-YYYY-MM-DD-HHMMSS.log                # Dry-run summary
└── update-hypr-YYYY-MM-DD-HHMMSS.log                  # Update tool summary

Log Analysis

# View most recent install log
ls -t Install-Logs/*.log | head -1 | xargs less

# Check for errors in specific module
grep -i error Install-Logs/install-*hyprland*.log

# View dry-run summary
cat Install-Logs/build-dry-run-*.log

Log Retention

• Logs accumulate over time for historical reference
• Manual cleanup recommended periodically:

# Keep only logs from last 30 days
find Install-Logs/ -name "*.log" -mtime +30 -delete

Advanced Usage

Tag Management

Force Update All Tags

# Override pinned values in hypr-tags.env to the latest releases
./update-hyprland.sh --fetch-latest --force-update --dry-run
# Install if the dry-run succeeds
./update-hyprland.sh --force-update --install

Backup and Restore

# Tags are automatically backed up on changes
# Restore most recent backup
./update-hyprland.sh --restore --dry-run

Multiple Version Sets

# Save current configuration
cp hypr-tags.env hypr-tags-stable.env

# Try experimental versions
./update-hyprland.sh --fetch-latest --dry-run

# Restore stable if needed
cp hypr-tags-stable.env hypr-tags.env

Environment Integration

Custom PKG_CONFIG_PATH

# Ensure /usr/local takes precedence
export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:/usr/local/share/pkgconfig:${PKG_CONFIG_PATH:-}"
./update-hyprland.sh --install

Parallel Builds

# Control build parallelism (default: all cores)
export MAKEFLAGS="-j4"
./update-hyprland.sh --install

Development Workflow

Testing New Releases

# 1. Create test environment
cp hypr-tags.env hypr-tags.backup

# 2. Test new version
./update-hyprland.sh --set HYPRLAND=v0.52.0 --dry-run

# 3. Install if successful
./update-hyprland.sh --install

# 4. Rollback if issues
./update-hyprland.sh --restore --install

Component Development

# Install dependencies only
./update-hyprland.sh --with-deps --dry-run

# Manual module testing
DRY_RUN=1 ./install-scripts/hyprland.sh

# Check logs for specific module
tail -f Install-Logs/install-*hyprland*.log

Troubleshooting

Common Issues

CMake Configuration Fails

Symptoms: "Package dependency requirement not satisfied"

Solutions:

# Install missing prerequisites
./update-hyprland.sh --install --only wayland-protocols-src,hyprutils,hyprlang

# Clear build cache
rm -rf hyprland aquamarine hyprutils hyprlang

# Retry installation
./update-hyprland.sh --install --only hyprland

Compilation Errors

Symptoms: "too many errors emitted"

Solutions:

# Update core dependencies first
./update-hyprland.sh --fetch-latest --install --only hyprutils,hyprlang

# Check for API mismatches in logs
grep -A5 -B5 "error:" Install-Logs/install-*hyprland*.log

Tag Not Found

Symptoms: "Remote branch X not found"

Solutions:

# Check available tags
git ls-remote --tags https://github.com/hyprwm/Hyprland

# Use confirmed existing tag
./update-hyprland.sh --set HYPRLAND=v0.50.1 --install

Debug Steps

1. Check system compatibility:

   # Verify Debian version
   cat /etc/os-release
   
   # Ensure deb-src enabled
   grep -E "^deb-src" /etc/apt/sources.list
   

2. Verify environment:

   # Check current tags
   cat hypr-tags.env
   
   # Test dry-run first
   ./update-hyprland.sh --dry-run --only hyprland
   

3. Analyze logs:

   # Most recent errors
   grep -i "error\|fail" Install-Logs/*.log | tail -20
   
   # Module-specific issues
   ls -la Install-Logs/install-*[component]*.log
   

Getting Help

1. Check logs: Always review Install-Logs/ for detailed error information
2. Test dry-run: Use --dry-run to validate before installing
3. Community support: Submit issues with relevant log excerpts
4. Documentation: Refer to main project README.md for base requirements

Migration from Previous Versions

Existing Installations

The new tools work alongside existing installations:

# Update existing installation
./update-hyprland.sh --install

# Test without affecting current system
./update-hyprland.sh --dry-run

Converting to Tag Management

# Current versions are saved to hypr-tags.env automatically
# Verify with:
cat hypr-tags.env

# Modify versions as needed:
./update-hyprland.sh --set HYPRLAND=v0.51.1

The enhanced workflow provides better control, testing capabilities, and automation while maintaining full compatibility with the original installation process.