🔧 Dependency Troubleshooting¶

Sistema de diagnóstico y resolución de problemas con dependencias.

🎯 Propósito¶

Este directorio contiene el Stack Overflow interno de AudioLab: una knowledge base de problemas comunes y sus soluciones.

Filosofía: Si un problema te costó >30 minutos resolverlo, documéntalo aquí para que nadie más pierda ese tiempo.

📚 Documentación Disponible¶

DEPENDENCY_TROUBLESHOOTING_GUIDE.md ¶

Knowledge base completa de problemas y soluciones.

Contiene:

🔴 Problemas Críticos¶

vcpkg install failures
JUCE not found
CMake configuration errors
Linker errors

🟡 Problemas Importantes¶

Version conflicts
Slow downloads
Cache issues
Deprecated API warnings

🟢 Problemas Menores¶

Certificate errors
Baseline outdated
Binary cache misses
Git LFS bandwidth limits

🖥️ Platform-Specific¶

Windows: Long paths, Visual Studio issues
Linux: Missing system libraries, old compilers
macOS: Xcode tools, code signing

🚀 Quick Start¶

Si tienes un problema AHORA¶

# 1. Verificar instalación básica
cd "C:\AudioDev\audio-lab"
.\verify_installation.ps1 -Detailed

# 2. Limpiar build
.\clean.ps1 -All

# 3. Regenerar
cmake --preset developer

# 4. Build verboso
cmake --build build --verbose

# 5. Buscar error en DEPENDENCY_TROUBLESHOOTING_GUIDE.md

📖 Cómo Usar la Guía¶

Buscar por Síntoma¶

La guía está organizada por categorías de problemas:

🔴 VCPKG ISSUES
   ├─ vcpkg: command not found
   ├─ Download errors
   ├─ Package not found by CMake
   └─ Triplet mismatches

🎵 JUCE PROBLEMS
   ├─ JUCE_DIR not found
   ├─ Version mismatch
   ├─ Modules not found
   └─ GUI dependencies (Linux)

🔍 CMAKE FINDPACKAGE FAILURES
   ├─ Package installed but not found
   └─ Wrong version found

⚔️ VERSION CONFLICTS
   ├─ Multiple versions
   └─ ABI incompatibility

🌐 NETWORK ISSUES
   ├─ Corporate proxy
   └─ GitHub rate limit

🖥️ PLATFORM-SPECIFIC
   ├─ Windows
   ├─ Linux
   └─ macOS

Estructura de Cada Solución¶

### ❌ [Nombre del problema]

**Síntoma:**
[Error message exacto]

**Causa:**
[Por qué sucede]

**Solución:**
[Pasos concretos para resolver]

**Verificar:**
[Cómo confirmar que está resuelto]

🛠️ Workflow de Diagnóstico¶

Sigue este flujo para cualquier problema de dependencias:

┌─────────────────────────────────────────┐
│ 1. Identificar síntoma exacto           │
│    ↓                                     │
│ 2. Verificar instalación básica         │
│    └─ verify_installation.ps1           │
│    ↓                                     │
│ 3. Limpiar build                        │
│    └─ clean.ps1 -All                    │
│    ↓                                     │
│ 4. Reinstalar dependencia               │
│    └─ vcpkg remove <package>            │
│    └─ vcpkg install <package>           │
│    ↓                                     │
│ 5. Regenerar CMake cache                │
│    └─ cmake --preset developer          │
│    ↓                                     │
│ 6. Build verbose                        │
│    └─ cmake --build build --verbose     │
│    ↓                                     │
│ 7. Buscar en la guía                    │
│    ↓                                     │
│ 8. Pedir ayuda (con info completa)      │
└─────────────────────────────────────────┘

💡 Tips de Prevención¶

Para evitar problemas en primer lugar:

✅ Usar CMakePresets.json¶

{
  "configurePresets": [{
    "name": "developer",
    "cacheVariables": {
      "CMAKE_TOOLCHAIN_FILE": "external/vcpkg/scripts/buildsystems/vcpkg.cmake"
    }
  }]
}

✅ Usar vcpkg.json (Manifest Mode)¶

Versiones locked y reproducibles
Documentado en control de versiones
Menos propenso a desincronización

✅ Habilitar Binary Caching¶

# Mucho más rápido, menos errores de compilación
setx VCPKG_BINARY_SOURCES "clear;files,C:\vcpkg-cache,readwrite"

✅ CI/CD Validation¶

Detecta problemas en fresh environment
Verifica multiple platforms
Evita "works on my machine"

📋 Template para Reportar Nuevos Problemas¶

Si encuentras un problema no documentado, usa este template:

## ❌ [Título descriptivo]

**Síntoma:**

[Error message exacto]

**Contexto:**
- OS: Windows 11 / macOS 14 / Ubuntu 22.04
- vcpkg version: [vcpkg --version]
- CMake version: [cmake --version]
- Compiler: MSVC 2022 / GCC 13 / Clang 16

**Pasos para reproducir:**
1. [Paso 1]
2. [Paso 2]
3. [Error ocurre]

**Solución encontrada:**
[Qué funcionó]

**Por qué funcionó:**
[Explicación de causa raíz]

**Prevención futura:**
[Cómo evitar que vuelva a pasar]

Luego: Crea PR agregando este problema a DEPENDENCY_TROUBLESHOOTING_GUIDE.md

🆘 Obtener Ayuda¶

Si la guía no resuelve tu problema:

1. Buscar en Issues Externos¶

2. Crear Issue Interno¶

Incluir:

- Error message completo
- Output de verify_installation.ps1 -Detailed
- Platform y versiones (OS, CMake, compiler)
- Pasos exactos para reproducir
- Lo que ya intentaste

3. Team Chat¶

Canal: #build-issues
Tag: @build-team
Adjuntar logs completos

🔄 Mantenimiento¶

Actualizar la Guía¶

Cuando agregar nuevo problema: - Costó >30 minutos resolver - No está documentado en la guía - Podría afectar a otros developers

Cómo contribuir:

# 1. Editar guía
code DEPENDENCY_TROUBLESHOOTING_GUIDE.md

# 2. Agregar tu solución en sección apropiada
# Mantener formato consistente

# 3. Commit
git add DEPENDENCY_TROUBLESHOOTING_GUIDE.md
git commit -m "docs: Add troubleshooting for [problema]"

# 4. Push y PR
git push origin feature/add-troubleshooting

📊 Métricas de Éxito¶

Esta guía es exitosa cuando: - ✅ Time-to-resolution disminuye - ✅ Menos preguntas repetidas en chat - ✅ Onboarding más rápido para nuevos devs - ✅ Menos builds rotos en CI/CD

Meta: Resolver 80% de problemas en <15 minutos usando esta guía.

📚 Referencias¶

Estado actual: Guía completa con 40+ problemas documentados.

Próximos pasos: Expandir con problemas reales del equipo a medida que aparezcan.

Maintainer: Build Team

Última actualización: 2025-10-03