Skip to content

🏭 BUILD INFRASTRUCTURE - GUÍA MAESTRA

Sistema de Construcción para AudioLab

"Un build system transforma potencial (código fuente) en realidad (software ejecutable)"

📖 TABLA DE CONTENIDOS

  1. Visión General
  2. Quick Start
  3. Rutas de Aprendizaje
  4. Estructura de Documentación
  5. Scripts de Build
  6. Troubleshooting
  7. Recursos

🎯 VISIÓN GENERAL

Este directorio contiene la infraestructura completa para construir proyectos AudioLab. No es solo "cómo compilar"—es un sistema completo de transformación de código a software distribuible.

🎓 ¿Qué Aprenderás Aquí?

📚 NIVEL 1: Fundamentos
   └─ ¿Qué es un build? ¿Por qué es complejo?

📚 NIVEL 2: Herramientas
   └─ CMake, compiladores, linkers, toolchains

📚 NIVEL 3: Optimización
   └─ LTO, PGO, SIMD, compilation speeds

📚 NIVEL 4: Cross-Platform
   └─ Windows, macOS, Linux builds unificados

📚 NIVEL 5: Troubleshooting
   └─ Diagnosticar y resolver errores de build

🏗️ Pipeline de Build

┌─────────────────────────────────────────────────────────┐
│                                                         │
│  📝 Código C++         →  🔄 Transformación            │
│     (.cpp, .h)              (build system)             │
│                                 ↓                       │
│                          1️⃣ Preprocessing               │
│                          2️⃣ Compilation                 │
│                          3️⃣ Linking                     │
│                          4️⃣ Post-processing             │
│                                 ↓                       │
│  🎯 Software           ←  📦 Empaquetado               │
│     (.exe, .vst3)          (deployment)                │
│                                                         │
└─────────────────────────────────────────────────────────┘

🚀 QUICK START

Para Usuarios (Solo quiero compilar)

# 1. Clonar el repositorio
git clone https://github.com/audiolab/audio-lab.git
cd audio-lab

# 2. Build rápido
./2 - FOUNDATION/03_INFRA/03_02_build_infrastructure/03_02_03_build_scripts/build.sh
# Windows: .\build.ps1

# 3. Ejecutar
./build/Debug/bin/your-app

¿Problemas? → Ver QUICK_START.md

Para Desarrolladores (Quiero entender)

# 1. Leer filosofía (30 min)
BUILD_SYSTEMS_PHILOSOPHY.md

# 2. Tutorial práctico (1 hora)
QUICK_START.md

# 3. Cheat sheet de comandos
CMAKE_CHEAT_SHEET.md

# 4. Configurar tu entorno
03_02_01_toolchains/TOOLCHAIN_PHILOSOPHY.md

🛤️ RUTAS DE APRENDIZAJE

🌱 RUTA 1: PRINCIPIANTE (Nunca usé CMake)

Objetivo: Poder compilar proyectos existentes

Secuencia (4-6 horas):

  1. QUICK_START.md (1 hora)
  2. 🎯 Tu primer build exitoso
  3. Entender qué hace cada paso

  4. Resolver problemas básicos

  5. BUILD_SYSTEMS_PHILOSOPHY.md - Capítulos 1-2 (1 hora)

  6. 📖 Lee: La naturaleza de la transformación
  7. 📖 Lee: ¿Por qué CMake?

  8. 🎯 Objetivo: Entender QUÉ es un build

  9. CMAKE_CHEAT_SHEET.md (30 min)

  10. 📖 Bookmarkea este archivo

  11. 🎯 Objetivo: Comandos esenciales a mano

  12. Scripts de Build (30 min)

  13. 📖 Lee: 03_02_03_build_scripts/README.md

  14. 🎯 Objetivo: Usar scripts sin pensar en CMake

  15. Troubleshooting Básico (1 hora)

  16. 📖 Lee: 03_02_05_troubleshooting/build_issues.md
  17. 🎯 Objetivo: Resolver errores comunes

✅ Al Completar: Puedes compilar AudioLab en Debug/Release, resolver errores básicos.

🌿 RUTA 2: INTERMEDIO (Sé usar CMake básico)

Objetivo: Configurar builds complejos, cross-platform

Secuencia (8-10 horas):

  1. BUILD_SYSTEMS_PHILOSOPHY.md - Completo (3 horas)
  2. 📖 Todos los capítulos

  3. 🎯 Objetivo: Modelo mental completo del pipeline

  4. CMAKE_ARCHITECTURE_DEEP_DIVE.md (2 horas)

  5. 📖 Internals de CMake

  6. 🎯 Objetivo: Entender cómo funciona CMake

  7. TOOLCHAIN_PHILOSOPHY.md (2 horas)

  8. 📖 Cross-compilation
  9. 📖 Toolchains específicos

  10. 🎯 Objetivo: Compilar para otras plataformas

  11. Módulos CMake (1 hora)

  12. 📖 Explora: 03_02_00_build_system/*.cmake

  13. 🎯 Objetivo: Reutilizar módulos en tus proyectos

  14. DEPENDENCY_PHILOSOPHY.md (2 horas)

  15. 📖 FetchContent, find_package, vcpkg
  16. 🎯 Objetivo: Gestionar dependencias

✅ Al Completar: Puedes configurar builds complejos, cross-compile, gestionar dependencias.

🌲 RUTA 3: AVANZADO (Quiero optimizar builds)

Objetivo: Builds rápidos, optimizados, CI/CD

Secuencia (10-15 horas):

  1. Optimization Modules (3 horas)
  2. 📖 advanced_optimization.cmake - LTO, PGO
  3. 📖 simd_detection.cmake - Vectorization
  4. 📖 pch_setup.cmake - Precompiled headers

  5. 🎯 Objetivo: Builds 2-5x más rápidos

  6. Compiler Deep Dive (2 horas)

  7. 📖 compiler_flags.cmake
  8. 📖 warning_flags.cmake

  9. 🎯 Objetivo: Fine-tuning de compilación

  10. Sanitizers & Debugging (2 horas)

  11. 📖 sanitizers.cmake

  12. 🎯 Objetivo: Detectar bugs en runtime

  13. Advanced Troubleshooting (3 horas)

  14. 📖 BUILD_TROUBLESHOOTING_PHILOSOPHY.md - Completo
  15. 📖 linker_errors.md

  16. 🎯 Objetivo: Diagnosticar problemas complejos

  17. CI/CD Integration (práctica)

  18. 🎯 Objetivo: Automatizar builds en GitHub Actions

✅ Al Completar: Puedes diseñar build systems complejos, optimizar, troubleshoot anything.

🚨 RUTA DE EMERGENCIA: "¡El Build Falló!"

Si estás bloqueado:

  1. STOP - No intentes compilar repetidamente sin entender
  2. Identifica la fase donde falla: 
    ❌ CMake configuration error   → Configuration time
❌ Compiler error (.cpp)        → Compilation time
❌ Undefined reference          → Link time
❌ Code signing failed          → Post-build
  3. Lee el playbook correspondiente:
  4. Configuration → build_issues.md - Sección 1
  5. Compilation → BUILD_TROUBLESHOOTING_PHILOSOPHY.md - PHASE 3
  6. Linking → linker_errors.md
  7. Si no resuelves: Pide ayuda en #build-help Slack

📚 ESTRUCTURA DE DOCUMENTACIÓN

03_02_build_infrastructure/
│
├── 📄 README.md (este archivo) ⭐
├── 📄 QUICK_START.md ⭐ (tutorial paso a paso)
├── 📄 CMAKE_CHEAT_SHEET.md ⭐ (quick reference)
├── 📄 BUILD_SYSTEMS_PHILOSOPHY.md (fundamentos conceptuales)
│
├── 📁 03_02_00_build_system/
│   ├── CMAKE_ARCHITECTURE_DEEP_DIVE.md (internals de CMake)
│   ├── advanced_optimization.cmake (LTO, PGO)
│   ├── compiler_flags.cmake (flags por compilador)
│   ├── lto_config.cmake (Link Time Optimization)
│   ├── pch_setup.cmake (Precompiled Headers)
│   ├── sanitizers.cmake (ASan, UBSan, TSan)
│   ├── simd_detection.cmake (SSE, AVX)
│   └── warning_flags.cmake (warning levels)
│
├── 📁 03_02_00_cmake_foundation/
│   ├── AudioLabConfig.cmake (project config)
│   ├── AudioLabTargets.cmake (export targets)
│   └── AudioLabUtilities.cmake (helper functions)
│
├── 📁 03_02_01_toolchains/
│   ├── TOOLCHAIN_PHILOSOPHY.md (cross-compilation guide)
│   ├── windows_msvc.cmake (Windows MSVC)
│   ├── linux_gcc.cmake (Linux GCC)
│   ├── linux_clang.cmake (Linux Clang)
│   ├── macos_universal.cmake (macOS Universal)
│   └── cross_mingw.cmake (Linux → Windows)
│
├── 📁 03_02_02_build_presets/
│   ├── README.md (cómo usar presets)
│   └── CMakePresets.json (presets examples) ⭐
│
├── 📁 03_02_02_dependencies/
│   ├── DEPENDENCY_PHILOSOPHY.md (gestión de dependencias)
│   ├── FetchContent.cmake (fetch external libs)
│   └── FindModules/
│       ├── FindIPP.cmake (Intel Performance Primitives)
│       └── FindJUCE.cmake (JUCE framework)
│
├── 📁 03_02_03_build_scripts/
│   ├── README.md (guía de scripts)
│   ├── build.sh (Unix/macOS build script) ✅
│   ├── build.ps1 (Windows build script) ✅
│   ├── clean.sh (cleanup script)
│   └── clean.ps1 (Windows cleanup)
│
└── 📁 03_02_05_troubleshooting/
    ├── BUILD_TROUBLESHOOTING_PHILOSOPHY.md (troubleshooting completo)
    ├── build_issues.md (problemas comunes)
    └── linker_errors.md (errores de linkeo)

⭐ = Documentos esenciales, leer primero

🔨 SCRIPTS DE BUILD

Scripts Principales

# Unix/macOS
./03_02_03_build_scripts/build.sh [opciones]

# Windows
.\03_02_03_build_scripts\build.ps1 [opciones]

Opciones Comunes

# Configuraciones
--config Debug              # Debug build (default)
--config Release            # Release build (optimizado)
--config RelWithDebInfo     # Release con debug info

# Operaciones
--clean                     # Limpiar antes de compilar
--verbose                   # Output detallado

# Performance
--parallel 8                # 8 jobs paralelos (default: auto)

# Presets
--preset developer          # Usar CMake preset específico
--preset ci-linux           # Para CI/CD

Ejemplos Prácticos

# Build rápido de debug
./build.sh

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

# Build paralelo máximo
./build.sh --parallel 16

# Usar preset específico
./build.sh --preset developer

# Build verboso para debugging
./build.sh --verbose

Scripts de Limpieza

# Limpiar build directory
./03_02_03_build_scripts/clean.sh

# Limpiar TODO (builds + caches)
./03_02_03_build_scripts/clean.sh --all

Ver: 03_02_03_build_scripts/README.md

🔧 CONFIGURACIÓN RÁPIDA

Primer Build (5 minutos)

# 1. Verificar requisitos
cmake --version          # Mínimo 3.20
g++ --version            # O clang++, msvc

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

# 3. Build
./2\ -\ FOUNDATION/03_INFRA/03_02_build_infrastructure/03_02_03_build_scripts/build.sh

# 4. ¡Éxito!
# Binarios en: build/Debug/bin/

Configuración Avanzada

# Usar toolchain específico
cmake -S . -B build \
      -DCMAKE_TOOLCHAIN_FILE=03_02_01_toolchains/linux_clang.cmake

# Habilitar optimizaciones
cmake -S . -B build \
      -DCMAKE_BUILD_TYPE=Release \
      -DENABLE_LTO=ON \
      -DENABLE_SIMD=ON

# Usar preset
cmake --preset developer
cmake --build --preset developer

Ver: CMAKE_CHEAT_SHEET.md

🚨 TROUBLESHOOTING

Diagnóstico Rápido

¿Dónde falló el build?

┌─────────────────────────────────────┐
│ "CMake Error: Could not find..."   │ → Configuration Error
│                                     │   Ver: build_issues.md #1
├─────────────────────────────────────┤
│ "error: 'vector' is not defined"   │ → Compilation Error
│                                     │   Ver: BUILD_TROUBLESHOOTING #3
├─────────────────────────────────────┤
│ "undefined reference to `foo'"     │ → Linker Error
│                                     │   Ver: linker_errors.md
├─────────────────────────────────────┤
│ "Code signing failed"               │ → Post-build Error
│                                     │   Ver: BUILD_TROUBLESHOOTING #5
└─────────────────────────────────────┘

Errores Comunes (Top 5)

  1. CMake no encuentra dependencia 

    # Solución: Especificar CMAKE_PREFIX_PATH
cmake -DCMAKE_PREFIX_PATH=/path/to/libs

  2. Compilador no encontrado 

    # Solución: Instalar o especificar
cmake -DCMAKE_CXX_COMPILER=/usr/bin/g++

  3. Undefined reference (linker error) 

    # Causa: Falta linkear library
# Solución: Agregar target_link_libraries() en CMakeLists.txt

  4. Permission denied (Unix) 

    chmod +x build.sh

  5. Out of memory durante link 

    # Solución: Reducir parallel jobs
./build.sh --parallel 2

Ver documentación completa: BUILD_TROUBLESHOOTING_PHILOSOPHY.md

📊 CASOS DE USO

Caso 1: Developer Local Build

# Debug build para desarrollo diario
./build.sh --config Debug

# Con sanitizers para detectar bugs
cmake -S . -B build-debug \
      -DCMAKE_BUILD_TYPE=Debug \
      -DENABLE_ASAN=ON \
      -DENABLE_UBSAN=ON

Caso 2: Release Build para Distribución

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

# Con todas las optimizaciones
cmake -S . -B build-release \
      -DCMAKE_BUILD_TYPE=Release \
      -DENABLE_LTO=ON \
      -DENABLE_SIMD=ON \
      -DENABLE_STRIP=ON

Caso 3: Cross-Compilation

# Linux → Windows (MinGW)
cmake -S . -B build-windows \
      -DCMAKE_TOOLCHAIN_FILE=03_02_01_toolchains/cross_mingw.cmake

# macOS Universal (Intel + Apple Silicon)
cmake -S . -B build-universal \
      -DCMAKE_TOOLCHAIN_FILE=03_02_01_toolchains/macos_universal.cmake

Caso 4: CI/CD Build

# Build no-interactivo para CI
./build.sh --preset ci-linux --parallel 4

# O directamente CMake
cmake --preset ci-linux
cmake --build --preset ci-linux --target all test

📖 RECURSOS ADICIONALES

AudioLab Interno

Externos Recomendados

Herramientas

  • CMake - Build system generator
  • Ninja - Fast build tool (recomendado)
  • ccache - Compiler cache (acelera rebuilds)
  • sccache - Distributed compiler cache

🎓 FILOSOFÍA DE AUDIOLAB BUILD

Principios

  1. Reproducibilidad - Mismo código → mismo resultado
  2. Cross-platform - Write once, build anywhere
  3. Performance - Fast builds, fast binaries
  4. Debuggability - Errores claros, fácil de troubleshoot
  5. Maintainability - Build system simple y comprensible

Build Philosophy

╔═══════════════════════════════════════════════════════════╗
║                                                           ║
║  "El build system es infraestructura invisible que        ║
║   permite a developers enfocarse en crear, no compilar."  ║
║                                                           ║
║  Un buen build system:                                    ║
║  • Funciona en primer intento                             ║
║  • Falla rápido con mensajes claros                       ║
║  • Se optimiza solo                                       ║
║  • No requiere configuración manual                       ║
║                                                           ║
║  - AudioLab Build Team                                    ║
║                                                           ║
╚═══════════════════════════════════════════════════════════╝

🤝 CONTRIBUCIONES

Mejorar Build System

Si encuentras: - ❌ Build que falla en tu plataforma - 💡 Optimización que falta - 📝 Documentación unclear - 🐛 Bug en scripts

Por favor: 1. Crea issue con detalles 2. O haz PR con fix 3. Documenta en troubleshooting si es nuevo error

Maintainer

Build Infrastructure Team Slack: #build-help Email: build-team@audiolab.com

📝 MÉTRICAS DE ÉXITO

Sabrás que dominas el build system cuando:

  • Puedes compilar AudioLab en cualquier plataforma
  • Entiendes cada paso del pipeline de build
  • Puedes diagnosticar errores de compilation/linking
  • Configuras optimizaciones (LTO, SIMD, PCH)
  • Cross-compilas para otras plataformas
  • Troubleshooteas build issues de otros developers
  • Diseñas CMake configs para nuevos proyectos

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

¡Bienvenido al sistema de build de AudioLab! 🚀

"De código fuente a plugins de audio en minutos, no horas."