🔧 Dependency Troubleshooting Guide¶

Base de conocimiento para resolver problemas comunes con dependencias en AudioLab.

📋 ÍNDICE RÁPIDO¶

vcpkg Issues
JUCE Problems
CMake FindPackage Failures
Version Conflicts
Network Issues
Platform-Specific Problems

🔴 VCPKG ISSUES¶

❌ vcpkg: command not found¶

Síntoma:

'vcpkg' is not recognized as an internal or external command

Causa: vcpkg no está instalado o no está en PATH.

Solución:

# Instalar vcpkg
.\install_all_dependencies.ps1

# O manualmente:
cd external
git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat  # Windows
./bootstrap-vcpkg.sh   # Unix

Verificar:

.\external\vcpkg\vcpkg.exe --version

❌ vcpkg install fails: download error¶

Síntoma:

Failed to download package from https://...
Connection timeout / Network error

Causas Comunes:

Firewall/Proxy bloqueando
Servidor temporalmente inaccesible
Certificado SSL inválido

Soluciones:

Opción 1: Configurar proxy

# Windows
set HTTP_PROXY=http://proxy.company.com:8080
set HTTPS_PROXY=http://proxy.company.com:8080

# Unix
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

Opción 2: Descargar manualmente

# Limpiar y reintentar
.\external\vcpkg\vcpkg.exe remove fmt
.\external\vcpkg\vcpkg.exe install fmt --clean-after-build

Opción 3: Usar mirror/cache

# Configurar binary cache
.\external\vcpkg\vcpkg.exe install fmt --binarysource=clear

❌ Package already installed but CMake doesn't find it¶

Síntoma:

find_package(fmt REQUIRED)
# CMake Error: Could not find package fmt

Pero:

vcpkg list | grep fmt
# fmt:x64-windows    10.1.1

Causa: CMake no sabe dónde buscar los packages de vcpkg.

Solución:

Método 1: Toolchain file (Recomendado)

cmake -S . -B build \
  -DCMAKE_TOOLCHAIN_FILE=external/vcpkg/scripts/buildsystems/vcpkg.cmake

Método 2: En CMakePresets.json

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

Método 3: Variable de entorno

# Windows
set VCPKG_ROOT=C:\AudioDev\audio-lab\external\vcpkg

# Unix
export VCPKG_ROOT=/path/to/audio-lab/external/vcpkg

❌ Different triplet installed than expected¶

Síntoma:

Package fmt:x64-windows-static installed
But CMake looking for fmt:x64-windows

Causa: vcpkg instaló con triplet diferente.

Solución:

# Ver qué triplets están instalados
vcpkg list

# Desinstalar triplet incorrecto
vcpkg remove fmt:x64-windows-static

# Instalar triplet correcto
vcpkg install fmt:x64-windows

# O especificar triplet en CMake
cmake -DVCPKG_TARGET_TRIPLET=x64-windows ..

Triplets comunes: - x64-windows - Dynamic linking - x64-windows-static - Static linking - x64-linux - Linux - x64-osx - macOS

❌ vcpkg ports outdated¶

Síntoma:

vcpkg installs old version of library
Newer version needed for features

Solución:

# Actualizar vcpkg
cd external/vcpkg
git pull
./bootstrap-vcpkg.bat  # Rebuild

# Actualizar packages
vcpkg upgrade --no-dry-run

🎵 JUCE PROBLEMS¶

❌ JUCE_DIR not found¶

Síntoma:

CMake Error: Could not find JUCE
Set JUCE_DIR to directory containing JUCEConfig.cmake

Causa: CMake no sabe dónde está JUCE.

Solución:

Método 1: Variable CMake

cmake -DJUCE_DIR=external/juce ..

Método 2: Variable de entorno

# Windows
set JUCE_DIR=C:\AudioDev\audio-lab\external\juce

# Unix
export JUCE_DIR=/path/to/audio-lab/external/juce

Método 3: En CMakeLists.txt

list(APPEND CMAKE_PREFIX_PATH "${PROJECT_SOURCE_DIR}/external/juce")
find_package(JUCE REQUIRED)

Verificar instalación:

# Debe existir:
ls external/juce/CMakeLists.txt
ls external/juce/extras/Build/CMake/JUCEConfig.cmake

❌ JUCE version mismatch¶

Síntoma:

JUCE version 7.0.5 found
But AudioLab requires JUCE 7.0.9+

Solución:

# Actualizar JUCE
cd external/juce
git fetch --tags
git checkout 7.0.9

# O reinstalar
rm -rf external/juce
.\install_all_dependencies.ps1 -Force -SkipVcpkg

❌ JUCE modules not found¶

Síntoma:

CMake Error: JUCE module juce_audio_processors not found

Causa: Instalación incompleta de JUCE.

Solución:

# Verificar módulos
ls external/juce/modules/

# Debe contener:
# juce_core/
# juce_audio_basics/
# juce_audio_processors/
# etc.

# Si faltan, reinstalar:
rm -rf external/juce
git clone --depth 1 --branch 7.0.9 \
  https://github.com/juce-framework/JUCE.git external/juce

❌ JUCE GUI dependencies missing (Linux)¶

Síntoma:

error: X11/Xlib.h: No such file or directory
error: ALSA headers not found

Causa: Faltan dependencias del sistema para JUCE en Linux.

Solución:

Ubuntu/Debian:

sudo apt update
sudo apt install -y \
  libasound2-dev \
  libx11-dev \
  libxext-dev \
  libxrandr-dev \
  libxinerama-dev \
  libxcursor-dev \
  libfreetype6-dev \
  libwebkit2gtk-4.0-dev \
  libglu1-mesa-dev

Fedora:

sudo dnf install -y \
  alsa-lib-devel \
  libX11-devel \
  libXext-devel \
  libXrandr-devel \
  libXinerama-devel \
  libXcursor-devel \
  freetype-devel \
  webkit2gtk3-devel \
  mesa-libGLU-devel

🔍 CMAKE FINDPACKAGE FAILURES¶

❌ Package installed but find_package fails¶

Síntoma:

find_package(spdlog REQUIRED)
# CMake Error: Could not find package spdlog

Diagnóstico paso a paso:

1. Verificar que el package existe:

vcpkg list | grep spdlog
# Debe mostrar: spdlog:x64-windows   1.x.x

2. Verificar CMAKE_PREFIX_PATH:

# En CMakeLists.txt agregar temporalmente:
message(STATUS "CMAKE_PREFIX_PATH: ${CMAKE_PREFIX_PATH}")

3. Verificar *Config.cmake existe:

# Windows
dir external\vcpkg\installed\x64-windows\share\spdlog\spdlogConfig.cmake

# Unix
ls external/vcpkg/installed/x64-linux/share/spdlog/spdlogConfig.cmake

Soluciones:

Si Config.cmake falta:

# Reinstalar package
vcpkg remove spdlog
vcpkg install spdlog

Si CMAKE_PREFIX_PATH incorrecto:

# En CMakeLists.txt
list(APPEND CMAKE_PREFIX_PATH
  "${CMAKE_SOURCE_DIR}/external/vcpkg/installed/${VCPKG_TARGET_TRIPLET}")

Si toolchain file no usado:

cmake -DCMAKE_TOOLCHAIN_FILE=external/vcpkg/scripts/buildsystems/vcpkg.cmake ..

❌ Wrong package version found¶

Síntoma:

Found fmt version 8.0.0
But required version is 10.0.0+

Causa: Sistema tiene versión antigua instalada globalmente.

Solución:

# En find_package, especificar versión mínima:
find_package(fmt 10.0 REQUIRED)

# O forzar usar vcpkg version:
set(CMAKE_FIND_PACKAGE_PREFER_CONFIG TRUE)
find_package(fmt REQUIRED)

Diagnóstico:

# Ver dónde encontró el package
find_package(fmt REQUIRED)
message(STATUS "fmt found at: ${fmt_DIR}")

⚔️ VERSION CONFLICTS¶

❌ Multiple versions of same library¶

Síntoma:

Linking against fmt 9.0 and fmt 10.0
Undefined symbols / crashes

Causa: Diferentes dependencies usan diferentes versiones.

Solución:

1. Identificar conflicto:

# Ver todas las versiones instaladas
vcpkg list | grep fmt

# Ver dependencias transitivas
vcpkg depend-info fmt

2. Forzar versión específica:

En vcpkg.json:

{
  "dependencies": [
    {
      "name": "fmt",
      "version>=": "10.0.0"
    }
  ],
  "overrides": [
    {
      "name": "fmt",
      "version": "10.1.1"
    }
  ]
}

3. Rebuild todo:

vcpkg remove --recurse fmt
vcpkg install

❌ ABI incompatibility¶

Síntoma:

Crash al ejecutar
Símbolos undefined al linkear
Comportamiento extraño

Causa: Mixing Debug/Release o diferentes CRT.

Diagnóstico:

Windows:

# Ver qué CRT usa una DLL
dumpbin /DEPENDENTS external\vcpkg\installed\x64-windows\bin\fmt.dll
# Buscar: MSVCR140D.dll (Debug) vs MSVCR140.dll (Release)

Solución:

# Asegurar consistencia
set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>DLL")

# O usar vcpkg manifest con features:
# vcpkg.json:
{
  "name": "audiolab",
  "dependencies": [
    {
      "name": "fmt",
      "features": ["shared"]  # O "static"
    }
  ]
}

Rebuild todo con mismo build type:

# Limpiar
rm -rf build external/vcpkg/buildtrees

# Rebuild consistente
cmake --preset developer
cmake --build build --config Debug

🌐 NETWORK ISSUES¶

❌ Corporate proxy blocks downloads¶

Síntoma:

Failed to download from github.com
Connection refused / timeout
SSL certificate verify failed

Solución:

1. Configurar proxy:

# Windows
set HTTP_PROXY=http://user:pass@proxy:8080
set HTTPS_PROXY=http://user:pass@proxy:8080

# Unix
export HTTP_PROXY=http://user:pass@proxy:8080
export HTTPS_PROXY=http://user:pass@proxy:8080

# Git también necesita configuración
git config --global http.proxy http://proxy:8080
git config --global https.proxy http://proxy:8080

2. Si SSL falla (NO RECOMENDADO para producción):

# Solo para debugging
git config --global http.sslVerify false

# Mejor: Instalar certificado corporativo
# Windows: Importar .crt a Trusted Root
# Unix: Agregar a /etc/ssl/certs/

3. Usar mirror interno:

# Configurar vcpkg binary cache
vcpkg install --binarysource=clear;files,\\share\vcpkg-cache,write

❌ GitHub rate limit exceeded¶

Síntoma:

API rate limit exceeded for xxx.xxx.xxx.xxx
Remaining: 0/60

Causa: vcpkg hace muchas requests a GitHub API.

Solución:

1. Usar GitHub token:

# Crear token: https://github.com/settings/tokens
# Permisos: public_repo

# Configurar
set GITHUB_TOKEN=ghp_xxxxxxxxxxxxx

# O en vcpkg:
vcpkg install --x-github-token=ghp_xxxxxxxxxxxxx

2. Esperar (límite se resetea cada hora)

3. Usar binary cache (evita recompilación):

vcpkg install --binarysource=clear;nuget,https://nuget.pkg.github.com/user/index.json

🖥️ PLATFORM-SPECIFIC PROBLEMS¶

🪟 Windows¶

❌ Long path issues¶

Síntoma:

error: filename or extension is too long
Cannot create file: path exceeds 260 characters

Solución:

Método 1: Habilitar long paths

# PowerShell como Admin
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
  -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

# Reiniciar

Método 2: Usar path más corto

# En lugar de:
C:\Users\MyName\Documents\Projects\AudioLab\...

# Usar:
C:\AudioLab\...

Método 3: Subst drive

subst A: C:\AudioDev\audio-lab
cd A:\

❌ Visual Studio version mismatch¶

Síntoma:

error MSB8036: The Windows SDK version X.X was not found
MSVC v142 not found

Solución:

1. Instalar SDK correcto: - Visual Studio Installer → Modify - Individual components → Windows SDK 10.0.xxxxx

2. Especificar versión en CMake:

cmake -G "Visual Studio 17 2022" -A x64 \
  -DCMAKE_SYSTEM_VERSION=10.0.19041.0 \
  ..

🐧 Linux¶

❌ Missing system libraries¶

Síntoma:

/usr/bin/ld: cannot find -lasound
/usr/bin/ld: cannot find -lX11

Solución:

Ubuntu/Debian:

sudo apt install -y \
  build-essential \
  cmake \
  pkg-config \
  libasound2-dev \
  libx11-dev \
  libxext-dev \
  libfreetype6-dev

Verificar instalación:

pkg-config --modversion alsa
pkg-config --modversion x11

❌ Compiler too old¶

Síntoma:

error: 'std::filesystem' has not been declared
requires at least GCC 9+

Solución:

Ubuntu 20.04+:

sudo apt install gcc-11 g++-11
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-11 100
sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-11 100

Verificar:

gcc --version
g++ --version

🍎 macOS¶

❌ Xcode Command Line Tools missing¶

Síntoma:

xcrun: error: invalid active developer path
xcode-select: error: tool 'xcodebuild' requires Xcode

Solución:

xcode-select --install

Verificar:

xcode-select -p
# Debe mostrar: /Library/Developer/CommandLineTools

❌ Code signing issues¶

Síntoma:

"AudioLab.component" cannot be opened because the developer cannot be verified

Solución (desarrollo):

# Deshabilitar Gatekeeper para el archivo
sudo xattr -rd com.apple.quarantine AudioLab.component

# O firmar con identidad de desarrollo
codesign -s "Developer ID Application" AudioLab.component

🔧 DIAGNOSTIC WORKFLOW¶

Para cualquier problema de dependencias:

1. Identificar síntoma exacto
   ↓
2. Verificar instalación básica
   └─ .\verify_installation.ps1 --detailed
   ↓
3. Limpiar build
   └─ .\clean.ps1 -All
   ↓
4. Reinstalar dependencia problemática
   └─ vcpkg remove <package>
   └─ vcpkg install <package>
   ↓
5. Regenerar CMake cache
   └─ cmake --preset developer
   ↓
6. Build verbose para ver errores completos
   └─ cmake --build build --verbose
   ↓
7. Buscar en este documento
   ↓
8. Pedir ayuda (con información completa):
   - Error message completo
   - Output de verify_installation
   - Platform y versiones
   - Pasos para reproducir

💡 PREVENTION TIPS¶

Best Practices para evitar problemas:

✅ Usar CMakePresets.json - Configuración consistente - Toolchain file automático - Versionado en Git

✅ Usar vcpkg manifest mode (vcpkg.json) - Versiones locked - Reproducible - Documentado

✅ Binary caching - Evita recompilaciones - Más rápido - Menos propenso a errores

✅ CI/CD validación - Detecta problemas temprano - Fresh environment cada vez - Multiple platforms

✅ Documentar custom configurations - Proxy settings - Paths non-standard - Workarounds temporales

📚 RECURSOS ADICIONALES¶

🆘 GETTING HELP¶

Si este documento no resuelve tu problema:

Buscar en GitHub Issues:
AudioLab issues
vcpkg issues
JUCE forum

Crear issue con:

- Error message completo
- Output de verify_installation.ps1 -Detailed
- Platform: Windows/Linux/macOS
- CMake version, compiler version
- Pasos exactos para reproducir

Team chat:
Canal #build-issues
Incluir logs completos
Tag @build-team

Última actualización: 2025-10-03 Mantenido por: Build Team Contribuir: Agrega soluciones cuando encuentres nuevos problemas