1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
# 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
|
