Guía de Estructura de Directorios - AudioLab Modules¶

📂 ¿QUÉ VA EN CADA CARPETA?¶

Esta guía explica el propósito de cada directorio en la estructura estándar de un módulo AudioLab.

🎯 ESTRUCTURA COMPLETA¶

05_19_XX_subsystem_name/
├── include/          ← Headers públicos (.h)
├── src/             ← Implementaciones (.cpp)
├── tests/           ← Unit tests
├── examples/        ← Programas de ejemplo
├── docs/            ← Documentación específica
├── tools/           ← Herramientas CLI/utilities
└── CMakeLists.txt   ← Build configuration

📁 1. `include/` - Headers Públicos¶

Propósito¶

Contiene los archivos de cabecera (.h) que definen la API pública del módulo.

¿Qué va aquí?¶

✅ Declaraciones de clases públicas
✅ Estructuras de datos públicas
✅ Enums y constants públicas
✅ Documentación Doxygen
✅ Inline functions (si es necesario)

¿Qué NO va aquí?¶

❌ Implementaciones (.cpp)
❌ Detalles de implementación privados
❌ Headers internos (van en src/internal/)

Ejemplo: `CrashHandler.h`¶

// include/CrashHandler.h
#ifndef AUDIOLAB_CRASH_HANDLER_H
#define AUDIOLAB_CRASH_HANDLER_H

namespace AudioLab {
namespace Diagnostics {

// API PÚBLICA - visible para usuarios del módulo
class CrashHandler {
public:
    bool initialize(const MinidumpConfig& config);
    static std::vector<StackFrame> captureStackTrace();
    // ...
};

} // namespace Diagnostics
} // namespace AudioLab

#endif

Estructura Típica¶

include/
├── CrashHandler.h           ← Clase principal
├── MinidumpConfig.h         ← Configuración
├── StackFrame.h             ← Estructuras de datos
└── crash_analysis_types.h   ← Types/enums comunes

📁 2. `src/` - Implementaciones¶

Propósito¶

Contiene las implementaciones (.cpp) de las clases y funciones declaradas en include/.

¿Qué va aquí?¶

✅ Archivos .cpp con implementaciones
✅ Headers internos privados (src/internal/)
✅ Helpers y utilities privadas
✅ Platform-specific implementations

¿Qué NO va aquí?¶

❌ Headers públicos (van en include/)
❌ Tests (van en tests/)
❌ Ejemplos (van en examples/)

Ejemplo: `CrashHandler.cpp`¶

// src/CrashHandler.cpp
#include "CrashHandler.h"
#include "internal/platform_specific.h"  // Header interno

namespace AudioLab {
namespace Diagnostics {

// IMPLEMENTACIÓN - detalles ocultos al usuario
bool CrashHandler::initialize(const MinidumpConfig& config) {
    // Lógica de implementación...
    return installHandlers();
}

// Funciones privadas, helpers, etc.
namespace {
    void helperFunction() { /* ... */ }
}

} // namespace Diagnostics
} // namespace AudioLab

Estructura Típica¶

src/
├── CrashHandler.cpp              ← Implementación principal
├── MinidumpWriter.cpp            ← Componentes específicos
├── SymbolResolver.cpp
├── internal/                     ← Headers privados
│   ├── platform_utils.h
│   └── symbol_cache.h
└── platform/                     ← Por plataforma
    ├── crash_handler_win.cpp
    ├── crash_handler_macos.cpp
    └── crash_handler_linux.cpp

📁 3. `tests/` - Unit Tests¶

Propósito¶

Contiene pruebas unitarias para verificar que el código funciona correctamente.

¿Qué va aquí?¶

✅ Archivos de test usando framework (Catch2, Google Test, etc.)
✅ Un test file por clase/componente
✅ Fixtures y utilities de testing
✅ Mocks y stubs si necesario

¿Qué NO va aquí?¶

❌ Integration tests (van en nivel superior)
❌ Performance benchmarks (pueden ir aquí o en benchmarks/)
❌ Código de producción

Ejemplo: `test_crash_handler.cpp`¶

// tests/test_crash_handler.cpp
#include "CrashHandler.h"
#include <catch2/catch_test_macros.hpp>

TEST_CASE("CrashHandler - Initialization", "[crash_handler]") {
    CrashHandler handler;
    MinidumpConfig config;
    config.outputDirectory = "./test_dumps";

    SECTION("Initialize with valid config") {
        REQUIRE(handler.initialize(config));
    }

    SECTION("Stack trace capture") {
        auto trace = CrashHandler::captureStackTrace();
        REQUIRE(!trace.empty());
    }
}

TEST_CASE("CrashHandler - Manual Minidump", "[crash_handler]") {
    // Más tests...
}

Estructura Típica¶

tests/
├── test_crash_handler.cpp       ← Tests de CrashHandler
├── test_minidump_writer.cpp     ← Tests de componentes
├── test_symbol_resolver.cpp
├── fixtures/                    ← Utilities de testing
│   └── test_fixtures.h
└── data/                        ← Test data files
    ├── sample_crash.dmp
    └── expected_output.json

Comandos Típicos¶

# Run all tests
cd build
ctest

# Run specific test
./test_crash_handler

# Run with Catch2 filters
./test_crash_handler "[crash_handler]"

📁 4. `examples/` - Programas de Ejemplo¶

Propósito¶

Contiene programas standalone que demuestran cómo usar el módulo.

¿Qué va aquí?¶

✅ Programas .cpp completos con main()
✅ Casos de uso reales
✅ Tutoriales interactivos
✅ Demos de features

¿Qué NO va aquí?¶

❌ Tests (van en tests/)
❌ Tools de producción (van en tools/)
❌ Documentación (va en docs/)

Ejemplo: `crash_demo.cpp`¶

// examples/crash_demo.cpp
#include "CrashHandler.h"
#include <iostream>

int main() {
    std::cout << "=== CrashHandler Demo ===\n";

    // Setup
    CrashHandler handler;
    MinidumpConfig config;
    config.outputDirectory = "./demo_dumps";
    handler.initialize(config);

    // Demo 1: Stack trace
    std::cout << "\n1. Capturing stack trace...\n";
    auto trace = CrashHandler::captureStackTrace();
    for (size_t i = 0; i < trace.size(); ++i) {
        std::cout << "#" << i << " " << trace[i].toString() << "\n";
    }

    // Demo 2: Manual minidump
    std::cout << "\n2. Generating manual minidump...\n";
    handler.generateMinidump("Demo dump");

    std::cout << "\n✓ Demo complete!\n";
    return 0;
}

Estructura Típica¶

examples/
├── crash_demo.cpp               ← Demo simple
├── interactive_crash_demo.cpp   ← Demo interactivo
├── real_world_usage.cpp         ← Caso de uso real
└── CMakeLists.txt               ← Build de examples

Compilación¶

# Con CMake
cd build
cmake .. -DBUILD_EXAMPLES=ON
make crash_demo

# Manual
g++ -std=c++17 crash_demo.cpp -I../include -L../build -lcrash_analysis -o crash_demo
./crash_demo

📁 5. `docs/` - Documentación¶

Propósito¶

Contiene documentación específica del módulo (además de los comentarios en código).

¿Qué va aquí?¶

✅ Guías de uso (Markdown)
✅ Tutoriales
✅ Architecture docs
✅ API reference (si no auto-generada)
✅ Diagramas
✅ Platform-specific notes

¿Qué NO va aquí?¶

❌ Código fuente
❌ Generated docs (van en build/docs/)

Ejemplo: `CRASH_ANALYSIS_GUIDE.md`¶

# CrashHandler - Guía Completa

## Quick Start

[código de ejemplo]

## API Reference

### CrashHandler::initialize()

Inicializa el crash handler...

## Platform-Specific Details

### Windows
...

### macOS
...

Estructura Típica¶

docs/
├── README.md                    ← Overview del módulo
├── CRASH_ANALYSIS_GUIDE.md      ← Guía completa
├── API_REFERENCE.md             ← API detallada
├── ARCHITECTURE.md              ← Diseño interno
├── PLATFORM_NOTES.md            ← Notas por plataforma
├── images/                      ← Diagramas
│   ├── architecture.png
│   └── workflow.png
└── examples/                    ← Code snippets
    └── snippets.md

📁 6. `tools/` - Herramientas CLI¶

Propósito¶

Contiene utilidades de línea de comandos relacionadas con el módulo.

¿Qué va aquí?¶

✅ CLIs standalone
✅ Scripts de análisis
✅ Converters
✅ Inspectors
✅ Utilities para debugging

¿Qué NO va aquí?¶

❌ Código de biblioteca (va en src/)
❌ Tests (van en tests/)
❌ Demos (van en examples/)

Ejemplo: `minidump_analyzer.cpp`¶

// tools/minidump_analyzer.cpp
#include "CrashHandler.h"
#include <iostream>

void printUsage() {
    std::cout << "Usage: minidump_analyzer <file> [options]\n";
    std::cout << "Options:\n";
    std::cout << "  --stack    Show stack trace\n";
    std::cout << "  --export   Export to JSON\n";
}

int main(int argc, char* argv[]) {
    if (argc < 2) {
        printUsage();
        return 1;
    }

    std::string dumpFile = argv[1];

    // Analyze dump...
    analyzeDump(dumpFile);

    return 0;
}

Estructura Típica¶

tools/
├── minidump_analyzer.cpp        ← Analizador de dumps
├── symbol_resolver.cpp          ← Resolvedor de símbolos
├── crash_reporter.cpp           ← Reportador de crashes
└── CMakeLists.txt               ← Build de tools

Uso¶

# Compilar
cd build
make minidump_analyzer

# Usar
./minidump_analyzer crash.dmp --stack
./minidump_analyzer crash.dmp --export report.json

🔧 CMakeLists.txt¶

Propósito¶

Define cómo compilar y linkar el módulo.

Estructura Típica¶

# CMakeLists.txt
cmake_minimum_required(VERSION 3.15)
project(CrashAnalysis VERSION 1.0.0)

# ============================================================================
# Library
# ============================================================================

add_library(crash_analysis
    src/CrashHandler.cpp
    src/MinidumpWriter.cpp
    src/SymbolResolver.cpp
)

target_include_directories(crash_analysis
    PUBLIC
        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
        $<INSTALL_INTERFACE:include>
    PRIVATE
        ${CMAKE_CURRENT_SOURCE_DIR}/src
)

# ============================================================================
# Tests (opcional)
# ============================================================================

option(BUILD_TESTS "Build tests" OFF)

if(BUILD_TESTS)
    add_executable(test_crash_handler tests/test_crash_handler.cpp)
    target_link_libraries(test_crash_handler PRIVATE crash_analysis Catch2::Catch2)
endif()

# ============================================================================
# Examples (opcional)
# ============================================================================

option(BUILD_EXAMPLES "Build examples" OFF)

if(BUILD_EXAMPLES)
    add_executable(crash_demo examples/crash_demo.cpp)
    target_link_libraries(crash_demo PRIVATE crash_analysis)
endif()

# ============================================================================
# Tools (opcional)
# ============================================================================

option(BUILD_TOOLS "Build tools" OFF)

if(BUILD_TOOLS)
    add_executable(minidump_analyzer tools/minidump_analyzer.cpp)
    target_link_libraries(minidump_analyzer PRIVATE crash_analysis)
endif()

# ============================================================================
# Install
# ============================================================================

install(TARGETS crash_analysis
    EXPORT CrashAnalysisTargets
    LIBRARY DESTINATION lib
    ARCHIVE DESTINATION lib
    RUNTIME DESTINATION bin
)

install(DIRECTORY include/ DESTINATION include)

📊 COMPARACIÓN: ¿Dónde va cada cosa?¶

Archivo	include/	src/	tests/	examples/	tools/	docs/
`CrashHandler.h`	✅	❌	❌	❌	❌	❌
`CrashHandler.cpp`	❌	✅	❌	❌	❌	❌
`internal_utils.h`	❌	✅ (en src/internal/)	❌	❌	❌	❌
`test_crash_handler.cpp`	❌	❌	✅	❌	❌	❌
`crash_demo.cpp`	❌	❌	❌	✅	❌	❌
`minidump_analyzer.cpp`	❌	❌	❌	❌	✅	❌
`API_GUIDE.md`	❌	❌	❌	❌	❌	✅

🎯 EJEMPLO COMPLETO: 05_19_01_crash_analysis¶

05_19_01_crash_analysis/
│
├── include/                         ← API PÚBLICA
│   ├── CrashHandler.h              [✅ CREADO]
│   ├── MinidumpConfig.h            (dentro de CrashHandler.h)
│   └── StackFrame.h                (dentro de CrashHandler.h)
│
├── src/                            ← IMPLEMENTACIÓN
│   ├── CrashHandler.cpp            [✅ CREADO]
│   ├── platform/
│   │   ├── crash_handler_win.cpp   (platform-specific)
│   │   ├── crash_handler_macos.cpp
│   │   └── crash_handler_linux.cpp
│   └── internal/
│       └── symbol_cache.h          (helpers privados)
│
├── tests/                          ← TESTS
│   ├── test_crash_handler.cpp      [✅ CREADO]
│   ├── test_minidump_writer.cpp
│   └── fixtures/
│       └── test_fixtures.h
│
├── examples/                       ← DEMOS
│   ├── crash_demo.cpp              [✅ CREADO]
│   └── interactive_demo.cpp
│
├── tools/                          ← CLI TOOLS
│   ├── minidump_analyzer.cpp       [✅ CREADO]
│   └── symbol_resolver_cli.cpp
│
├── docs/                           ← DOCUMENTACIÓN
│   ├── CRASH_ANALYSIS_GUIDE.md     [✅ CREADO]
│   ├── API_REFERENCE.md
│   └── PLATFORM_NOTES.md
│
└── CMakeLists.txt                  [✅ EXISTE]

🚀 WORKFLOW DE DESARROLLO¶

1. Diseño (Design Phase)¶

1. Crear header en include/
   └─> Define API pública

2. Implementación (Implementation Phase)¶

2. Crear .cpp en src/
   └─> Implementa la funcionalidad

3. Testing (Testing Phase)¶

3. Crear tests en tests/
   └─> Verifica que funciona

4. Documentación (Documentation Phase)¶

4. Crear guías en docs/
   └─> Explica cómo usar

5. Ejemplos (Examples Phase)¶

5. Crear demos en examples/
   └─> Muestra casos de uso

6. Herramientas (Tools Phase) [Opcional]¶

6. Crear CLIs en tools/
   └─> Utilities adicionales

✅ ESTADO ACTUAL: 05_19_DIAGNOSTIC_SUITE¶

Lo que YA existe (solo `include/`):¶

✅ 05_19_00_diagnostic_framework/include/DiagnosticFramework.h
✅ 05_19_00_diagnostic_framework/src/DiagnosticFramework.cpp
✅ 05_19_01_crash_analysis/include/CrashHandler.h
✅ 05_19_01_crash_analysis/src/CrashHandler.cpp
✅ 05_19_01_crash_analysis/tests/test_crash_handler.cpp
✅ 05_19_01_crash_analysis/examples/crash_demo.cpp
✅ 05_19_01_crash_analysis/tools/minidump_analyzer.cpp
✅ 05_19_01_crash_analysis/docs/CRASH_ANALYSIS_GUIDE.md
✅ 05_19_02_memory_debugging/include/MemoryDebugger.h
✅ ... (05_19_03 hasta 05_19_09 con headers)

Lo que FALTA por crear:¶

Para cada subsistema 02-09: - src/*.cpp - Implementaciones - tests/test_*.cpp - Unit tests - examples/*_demo.cpp - Programas de ejemplo - tools/*_tool.cpp - Herramientas CLI (si aplica) - docs/*.md - Documentación específica

💡 PRÓXIMOS PASOS SUGERIDOS¶

Opción A: Completar un subsistema a la vez¶

1. Elegir subsistema (ej: 05_19_02_memory_debugging)
2. Crear src/MemoryDebugger.cpp
3. Crear tests/test_memory_debugger.cpp
4. Crear examples/memory_demo.cpp
5. Crear docs/MEMORY_DEBUGGING_GUIDE.md
6. Repetir para siguiente subsistema

Opción B: Completar por tipo de archivo¶

1. Crear todos los src/*.cpp (implementaciones)
2. Crear todos los tests/test_*.cpp
3. Crear todos los examples/*_demo.cpp
4. Crear todas las docs/*.md

Opción C: Mínimo viable¶

1. Crear src/*.cpp para subsistemas críticos
2. Crear tests básicos
3. Dejar examples/tools/docs para después

📖 RESUMEN¶

Directorio	Contenido	Visibilidad	Build
`include/`	Headers API	Pública	Siempre
`src/`	Implementations	Privada	Siempre
`tests/`	Unit tests	Testing	Opcional (-DBUILD_TESTS=ON)
`examples/`	Demos	Learning	Opcional (-DBUILD_EXAMPLES=ON)
`tools/`	CLI utilities	Tools	Opcional (-DBUILD_TOOLS=ON)
`docs/`	Documentation	Docs	No compilable

¿Quieres que continúe creando los archivos faltantes para los otros subsistemas (02-09)?

Opciones: 1. ✅ Completar src/ para todos (implementaciones) 2. ✅ Completar tests/ para todos (unit tests) 3. ✅ Completar examples/ para todos (demos) 4. ✅ Completar tools/ para algunos (utilities) 5. ✅ Completar docs/ para todos (guías) 6. ✅ Todo lo anterior (implementación completa)

Tiempo estimado: 30-60 min para completar todo.

Guía de Estructura de Directorios - AudioLab Modules¶

📂 ¿QUÉ VA EN CADA CARPETA?¶

🎯 ESTRUCTURA COMPLETA¶

📁 1. include/ - Headers Públicos¶

Propósito¶

¿Qué va aquí?¶

¿Qué NO va aquí?¶

Ejemplo: CrashHandler.h¶

Estructura Típica¶

📁 2. src/ - Implementaciones¶

Propósito¶

¿Qué va aquí?¶

¿Qué NO va aquí?¶

Ejemplo: CrashHandler.cpp¶

Estructura Típica¶

📁 3. tests/ - Unit Tests¶

Propósito¶

¿Qué va aquí?¶

¿Qué NO va aquí?¶

Ejemplo: test_crash_handler.cpp¶

Estructura Típica¶

Comandos Típicos¶

📁 4. examples/ - Programas de Ejemplo¶

Propósito¶

¿Qué va aquí?¶

¿Qué NO va aquí?¶

Ejemplo: crash_demo.cpp¶

Estructura Típica¶

Compilación¶

📁 5. docs/ - Documentación¶

Propósito¶

¿Qué va aquí?¶

¿Qué NO va aquí?¶

Ejemplo: CRASH_ANALYSIS_GUIDE.md¶

Estructura Típica¶

📁 6. tools/ - Herramientas CLI¶

Propósito¶

¿Qué va aquí?¶

¿Qué NO va aquí?¶

Ejemplo: minidump_analyzer.cpp¶

Estructura Típica¶

Uso¶

🔧 CMakeLists.txt¶

Propósito¶

Estructura Típica¶

📊 COMPARACIÓN: ¿Dónde va cada cosa?¶

🎯 EJEMPLO COMPLETO: 05_19_01_crash_analysis¶

🚀 WORKFLOW DE DESARROLLO¶

1. Diseño (Design Phase)¶

2. Implementación (Implementation Phase)¶

3. Testing (Testing Phase)¶

4. Documentación (Documentation Phase)¶

5. Ejemplos (Examples Phase)¶

6. Herramientas (Tools Phase) [Opcional]¶

✅ ESTADO ACTUAL: 05_19_DIAGNOSTIC_SUITE¶

Lo que YA existe (solo include/):¶

Lo que FALTA por crear:¶

💡 PRÓXIMOS PASOS SUGERIDOS¶

Opción A: Completar un subsistema a la vez¶

Opción B: Completar por tipo de archivo¶

Opción C: Mínimo viable¶

📖 RESUMEN¶

📁 1. `include/` - Headers Públicos¶

Ejemplo: `CrashHandler.h`¶

📁 2. `src/` - Implementaciones¶

Ejemplo: `CrashHandler.cpp`¶

📁 3. `tests/` - Unit Tests¶

Ejemplo: `test_crash_handler.cpp`¶

📁 4. `examples/` - Programas de Ejemplo¶

Ejemplo: `crash_demo.cpp`¶

📁 5. `docs/` - Documentación¶

Ejemplo: `CRASH_ANALYSIS_GUIDE.md`¶

📁 6. `tools/` - Herramientas CLI¶

Ejemplo: `minidump_analyzer.cpp`¶

Lo que YA existe (solo `include/`):¶