🚀 QUICK START - Tu Primer Build de AudioLab¶

Guía práctica paso a paso (30-60 minutos)¶

Objetivo: Compilar AudioLab exitosamente desde cero, entendiendo cada paso.

📋 PRERREQUISITOS¶

✅ Checklist de Software¶

Antes de empezar, necesitas:

Software	Versión Mínima	Verificar	Instalar
CMake	3.20+	`cmake --version`	cmake.org
Compilador	Ver abajo	`g++ --version`	Ver sección Compiladores
Git	2.20+	`git --version`	git-scm.com
Ninja (opcional)	1.10+	`ninja --version`	ninja-build.org

Compiladores por Plataforma¶

🪟 Windows¶

MSVC 2022 (recomendado)
Visual Studio 2022 Community (gratis)
O Build Tools: winget install Microsoft.VisualStudio.2022.BuildTools
Clang 15+ (alternativa)

🐧 Linux¶

GCC 11+ (recomendado)

sudo apt install build-essential cmake ninja-build  # Ubuntu/Debian
sudo dnf install gcc-c++ cmake ninja-build          # Fedora/RHEL

Clang 15+ (alternativa)

🍎 macOS¶

Xcode Command Line Tools (recomendado)
```
xcode-select --install
```
Incluye: Apple Clang, CMake vía Homebrew:
```
brew install cmake ninja
```

🎯 PASO 1: CLONAR EL REPOSITORIO¶

# Clonar AudioLab
git clone https://github.com/audiolab/audio-lab.git
cd audio-lab

# Verificar que estás en el directorio correcto
ls
# Deberías ver: CMakeLists.txt, 2 - FOUNDATION/, etc.

🔍 ¿Qué acabas de hacer? - Descargaste el código fuente de AudioLab - CMakeLists.txt en la raíz es el punto de entrada del build system

🎯 PASO 2: PRIMER BUILD (Método Rápido)¶

Opción A: Usando Scripts (Recomendado para principiantes)¶

Unix/macOS:¶

# Navegar a scripts de build
cd "2 - FOUNDATION/03_INFRA/03_02_build_infrastructure/03_02_03_build_scripts"

# Hacer ejecutable (solo primera vez)
chmod +x build.sh

# Ejecutar build
./build.sh

Windows (PowerShell):¶

# Navegar a scripts de build
cd "2 - FOUNDATION\03_INFRA\03_02_build_infrastructure\03_02_03_build_scripts"

# Ejecutar build
.\build.ps1

✅ Si funcionó: Verás ✅ Build exitoso y los binarios en build/Debug/bin/

❌ Si falló: Salta a Troubleshooting

Opción B: Usando CMake Directamente (Método manual)¶

# Desde la raíz del proyecto

# 1. Configurar (genera build files)
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug

# 2. Compilar
cmake --build build --config Debug -j 8

# -j 8 = usar 8 cores paralelos (ajusta a tu CPU)

🔍 ¿Qué acabas de hacer?

Paso 1 (Configure): - CMake lee CMakeLists.txt - Detecta compilador, libraries, opciones - Genera archivos de build nativos (Makefiles, .sln, build.ninja) - Crea directorio build/ con todo lo necesario

Paso 2 (Build): - Compila todo el código .cpp → .o (object files) - Linkea objects → binarios ejecutables - Copia outputs a build/bin/

🎯 PASO 3: VERIFICAR EL BUILD¶

# Listar binarios creados
ls build/Debug/bin/
# O en Windows: dir build\Debug\bin\

# Debería mostrar:
# - Ejecutables (.exe en Windows)
# - Librerías (.a, .so, .dylib)
# - Plugins (.vst3)

Ejecutar un Ejemplo¶

# Unix/macOS
./build/Debug/bin/audiolab_example

# Windows
.\build\Debug\bin\audiolab_example.exe

✅ Si ejecuta sin errores: ¡Felicitaciones! Build exitoso.

🎯 PASO 4: BUILD DE RELEASE (Optimizado)¶

El build de Debug es lento pero fácil de debuggear. Para producción/testing real:

Con Script:¶

./build.sh --config Release

Con CMake:¶

cmake -S . -B build-release -DCMAKE_BUILD_TYPE=Release
cmake --build build-release --config Release -j 8

🔍 Diferencias Debug vs Release:

Aspecto	Debug	Release
Optimización	-O0 (ninguna)	-O3 (máxima)
Símbolos debug	Sí (gdb/lldb)	No (stripped)
Velocidad	5-10x más lento	Full speed
Tamaño binario	Grande	Pequeño
Uso	Desarrollo	Producción

🎯 PASO 5: LIMPIAR Y REBUILD¶

A veces necesitas empezar desde cero:

Método 1: Script de Clean¶

cd "2 - FOUNDATION/03_INFRA/03_02_build_infrastructure/03_02_03_build_scripts"
./clean.sh

Método 2: Manual¶

# Borrar directorio de build completo
rm -rf build/         # Unix/macOS
rmdir /s build        # Windows

# Rebuild desde cero
./build.sh --clean

⚠️ Cuándo limpiar: - Cambios en CMakeLists.txt no se reflejan - Errores extraños de linkeo - Cambios de compilador o toolchain - Quieres asegurar build "limpio"

🎯 PASO 6: CONFIGURACIONES AVANZADAS¶

Habilitar Optimizaciones Extra¶

cmake -S . -B build-optimized \
      -DCMAKE_BUILD_TYPE=Release \
      -DENABLE_LTO=ON \           # Link-Time Optimization
      -DENABLE_SIMD=ON \          # Vectorización (SSE/AVX)
      -DENABLE_PCH=ON             # Precompiled Headers (build más rápido)

cmake --build build-optimized -j 8

Habilitar Sanitizers (Detectar bugs)¶

cmake -S . -B build-sanitized \
      -DCMAKE_BUILD_TYPE=Debug \
      -DENABLE_ASAN=ON \          # AddressSanitizer (memory bugs)
      -DENABLE_UBSAN=ON           # UndefinedBehaviorSanitizer

cmake --build build-sanitized -j 8

Build con Ninja (Más rápido)¶

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build

🎯 PASO 7: USAR CMAKE PRESETS¶

Los presets son configuraciones predefinidas:

# Listar presets disponibles
cmake --list-presets

# Usar preset específico
cmake --preset developer      # Para desarrollo
cmake --preset ci-linux       # Para CI/CD
cmake --preset release        # Release optimizado

# Build con preset
cmake --build --preset developer

Ver presets disponibles: 03_02_02_build_presets/CMakePresets.json

🛠️ TROUBLESHOOTING¶

Problema 1: "CMake command not found"¶

Causa: CMake no instalado o no en PATH

Solución:

# Verificar instalación
which cmake       # Unix/macOS
where cmake       # Windows

# Si no está: Instalar
# macOS
brew install cmake

# Ubuntu/Debian
sudo apt install cmake

# Windows
winget install Kitware.CMake

Problema 2: "Could not find compiler"¶

Causa: No hay compilador instalado

Solución por plataforma:

Windows:

# Instalar Visual Studio Build Tools
winget install Microsoft.VisualStudio.2022.BuildTools

# O especificar manualmente
cmake -G "Visual Studio 17 2022" -A x64 -S . -B build

Linux:

# Instalar GCC
sudo apt install build-essential

# O Clang
sudo apt install clang

macOS:

# Instalar Xcode Command Line Tools
xcode-select --install

Problema 3: "Could not find package JUCE"¶

Causa: Dependencia no encontrada

Solución:

AudioLab usa FetchContent para dependencias. Si falla:

# Opción 1: Dejar que CMake la descargue
cmake -S . -B build -DFETCH_DEPENDENCIES=ON

# Opción 2: Instalar con vcpkg
vcpkg install juce

# Especificar path
cmake -S . -B build -DCMAKE_PREFIX_PATH=/path/to/juce

Problema 4: "ninja: build stopped: subcommand failed"¶

Causa: Error de compilación (código con errores)

Solución:

# Rebuild con output verbose para ver error exacto
cmake --build build --verbose

# El output mostrará el comando de compilación que falló
# y el error específico del compilador

Lee el error del compilador: - error: 'foo' was not declared → Falta include - undefined reference to 'bar' → Problema de linkeo - fatal error: file.h: No such file → Path de include incorrecto

Ver guía completa: BUILD_TROUBLESHOOTING_PHILOSOPHY.md

Problema 5: "Permission denied" (Unix/macOS)¶

Causa: Script no tiene permisos de ejecución

Solución:

chmod +x build.sh
chmod +x clean.sh

Problema 6: Build muy lento¶

Soluciones:

Usar Ninja:
```
cmake -G Ninja -S . -B build
```

Más paralelismo:

./build.sh --parallel 16  # Ajusta a tus CPU cores

Precompiled Headers:
```
cmake -S . -B build -DENABLE_PCH=ON
```

ccache:

sudo apt install ccache    # Linux
brew install ccache        # macOS

cmake -S . -B build -DCMAKE_CXX_COMPILER_LAUNCHER=ccache

📊 TIEMPOS DE BUILD ESPERADOS¶

Primer build (clean): - Debug: 2-5 minutos (depende de CPU) - Release: 3-8 minutos (optimizaciones toman tiempo)

Rebuild incremental (cambio de 1 archivo): - Debug: 5-30 segundos - Release: 10-60 segundos

Si tu build toma >15 minutos: Algo está mal. Ver optimizaciones arriba.

🎓 PRÓXIMOS PASOS¶

Ahora que compilaste exitosamente:

Explorar el código:

# Ver estructura del proyecto
tree -L 2

Modificar algo:
Edita un archivo .cpp
Rebuild (debería ser rápido)
Ejecuta para ver cambios
Aprender CMake:
Lee: CMAKE_CHEAT_SHEET.md
Lee: BUILD_SYSTEMS_PHILOSOPHY.md
Configuraciones avanzadas:
Cross-compilation: TOOLCHAIN_PHILOSOPHY.md
Optimizaciones: Módulos en 03_02_00_build_system/

🎯 CHEAT SHEET RÁPIDO¶

# Build rápido
./build.sh

# Release optimizado
./build.sh --config Release

# Limpiar y rebuild
./build.sh --clean

# Ver qué hace CMake
cmake --build build --verbose

# Build solo un target
cmake --build build --target audiolab_plugin

# Instalar (copia a /usr/local)
cmake --build build --target install

# Ejecutar tests
cmake --build build --target test
# O: ctest --test-dir build

✅ CHECKLIST DE ÉXITO¶

Has completado el Quick Start si puedes:

¡Felicitaciones! Ahora eres capaz de compilar AudioLab. 🎉

📚 RECURSOS¶

Si algo falla: BUILD_TROUBLESHOOTING_PHILOSOPHY.md
Comandos CMake: CMAKE_CHEAT_SHEET.md
Entender el proceso: BUILD_SYSTEMS_PHILOSOPHY.md
Ayuda: #build-help en Slack

Última actualización: 2025-10-09