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

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
2. Nuevas Funciones
3. Gestión Central de Versiones
4. Métodos de Instalación
5. Flujos de Actualización
6. Pruebas con Dry-Run
7. Gestión de Logs
8. Uso Avanzado
9. 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:

chmod +x ./update-hyprland.sh
./update-hyprland.sh --help  # Ver todas las opciones

Flags clave:

• --fetch-latest: obtiene las últimas etiquetas desde GitHub
• --force-update: sobrescribe valores fijados en hypr-tags.env (equivalente a FORCE=1)
• --dry-run / --install: solo compilar o compilar+instalar
• --only / --skip: limitar qué módulos se ejecutan

dry-run-build.sh

Herramienta de pruebas que compila componentes sin instalarlos:

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:

# 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

# 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

# Instala solo Hyprland y componentes esenciales
./update-hyprland.sh --install

Método 3: Instalación Nueva con Últimas Versiones

# Obtiene últimas versiones de GitHub e instala
./update-hyprland.sh --fetch-latest --install

# Si tu hypr-tags.env tiene valores fijados y deseas sobrescribirlos:
./update-hyprland.sh --fetch-latest --force-update --install

Método 4: Instalación con Preset

# Usa un preset para elecciones automáticas
./install.sh --preset ./preset.sh

Flujos de Actualización

Enlace rápido: Actualización 0.49/0.50.x → 0.51.1

Actualizar a la Última Versión de Hyprland

Opción A: Descubrimiento Automático

# Obtiene las últimas etiquetas e instala (respeta versiones fijadas en hypr-tags.env)
./update-hyprland.sh --fetch-latest --install

# Forzar la actualización de todas las etiquetas (mismo efecto que ejecutar refresh con FORCE=1)
./update-hyprland.sh --fetch-latest --force-update --install

Opción B: Versión Específica

# Establece una versión específica de Hyprland
./update-hyprland.sh --set HYPRLAND=v0.51.1 --install

Opción C: Probar Antes de Instalar

# 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

# 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

# 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

Actualización: 0.49/0.50.x ➜ 0.51.1

Si actualmente estás en Hyprland 0.49 o 0.50.x, puedes actualizar directamente a 0.51.1 sin una reinstalación completa.

Ruta recomendada:

# Asegura que hypr-tags.env apunte a la versión objetivo (omitir si ya es v0.51.1)
./update-hyprland.sh --set HYPRLAND=v0.51.1

# Actualiza Hyprland (los prerrequisitos se incluyen y ordenan automáticamente)
./update-hyprland.sh --install --only hyprland

Notas:

• El comando garantiza y ejecuta, según sea necesario: wayland-protocols-src, hyprland-protocols, hyprutils, hyprlang, aquamarine y luego hyprland.
• No es necesario usar install.sh para esta actualización, a menos que también quieras instalar/actualizar módulos opcionales (p. ej., SDDM, Bluetooth, Thunar, AGS, dotfiles) o estés recuperándote de una instalación fallida/parcial.
• Opcional: agrega --with-deps para reinstalar dependencias primero:

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

• Puedes hacer un dry-run primero para validar:

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

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

# 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

# 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

# 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:

# Mantener solo logs de los últimos 30 días
find Install-Logs/ -name "*.log" -mtime +30 -delete

Uso Avanzado

Gestión de Versiones

Forzar la Actualización de Todas las Etiquetas

# Sobrescribe valores fijados en hypr-tags.env con las últimas versiones
./update-hyprland.sh --fetch-latest --force-update --dry-run
# Instalar si la dry-run es exitosa
./update-hyprland.sh --force-update --install

Copia de Seguridad y Restauración

# 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

# 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

# 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

# Controlar el paralelismo (por defecto: todos los núcleos)
export MAKEFLAGS="-j4"
./update-hyprland.sh --install

Flujo de Trabajo de Desarrollo

Probar Nuevos Lanzamientos

# 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

# 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:

# 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:

# 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:

# 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:

   # Verificar versión de Debian
   cat /etc/os-release
   
   # Asegurar deb-src habilitado
   grep -E "^deb-src" /etc/apt/sources.list
   

2. Verificar entorno:

   # Ver etiquetas actuales
   cat hypr-tags.env
   
   # Probar dry-run primero
   ./update-hyprland.sh --dry-run --only hyprland
   

3. Analizar logs:

   # 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:

# 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

# 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.