# Build Instructions

## Quick Start

```bash
# Development build
cmake -S . -B build
cmake --build build -j4

# Size-optimized build
cmake -S . -B build -DDEMO_SIZE_OPT=ON
cmake --build build -j4

# Final stripped build
cmake -S . -B build_final -DDEMO_FINAL_STRIP=ON
cmake --build build_final -j4
```

## Build Modes

| Mode | Flags | Use Case |
|------|-------|----------|
| Debug | `-DCMAKE_BUILD_TYPE=Debug` | Development, full error checking + debug features |
| SIZE_OPT | `-DDEMO_SIZE_OPT=ON` | Size-optimized, with checks |
| STRIP_ALL | `-DDEMO_STRIP_ALL=ON` | Release candidate, full error checking, no debug features (~64k target) |
| FINAL_STRIP | `-DDEMO_FINAL_STRIP=ON` | Final release, no error checking, absolute minimum size |
| HEADLESS | `-DDEMO_HEADLESS=ON` | Testing without GPU (audio/timeline work, no rendering) |
| STRIP_EXTERNAL_LIBS | `-DDEMO_STRIP_EXTERNAL_LIBS=ON` | Size measurement only (binary won't run) |

**Build Hierarchy:**
- **Debug:** Full checks + debug features (hot-reload, seek, etc.)
- **STRIP_ALL:** Full checks, no debug (~64k target, always fullscreen)
- **FINAL_STRIP:** No checks, no debug (absolute minimum, ⚠️ dangerous)

**Note:** `DEMO_ALL_OPTIONS=ON` enables tests, tools, AND `STRIP_ALL`.

## Dependencies

Install via Homebrew (macOS):
```bash
brew install wgpu-native
```

Or use project init script:
```bash
./scripts/project_init.sh
```

Required libraries:
- **miniaudio** (single header, auto-fetched by init script)
- **wgpu-native** (WebGPU implementation)
- **glfw3webgpu** (GLFW surface helper, auto-fetched)
- **UPX** (executable packer, optional for Linux/Windows)

## Windows Cross-Compilation (macOS)

Requires `mingw-w64` and `wine-stable`.

```bash
# Fetch Windows dependencies
./scripts/fetch_win_deps.sh

# Build for Windows
./scripts/build_win.sh

# Test with Wine
./scripts/run_win.sh
```

Produces `build_win/demo64k_packed.exe`.

## Xcode Build (macOS)

```bash
cmake -S . -B build -G "Xcode"
open build/demo.xcodeproj
```

Use Xcode Metal debugger for shader performance analysis.

## Build System Internals

**Asset Dependency Tracking:**
- CMake tracks 42 demo + 17 test assets
- Editing shaders/audio/sequences auto-triggers rebuild
- Asset lists parsed to extract individual file dependencies

**Header Organization:**
- `asset_manager_dcl.h`: Forward declarations
- `asset_manager.h`: Core API (GetAsset/DropAsset)
- `asset_manager_utils.h`: Typed helpers

**Code Generation:**
- Timeline: `seq_compiler` → `generated/timeline.cc`
- Music: `tracker_compiler` → `generated/music.cc`
- Assets: `asset_packer` → `generated/assets.h` + `assets_data.cc`
- Cross-compilation uses host-native tools for generation