diff --git a/Debian-Hyprland-Install-Upgrade.es.md b/Debian-Hyprland-Install-Upgrade.es.md new file mode 100644 index 0000000..f79ca2d --- /dev/null +++ b/Debian-Hyprland-Install-Upgrade.es.md @@ -0,0 +1,396 @@ +# Guía de Instalación y Actualización de Debian-Hyprland + +Esta guía cubre los flujos de instalación y actualización mejorados para el proyecto Debian-Hyprland de KooL, incluyendo nuevas funciones de automatización, gestión centralizada de versiones y capacidades de dry-run. + +## Tabla de Contenidos + +1. [Resumen](#resumen) +2. [Nuevas Funciones](#nuevas-funciones) +3. [Gestión Central de Versiones](#gestión-central-de-versiones) +4. [Métodos de Instalación](#métodos-de-instalación) +5. [Flujos de Actualización](#flujos-de-actualización) +6. [Pruebas con Dry-Run](#pruebas-con-dry-run) +7. [Gestión de Logs](#gestión-de-logs) +8. [Uso Avanzado](#uso-avanzado) +9. [Solución de Problemas](#solución-de-problemas) + +## Resumen + +El proyecto Debian-Hyprland ahora incluye herramientas de automatización y gestión mejoradas, manteniendo la compatibilidad con el script original install.sh. Las principales adiciones son: + +- **Gestión centralizada de versiones** mediante `hypr-tags.env` +- **Orden automático de dependencias** para los requisitos de Hyprland 0.51.x +- **Pruebas de compilación con dry-run** sin modificar el sistema +- **Actualizaciones selectivas de componentes** con `update-hyprland.sh` +- **Obtención automática de últimas versiones** desde GitHub + +## Nuevas Funciones + +### install.sh mejorado +El script original ahora: + +- **Unifica versiones**: Lee `hypr-tags.env` y exporta variables de versión a todos los módulos +- **wayland-protocols automático**: Instala wayland-protocols desde el código fuente (≥1.45) antes de Hyprland +- **Orden robusto de dependencias**: Garantiza la secuencia correcta de requisitos + +### Nuevos Scripts + +#### update-hyprland.sh +Herramienta enfocada para gestionar y compilar solo el stack de Hyprland: +```bash +chmod +x ./update-hyprland.sh +./update-hyprland.sh --help # Ver todas las opciones +``` + +#### dry-run-build.sh +Herramienta de pruebas que compila componentes sin instalarlos: +```bash +chmod +x ./dry-run-build.sh +./dry-run-build.sh --help # Ver todas las opciones +``` + +#### wayland-protocols-src.sh +Módulo que compila wayland-protocols desde el origen para satisfacer los requisitos de Hyprland 0.51.x. + +## Gestión Central de Versiones + +### hypr-tags.env +Archivo con etiquetas de versión para todos los componentes de Hyprland: + +```bash +# Versiones actuales (ejemplo) +HYPRLAND_TAG=v0.51.1 +AQUAMARINE_TAG=v0.9.3 +HYPRUTILS_TAG=v0.8.2 +HYPRLANG_TAG=v0.6.4 +HYPRGRAPHICS_TAG=v0.1.5 +HYPRWAYLAND_SCANNER_TAG=v0.4.5 +HYPRLAND_PROTOCOLS_TAG=v0.6.4 +HYPRLAND_QT_SUPPORT_TAG=v0.1.0 +HYPRLAND_QTUTILS_TAG=v0.1.4 +WAYLAND_PROTOCOLS_TAG=1.45 +``` + +### Prioridad de Sobrescritura de Versiones +1. Variables de entorno (exportadas) +2. Valores en el archivo `hypr-tags.env` +3. Valores por defecto en cada módulo + +## Métodos de Instalación + +### Método 1: Instalación Completa Original +```bash +# Instalación estándar con todos los componentes +chmod +x install.sh +./install.sh +``` + +Ahora, este método automáticamente: +- Carga versiones desde `hypr-tags.env` +- Instala wayland-protocols desde el origen antes de Hyprland +- Mantiene el orden correcto de dependencias + +### Método 2: Solo el Stack de Hyprland +```bash +# Instala solo Hyprland y componentes esenciales +./update-hyprland.sh --install +``` + +### Método 3: Instalación Nueva con Últimas Versiones +```bash +# Obtiene últimas versiones de GitHub e instala +./update-hyprland.sh --fetch-latest --install +``` + +### Método 4: Instalación con Preset +```bash +# Usa un preset para elecciones automáticas +./install.sh --preset ./preset.sh +``` + +## Flujos de Actualización + +### Actualizar a la Última Versión de Hyprland + +#### Opción A: Descubrimiento Automático +```bash +# Obtiene las últimas etiquetas e instala +./update-hyprland.sh --fetch-latest --install +``` + +#### Opción B: Versión Específica +```bash +# Establece una versión específica de Hyprland +./update-hyprland.sh --set HYPRLAND=v0.51.1 --install +``` + +#### Opción C: Probar Antes de Instalar +```bash +# Prueba la compilación primero, luego instala si es exitoso +./update-hyprland.sh --fetch-latest --dry-run +# Si es exitoso: +./update-hyprland.sh --install +``` + +### Actualizar Componentes Individuales + +```bash +# Actualiza solo librerías núcleo (a menudo necesario para nuevas versiones de Hyprland) +./update-hyprland.sh --fetch-latest --install --only hyprutils,hyprlang + +# Actualiza aquamarine específicamente +./update-hyprland.sh --set AQUAMARINE=v0.9.3 --install --only aquamarine +``` + +### Actualizaciones Selectivas + +```bash +# Instalar todo excepto los componentes Qt +./update-hyprland.sh --install --skip hyprland-qt-support,hyprland-qtutils + +# Instalar solo componentes específicos +./update-hyprland.sh --install --only hyprland,aquamarine +``` + +## Pruebas con Dry-Run + +### ¿Por qué usar Dry-Run? +- Probar compatibilidad de compilación antes de instalar +- Validar combinaciones de versiones +- Depurar problemas de compilación sin cambios en el sistema +- Integración en CI/CD + +### Uso Básico de Dry-Run + +```bash +# Probar la configuración actual de versiones +./update-hyprland.sh --dry-run + +# Probar con últimas versiones de GitHub +./update-hyprland.sh --fetch-latest --dry-run + +# Probar una versión específica +./update-hyprland.sh --set HYPRLAND=v0.51.1 --dry-run +``` + +### Pruebas Avanzadas con Dry-Run + +```bash +# Formato alternativo de resumen +./update-hyprland.sh --via-helper + +# Probar con instalación de dependencias +./dry-run-build.sh --with-deps + +# Probar solo componentes específicos +./dry-run-build.sh --only hyprland,aquamarine +``` + +### Limitaciones de Dry-Run +- **Las dependencias se instalan**: apt se ejecuta para asegurar la compilación +- **Requisitos de pkg-config**: Algunos componentes necesitan requisitos instalados en el sistema +- **Sin cambios en el sistema**: No instala archivos en /usr/local o /usr + +## Gestión de Logs + +### Ubicación de Logs +Todas las actividades de construcción generan logs con sello de tiempo en: +``` +Install-Logs/ +├── 01-Hyprland-Install-Scripts-YYYY-MM-DD-HHMMSS.log # Log principal de instalación +├── install-DD-HHMMSS_module-name.log # Logs por módulo +├── build-dry-run-YYYY-MM-DD-HHMMSS.log # Resumen de dry-run +└── update-hypr-YYYY-MM-DD-HHMMSS.log # Resumen de actualización +``` + +### Análisis de Logs +```bash +# Ver el log de instalación más reciente +ls -t Install-Logs/*.log | head -1 | xargs less + +# Buscar errores en un módulo específico +grep -i error Install-Logs/install-*hyprland*.log + +# Ver resumen de dry-run +cat Install-Logs/build-dry-run-*.log +``` + +### Retención de Logs +- Los logs se acumulan con el tiempo para referencia histórica +- Se recomienda limpieza manual periódica: +```bash +# Mantener solo logs de los últimos 30 días +find Install-Logs/ -name "*.log" -mtime +30 -delete +``` + +## Uso Avanzado + +### Gestión de Versiones + +#### Copia de Seguridad y Restauración +```bash +# Las etiquetas se respaldan automáticamente cuando cambian +# Restaurar la copia más reciente +./update-hyprland.sh --restore --dry-run +``` + +#### Múltiples Conjuntos de Versiones +```bash +# Guardar configuración actual +cp hypr-tags.env hypr-tags-stable.env + +# Probar versiones experimentales +./update-hyprland.sh --fetch-latest --dry-run + +# Restaurar estable si es necesario +cp hypr-tags-stable.env hypr-tags.env +``` + +### Integración con el Entorno + +#### PKG_CONFIG_PATH personalizado +```bash +# Asegurar que /usr/local tenga prioridad +export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:/usr/local/share/pkgconfig:${PKG_CONFIG_PATH:-}" +./update-hyprland.sh --install +``` + +#### Compilaciones en Paralelo +```bash +# Controlar el paralelismo (por defecto: todos los núcleos) +export MAKEFLAGS="-j4" +./update-hyprland.sh --install +``` + +### Flujo de Trabajo de Desarrollo + +#### Probar Nuevos Lanzamientos +```bash +# 1. Crear entorno de pruebas +cp hypr-tags.env hypr-tags.backup + +# 2. Probar nueva versión +./update-hyprland.sh --set HYPRLAND=v0.52.0 --dry-run + +# 3. Instalar si es exitoso +./update-hyprland.sh --install + +# 4. Revertir si hay problemas +./update-hyprland.sh --restore --install +``` + +#### Desarrollo de Componentes +```bash +# Solo instalar dependencias +./update-hyprland.sh --with-deps --dry-run + +# Pruebas manuales de módulo +DRY_RUN=1 ./install-scripts/hyprland.sh + +# Ver logs de un módulo específico +tail -f Install-Logs/install-*hyprland*.log +``` + +## Solución de Problemas + +### Problemas Comunes + +#### Falla de Configuración con CMake +**Síntomas**: "Package dependency requirement not satisfied" + +**Soluciones**: +```bash +# Instalar requisitos faltantes +./update-hyprland.sh --install --only wayland-protocols-src,hyprutils,hyprlang + +# Limpiar caché de compilación +rm -rf hyprland aquamarine hyprutils hyprlang + +# Reintentar instalación +./update-hyprland.sh --install --only hyprland +``` + +#### Errores de Compilación +**Síntomas**: "too many errors emitted" + +**Soluciones**: +```bash +# Actualizar dependencias núcleo primero +./update-hyprland.sh --fetch-latest --install --only hyprutils,hyprlang + +# Revisar incompatibilidades de API en logs +grep -A5 -B5 "error:" Install-Logs/install-*hyprland*.log +``` + +#### Etiqueta No Encontrada +**Síntomas**: "Remote branch X not found" + +**Soluciones**: +```bash +# Ver etiquetas disponibles +git ls-remote --tags https://github.com/hyprwm/Hyprland + +# Usar etiqueta confirmada +./update-hyprland.sh --set HYPRLAND=v0.50.1 --install +``` + +### Pasos de Depuración + +1. **Verificar compatibilidad del sistema**: + ```bash + # Verificar versión de Debian + cat /etc/os-release + + # Asegurar deb-src habilitado + grep -E "^deb-src" /etc/apt/sources.list + ``` + +2. **Verificar entorno**: + ```bash + # Ver etiquetas actuales + cat hypr-tags.env + + # Probar dry-run primero + ./update-hyprland.sh --dry-run --only hyprland + ``` + +3. **Analizar logs**: + ```bash + # Errores más recientes + grep -i "error\|fail" Install-Logs/*.log | tail -20 + + # Problemas por módulo + ls -la Install-Logs/install-*[component]*.log + ``` + +### Obtener Ayuda + +1. **Revisar logs**: Consulte siempre Install-Logs/ para detalles +2. **Probar dry-run**: Valide antes de instalar +3. **Soporte de la comunidad**: Envíe issues con extractos de logs +4. **Documentación**: Consulte README.md del proyecto para requisitos base + +## Migración desde Versiones Previas + +### Instalaciones Existentes +Las nuevas herramientas funcionan junto a instalaciones existentes: + +```bash +# Actualizar instalación existente +./update-hyprland.sh --install + +# Probar sin afectar el sistema actual +./update-hyprland.sh --dry-run +``` + +### Convertir a Gestión por Etiquetas +```bash +# Las versiones actuales se guardan en hypr-tags.env automáticamente +# Verificar con: +cat hypr-tags.env + +# Modificar versiones según necesidad: +./update-hyprland.sh --set HYPRLAND=v0.51.1 +``` + +El flujo mejorado ofrece mayor control, capacidad de prueba y automatización, manteniendo la compatibilidad total con el proceso de instalación original. diff --git a/Debian-Hyprland-Install-Upgrade.md b/Debian-Hyprland-Install-Upgrade.md new file mode 100644 index 0000000..46dff79 --- /dev/null +++ b/Debian-Hyprland-Install-Upgrade.md @@ -0,0 +1,396 @@ +# 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](#overview) +2. [New Features](#new-features) +3. [Central Version Management](#central-version-management) +4. [Installation Methods](#installation-methods) +5. [Upgrade Workflows](#upgrade-workflows) +6. [Dry-Run Testing](#dry-run-testing) +7. [Log Management](#log-management) +8. [Advanced Usage](#advanced-usage) +9. [Troubleshooting](#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: +```bash +chmod +x ./update-hyprland.sh +./update-hyprland.sh --help # View all options +``` + +#### dry-run-build.sh +A testing tool that compiles components without installing: +```bash +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. + +## Central Version Management + +### hypr-tags.env +This file contains version tags for all Hyprland components: + +```bash +# Current versions (example) +HYPRLAND_TAG=v0.51.1 +AQUAMARINE_TAG=v0.9.3 +HYPRUTILS_TAG=v0.8.2 +HYPRLANG_TAG=v0.6.4 +HYPRGRAPHICS_TAG=v0.1.5 +HYPRWAYLAND_SCANNER_TAG=v0.4.5 +HYPRLAND_PROTOCOLS_TAG=v0.6.4 +HYPRLAND_QT_SUPPORT_TAG=v0.1.0 +HYPRLAND_QTUTILS_TAG=v0.1.4 +WAYLAND_PROTOCOLS_TAG=1.45 +``` + +### 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 +```bash +# 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 +```bash +# Install only Hyprland and essential components +./update-hyprland.sh --install +``` + +### Method 3: Fresh Installation with Latest Versions +```bash +# Fetch latest GitHub releases and install +./update-hyprland.sh --fetch-latest --install +``` + +### Method 4: Preset-Based Installation +```bash +# Use preset file for automated choices +./install.sh --preset ./preset.sh +``` + +## Upgrade Workflows + +### Upgrading to Latest Hyprland Release + +#### Option A: Automatic Discovery +```bash +# Fetch latest tags and install +./update-hyprland.sh --fetch-latest --install +``` + +#### Option B: Specific Version +```bash +# Set specific Hyprland version +./update-hyprland.sh --set HYPRLAND=v0.51.1 --install +``` + +#### Option C: Test Before Installing +```bash +# Test compilation first, then install if successful +./update-hyprland.sh --fetch-latest --dry-run +# If successful: +./update-hyprland.sh --install +``` + +### Upgrading Individual Components + +```bash +# 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 + +```bash +# 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 +``` + +## 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 + +```bash +# 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 + +```bash +# 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 + +### 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 +```bash +# 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: +```bash +# Keep only logs from last 30 days +find Install-Logs/ -name "*.log" -mtime +30 -delete +``` + +## Advanced Usage + +### Tag Management + +#### Backup and Restore +```bash +# Tags are automatically backed up on changes +# Restore most recent backup +./update-hyprland.sh --restore --dry-run +``` + +#### Multiple Version Sets +```bash +# 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 +```bash +# 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 +```bash +# Control build parallelism (default: all cores) +export MAKEFLAGS="-j4" +./update-hyprland.sh --install +``` + +### Development Workflow + +#### Testing New Releases +```bash +# 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 +```bash +# 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**: +```bash +# 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**: +```bash +# 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**: +```bash +# 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**: + ```bash + # Verify Debian version + cat /etc/os-release + + # Ensure deb-src enabled + grep -E "^deb-src" /etc/apt/sources.list + ``` + +2. **Verify environment**: + ```bash + # Check current tags + cat hypr-tags.env + + # Test dry-run first + ./update-hyprland.sh --dry-run --only hyprland + ``` + +3. **Analyze logs**: + ```bash + # 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: + +```bash +# Update existing installation +./update-hyprland.sh --install + +# Test without affecting current system +./update-hyprland.sh --dry-run +``` + +### Converting to Tag Management +```bash +# 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. \ No newline at end of file