Skip to content

📦 DEPENDENCY MANAGEMENT - GUÍA MAESTRA

Sistema de Gestión de Dependencias para AudioLab

"Dependencies bien gestionadas = builds reproducibles y desarrollo sin fricción"

📖 TABLA DE CONTENIDOS

  1. Quick Start
  2. Visión General
  3. ¿Qué Script Usar?
  4. Estructura de Documentación
  5. Rutas de Aprendizaje
  6. Troubleshooting
  7. Recursos

🚀 QUICK START

Setup Inicial (5 minutos)

# 1. Navegar a dependency management
cd "2 - FOUNDATION/03_INFRA/03_03_dependency_management"

# 2. Instalar TODAS las dependencias
# Windows:
.\03_03_01_installation_scripts\install_all_dependencies.ps1

# Unix/macOS:
./03_03_01_installation_scripts/install_all_dependencies.sh

# 3. Verificar instalación
# Windows:
.\03_03_01_installation_scripts\verify_installation.ps1

# Unix/macOS:
./03_03_01_installation_scripts/verify_installation.sh

⏱️ Tiempo esperado: 15-30 minutos (primera vez)

✅ Si todo funciona: Verás "✓ All dependencies installed successfully"

❌ Si algo falla: Ver Troubleshooting

🎯 VISIÓN GENERAL

AudioLab gestiona dependencias usando un sistema híbrido que combina:

📦 Tipos de Dependencias

┌─────────────────────────────────────────────────────────┐
│                                                         │
│  🔧 VCPKG PACKAGES (7)                                  │
│  ├─ fftw3          - Fast Fourier Transform            │
│  ├─ eigen3         - Linear algebra                    │
│  ├─ libsndfile     - Audio file I/O                    │
│  ├─ catch2         - Testing framework                 │
│  ├─ benchmark      - Performance testing               │
│  ├─ fmt            - String formatting                 │
│  └─ spdlog         - Logging                           │
│                                                         │
│  🐍 PYTHON TOOLS (3)                                    │
│  ├─ black          - Code formatter                    │
│  ├─ pytest         - Testing                           │
│  └─ sphinx         - Documentation                     │
│                                                         │
│  📚 VENDORED (1)                                        │
│  └─ JUCE 7.0.9     - Audio plugin framework (71 MB)    │
│                                                         │
└─────────────────────────────────────────────────────────┘

🗂️ Sistema de Registry

Innovación clave: Tracking Git-friendly de dependencias instaladas

_installed_registry/
├── vcpkg/
│   ├── fftw3.yaml       ← versión, fecha, location
│   ├── eigen3.yaml
│   └── ...
├── python/
│   ├── black.yaml
│   └── ...
└── vendored/
    └── juce.yaml

Beneficios: - ✅ Team sync (todos mismo setup) - ✅ Audit trail (quién instaló qué y cuándo) - ✅ Version tracking (git diff muestra cambios)

🔀 ¿QUÉ SCRIPT USAR?

Flowchart de Decisión

┌────────────────────────────────────────┐
│  ¿Primera vez instalando?              │
└─────────┬──────────────────────────────┘
          │
       SÍ │
          ▼
   ┌──────────────────────────┐
   │ install_all_dependencies │ ← Instala TODO
   └──────────┬───────────────┘
              │
              ▼
   ┌──────────────────────────┐
   │ verify_installation      │ ← Verifica
   └──────────┬───────────────┘
              │
           ✅ DONE


┌────────────────────────────────────────┐
│  Ya instalado, solo verificar?         │
└─────────┬──────────────────────────────┘
          │
       SÍ │
          ▼
   ┌──────────────────────────┐
   │ verify_installation      │
   └──────────────────────────┘


┌────────────────────────────────────────┐
│  Solo necesitas core packages?         │
│  (más rápido, omite opcionales)        │
└─────────┬──────────────────────────────┘
          │
       SÍ │
          ▼
   ┌──────────────────────────┐
   │ install_core_deps        │ ← Más rápido
   └──────────────────────────┘


┌────────────────────────────────────────┐
│  ¿Ver qué está instalado?              │
└─────────┬──────────────────────────────┘
          │
       SÍ │
          ▼
   ┌──────────────────────────┐
   │ list_installed           │
   └──────────────────────────┘


┌────────────────────────────────────────┐
│  ¿Registry desactualizado?             │
│  (instalaste algo manualmente)         │
└─────────┬──────────────────────────────┘
          │
       SÍ │
          ▼
   ┌──────────────────────────┐
   │ update_registry          │
   └──────────────────────────┘


┌────────────────────────────────────────┐
│  ¿Actualizar dependencias?             │
└─────────┬──────────────────────────────┘
          │
       SÍ │
          ▼
   ┌──────────────────────────┐
   │ update_dependencies      │
   └──────────────────────────┘


┌────────────────────────────────────────┐
│  ¿Limpiar y empezar de cero?           │
└─────────┬──────────────────────────────┘
          │
       SÍ │
          ▼
   ┌──────────────────────────┐
   │ clean_dependencies       │
   └──────────┬───────────────┘
              │
              ▼
   ┌──────────────────────────┐
   │ install_all_dependencies │
   └──────────────────────────┘

Tabla de Scripts

Script Cuándo Usar Tiempo Plataformas
install_all_dependencies Primera instalación completa 15-30 min Win, Unix, macOS
install_core_deps Solo packages esenciales (más rápido) 10-15 min Windows
verify_installation Verificar que todo esté instalado 1-2 min Win, Unix, macOS
list_installed Ver qué packages tienes < 1 min Windows
update_registry Sync registry con instalaciones < 1 min Windows
update_dependencies Actualizar a nuevas versiones 10-20 min Windows
clean_dependencies Limpiar todo (nuclear option) < 1 min Windows
check_security Audit vulnerabilidades 2-5 min Windows

Ver: 03_03_01_installation_scripts/README.md

📚 ESTRUCTURA DE DOCUMENTACIÓN

03_03_dependency_management/
│
├── 📄 README.md (este archivo) ⭐
├── 📄 DEPENDENCY_CHEAT_SHEET.md ⭐ (comandos rápidos)
├── 📄 INSTALLATION_GUIDE.md (guía detallada)
│
├── 📁 03_03_00_package_manifests/
│   ├── vcpkg.json (manifest de vcpkg)
│   ├── vcpkg-configuration.json
│   ├── requirements.txt (Python packages)
│   └── _installed_registry/ ⭐ (tracking system)
│       ├── vcpkg/
│       ├── python/
│       └── vendored/
│
├── 📁 03_03_01_installation_scripts/ ⭐
│   ├── README.md (guía de scripts)
│   ├── install_all_dependencies.ps1/sh
│   ├── install_core_deps.ps1
│   ├── verify_installation.ps1/sh
│   ├── list_installed.ps1
│   └── update_registry.ps1
│
├── 📁 03_03_02_cmake_integration/
│   ├── README.md (cómo integrar con CMake)
│   ├── Dependencies.cmake
│   ├── INTEGRATION_EXAMPLE.cmake
│   └── FindModules/
│       ├── FindFFTW3.cmake
│       ├── FindIPP.cmake
│       └── FindJUCE.cmake
│
├── 📁 03_03_03_maintenance_scripts/
│   ├── README.md (guía de mantenimiento)
│   ├── update_dependencies.ps1
│   ├── clean_dependencies.ps1
│   └── check_security.ps1
│
├── 📁 03_03_04_license_management/
│   ├── README.md
│   ├── generate_attributions.ps1/sh
│   └── THIRD_PARTY_LICENSES.md (generado)
│
├── 📁 03_03_05_vendoring/
│   ├── VENDOR_POLICY.md (cuándo vendor vs external)
│   └── juce/ (JUCE framework vendored)
│
└── 📁 03_03_09_troubleshooting/
    ├── README.md
    └── DEPENDENCY_TROUBLESHOOTING_GUIDE.md ⭐ (876 líneas)

⭐ = Documentos esenciales

🛤️ RUTAS DE APRENDIZAJE

🌱 RUTA 1: USUARIO (Solo quiero que funcione)

Objetivo: Instalar dependencias y seguir desarrollando

Secuencia (30 min):

  1. Este README (5 min)
  2. 📖 Lee: Quick Start

  3. 📖 Lee: ¿Qué Script Usar?

  4. Ejecutar instalación (15-30 min) 

    ./install_all_dependencies.ps1
./verify_installation.ps1

  5. DEPENDENCY_CHEAT_SHEET.md (5 min)

  6. 📖 Bookmarkea para comandos rápidos

  7. Si algo falla:

  8. 📖 DEPENDENCY_TROUBLESHOOTING_GUIDE.md

✅ Al Completar: Puedes compilar AudioLab con todas las dependencias.

🌿 RUTA 2: DEVELOPER (Entender el sistema)

Objetivo: Comprender cómo funciona la gestión de dependencias

Secuencia (2-3 horas):

  1. INSTALLATION_GUIDE.md (30 min)
  2. 📖 Detalles de cada package

  3. 📖 Sistema de registry explicado

  4. 03_03_01_installation_scripts/README.md (30 min)

  5. 📖 Qué hace cada script internamente

  6. 📖 Cómo personalizar instalación

  7. 03_03_02_cmake_integration/README.md (1 hora)

  8. 📖 Cómo CMake encuentra packages
  9. 📖 Crear custom FindModules

  10. 📖 Integration examples

  11. VENDOR_POLICY.md (30 min)

  12. 📖 Cuándo vendor vs external
  13. 📖 Por qué JUCE está vendored

✅ Al Completar: Puedes agregar nuevas dependencias, troubleshoot issues.

🌲 RUTA 3: MAINTAINER (Gestionar dependencias)

Objetivo: Mantener dependencias actualizadas y seguras

Secuencia (4-5 horas):

  1. Ruta 2 completa (prerequisito)

  2. 03_03_03_maintenance_scripts/README.md (1 hora)

  3. 📖 Update workflow
  4. 📖 Security audits

  5. 📖 Dependency cleanup

  6. 03_03_04_license_management/README.md (1 hora)

  7. 📖 License compliance
  8. 📖 Attribution generation

  9. 📖 Legal requirements

  10. DEPENDENCY_TROUBLESHOOTING_GUIDE.md (2 horas)

  11. 📖 Todos los problemas comunes

  12. 📖 Advanced troubleshooting

  13. Práctica: Actualizar una dependencia completa

✅ Al Completar: Puedes gestionar todo el ciclo de vida de dependencias.

🚨 RUTA DE EMERGENCIA: "¡Las Dependencias Fallan!"

Si estás bloqueado:

  1. STOP - No reinstales ciegamente
  2. Identifica el problema: 
    ¿Qué comando falló?
¿Qué mensaje de error ves?
  3. Busca en troubleshooting:
  4. DEPENDENCY_TROUBLESHOOTING_GUIDE.md
  5. Busca tu error específico (Ctrl+F)
  6. Problemas comunes:
  7. ❌ "vcpkg: command not found" → Sección 1.1
  8. ❌ "CMake can't find package" → Sección 3.2
  9. ❌ "Download failed" → Sección 5.1
  10. Si no resuelves: Pide ayuda en #dependency-help Slack

🔍 TROUBLESHOOTING

Diagnóstico Rápido

Error Causa Probable Solución Rápida
vcpkg: command not found vcpkg no instalado ./install_all_dependencies.ps1
CMake can't find package Toolchain no configurado Ver CMake Integration
Download failed Network/proxy issue Ver Troubleshooting - Network
Version conflict Múltiples versiones ./clean_dependencies.ps1 + reinstall
Permission denied Scripts no ejecutables chmod +x *.sh (Unix)

Troubleshooting Completo

Ver: DEPENDENCY_TROUBLESHOOTING_GUIDE.md (876 líneas)

Incluye: - ✅ 50+ problemas comunes - ✅ Síntoma → Diagnóstico → Solución - ✅ Platform-specific issues - ✅ Advanced scenarios

📊 CASOS DE USO COMUNES

Caso 1: First-Time Setup (Team Member)

# 1. Clone repo
git clone https://github.com/audiolab/audio-lab.git
cd audio-lab

# 2. Install dependencies
cd "2 - FOUNDATION/03_INFRA/03_03_dependency_management"
./03_03_01_installation_scripts/install_all_dependencies.ps1

# 3. Verify
./03_03_01_installation_scripts/verify_installation.ps1

# 4. Build project
cd ../../..
./2\ -\ FOUNDATION/03_INFRA/03_02_build_infrastructure/03_02_03_build_scripts/build.sh

Caso 2: Agregar Nueva Dependencia

# 1. Instalar con vcpkg
vcpkg install new-library:x64-windows

# 2. Actualizar registry
./03_03_01_installation_scripts/update_registry.ps1

# 3. Agregar a CMake
# Editar: 03_03_02_cmake_integration/Dependencies.cmake
find_package(NewLibrary REQUIRED)

# 4. Commit registry
git add 03_03_00_package_manifests/_installed_registry/
git commit -m "Add new-library dependency"

Caso 3: Actualizar Dependencias

# 1. Ver versiones actuales
./03_03_01_installation_scripts/list_installed.ps1

# 2. Actualizar
./03_03_03_maintenance_scripts/update_dependencies.ps1

# 3. Verificar todo funciona
./03_03_01_installation_scripts/verify_installation.ps1

# 4. Actualizar registry
./03_03_01_installation_scripts/update_registry.ps1

# 5. Test build
cd ../../03_02_build_infrastructure/03_02_03_build_scripts
./build.sh

# 6. Commit si todo OK
git add ../03_03_00_package_manifests/_installed_registry/
git commit -m "Update dependencies to latest versions"

Caso 4: Clean Reinstall (Nuclear Option)

# 1. Limpiar TODO
./03_03_03_maintenance_scripts/clean_dependencies.ps1

# 2. Reinstalar desde cero
./03_03_01_installation_scripts/install_all_dependencies.ps1

# 3. Verificar
./03_03_01_installation_scripts/verify_installation.ps1

Caso 5: Generar License Attributions (Para Release)

# Antes de distribuir software
cd 03_03_04_license_management
./generate_attributions.ps1

# Genera: THIRD_PARTY_LICENSES.md
# Incluir en distribución

🔐 SECURITY & COMPLIANCE

Security Audits

# Audit vulnerabilities en dependencias
./03_03_03_maintenance_scripts/check_security.ps1

License Compliance

# Generar attributions
./03_03_04_license_management/generate_attributions.ps1

# Review licenses
cat 03_03_04_license_management/THIRD_PARTY_LICENSES.md

Ver: License Management README

🎓 FILOSOFÍA DE AUDIOLAB DEPENDENCIES

Principios

  1. Reproducibilidad - Mismo setup en todos los dev machines
  2. Transparency - Registry tracking de todo instalado
  3. Automation - Scripts para everything
  4. Compliance - License tracking automático
  5. Minimalism - Solo dependencias necesarias

Vendor vs External

Ver: VENDOR_POLICY.md

TL;DR: - Vendor si modificamos el código o es muy estable - External (vcpkg) para libraries estándar que se actualizan

📖 RECURSOS

AudioLab Interno

Externos

Herramientas

  • vcpkg - C++ package manager
  • pip - Python package installer
  • CMake - Build system

🤝 CONTRIBUCIONES

Agregar Nueva Dependencia

  1. Evaluar si vendor o external (ver VENDOR_POLICY.md)
  2. Si external: Agregar a vcpkg.json o requirements.txt
  3. Ejecutar install_all_dependencies.ps1
  4. Actualizar registry: update_registry.ps1
  5. Agregar a Dependencies.cmake
  6. Commit registry + manifests

Reportar Issues

  • Dependency que falla → Crear issue con logs
  • Mejora a scripts → PR bienvenido
  • Nueva dependencia → Proponer en #dependencies Slack

Maintainer: Dependency Management Team Slack: #dependency-help

📝 MÉTRICAS DE ÉXITO

Sabrás que dominas el sistema cuando:

  • Puedes instalar todas las dependencias desde cero
  • Entiendes el sistema de registry
  • Puedes agregar nuevas dependencias
  • Sabes troubleshoot errores comunes
  • Puedes actualizar dependencias safely
  • Generas license attributions para releases
  • Ayudas a otros con dependency issues

🎯 RESUMEN RÁPIDO

Para instalar (primera vez): 

./install_all_dependencies.ps1
./verify_installation.ps1

Para verificar qué tienes: 

./list_installed.ps1

Para actualizar: 

./update_dependencies.ps1

Para troubleshooting: - DEPENDENCY_CHEAT_SHEET.md - DEPENDENCY_TROUBLESHOOTING_GUIDE.md

Última actualización: 2025-10-09 Versión: 1.0.0

¡Bienvenido al sistema de gestión de dependencias de AudioLab! 📦

"Dependencies que funcionan = developers felices"