# CMake Module Hierarchy

**Purpose:** Document the modular CMake architecture for developers and AI agents.

---

## Overview

The build system is split into 10 specialized modules under `cmake/`:

- **DemoOptions.cmake** - Build option declarations (10 flags)
- **DemoConfig.cmake** - Option implications + platform detection
- **DemoDependencies.cmake** - External library discovery (WGPU, GLFW)
- **DemoCommon.cmake** - Shared macros and utilities
- **DemoSourceLists.cmake** - Conditional source file lists
- **DemoLibraries.cmake** - Subsystem library targets (util, audio, gpu, 3d, procedural)
- **DemoTools.cmake** - Build tools (asset_packer, seq_compiler, tracker_compiler)
- **DemoCodegen.cmake** - Code generation (assets, timeline, music)
- **DemoExecutables.cmake** - Main binaries (demo64k, test_demo)
- **DemoTests.cmake** - Test infrastructure (36 tests)
- **Validation.cmake** - Uniform buffer validation

---

## Module Flow

```
CMakeLists.txt (orchestrator, ~54 lines)
  ├─> DemoOptions.cmake         (option() declarations)
  ├─> DemoConfig.cmake          (implications, platform detection)
  ├─> ParseWorkspace.cmake      (workspace config parsing)
  ├─> DemoCommon.cmake          (shared macros)
  ├─> DemoDependencies.cmake    (find WGPU/GLFW)
  ├─> DemoSourceLists.cmake     (source file variables)
  ├─> DemoLibraries.cmake       (add_library for subsystems)
  ├─> DemoTools.cmake           (if DEMO_BUILD_TOOLS)
  ├─> DemoCodegen.cmake         (asset/timeline/music generation)
  ├─> DemoExecutables.cmake     (demo64k, test_demo)
  ├─> DemoTests.cmake           (if DEMO_BUILD_TESTS)
  └─> Validation.cmake          (uniform validation)
```

---

## Shared Macros (DemoCommon.cmake)

### `demo_set_conditional_sources(VAR HEADLESS_LIST STRIP_LIST NORMAL_LIST)`
Simplifies 3-branch conditional source lists based on build mode.

**Example:**
```cmake
demo_set_conditional_sources(GPU_SOURCES
    "${headless_list}"
    "${strip_list}"
    "${normal_list}"
)
```

### `demo_apply_size_optimizations(TARGET)`
Applies platform-specific size optimization flags (MSVC/APPLE/Linux).

**Example:**
```cmake
demo_apply_size_optimizations(demo64k)
```

### `demo_link_libraries_ordered(TARGET)`
Links subsystem libraries in correct order with platform quirks.

**Example:**
```cmake
demo_link_libraries_ordered(demo64k)
```

### `demo_add_test_with_deps(NAME TEST_NAME LABEL SOURCES... LINK libs... DEPENDS targets...)`
Streamlined test registration with automatic dependency handling.

**Example:**
```cmake
demo_add_test_with_deps(test_window HammingWindowTest audio
    src/tests/audio/test_window.cc
    LINK audio util procedural ${DEMO_LIBS}
    DEPENDS generate_demo_assets
)
```

### `add_demo_executable(NAME SOURCES...)`
Creates an executable for the demo (legacy macro).

### `add_demo_test(NAME TEST_NAME LABEL SOURCES...)`
Creates a test executable and registers it with CTest (legacy macro).

---

## Conditional Inclusion

Modules are conditionally included based on build options:

- **Always:** Options, Config, Dependencies, SourceLists, Libraries, Codegen, Executables, Validation
- **Conditional:** Tools (if DEMO_BUILD_TOOLS OR DEMO_BUILD_TESTS OR NOT DEMO_STRIP_EXTERNAL_LIBS)
- **Conditional:** Tests (if DEMO_BUILD_TESTS)

This reduces parse time when building without tests/tools.

---

## Adding New Components

### New Effect
- Add sources to `cmake/DemoSourceLists.cmake` (GPU_SOURCES list)
- No other CMake changes needed

### New Test
- Add to `cmake/DemoTests.cmake` using `demo_add_test_with_deps()`
- Use LINK and DEPENDS parameters for libraries/assets

### New Library
- Add to `cmake/DemoLibraries.cmake` with appropriate dependencies
- Update `demo_link_libraries_ordered()` macro in `cmake/DemoCommon.cmake` if needed

### New Tool
- Add to `cmake/DemoTools.cmake` following asset_packer pattern
- Set tool command variable for use in code generation

---

## Benefits

1. **Maintainability:** Each subsystem in its own file—easier to understand and modify
2. **Performance:** Conditional inclusion—tests not parsed unless DEMO_BUILD_TESTS=ON
3. **Modularity:** Clear boundaries—tools, tests, libs, executables separated
4. **Reusability:** Shared macros—eliminate 200+ lines of repetition
5. **Clarity:** Top-level CMakeLists.txt is 54-line roadmap
6. **Scalability:** Easy to add new tests/tools/libraries without bloating main file

---

## Size Reduction

**Before:** 866 lines (monolithic)
**After:** 54 lines (orchestrator) + 10 modules
**Reduction:** 94% (exceeds 91% target)

---

## Module Sizes

```
CMakeLists.txt              54 lines  (orchestrator)
cmake/DemoCommon.cmake     204 lines  (shared macros)
cmake/DemoOptions.cmake     20 lines  (option declarations)
cmake/DemoConfig.cmake      80 lines  (config implications)
cmake/DemoDependencies.cmake 33 lines (external libs)
cmake/DemoSourceLists.cmake 63 lines  (source lists)
cmake/DemoLibraries.cmake   30 lines  (subsystem libs)
cmake/DemoTools.cmake       50 lines  (build tools)
cmake/DemoCodegen.cmake    128 lines  (code generation)
cmake/DemoExecutables.cmake 105 lines (main binaries)
cmake/DemoTests.cmake      270 lines  (test infrastructure)
cmake/Validation.cmake      39 lines  (uniform validation)
```

Total: ~1,076 lines across 12 files (vs 866 in single file)

---

## See Also

- `doc/BUILD.md` - Build system documentation
- `doc/HOWTO.md` - Common operations
- `doc/CONTRIBUTING.md` - Development guidelines