From 002ab9094f638c46d5db95d478e71c10933aceb2 Mon Sep 17 00:00:00 2001 From: skal Date: Mon, 9 Feb 2026 18:37:38 +0100 Subject: docs: Condense HOWTO.md, move details to technical docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - HOWTO.md: 184→97 lines (quick reference only) - BUILD.md: Add build modes, header organization, dependency tracking - ASSET_SYSTEM.md: Add developer workflow section - TRACKER.md: Add AudioEngine API documentation Net: -147 lines in HOWTO.md --- doc/BUILD.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) (limited to 'doc/BUILD.md') diff --git a/doc/BUILD.md b/doc/BUILD.md index 1f65122..7cb3473 100644 --- a/doc/BUILD.md +++ b/doc/BUILD.md @@ -21,8 +21,17 @@ cmake --build build_final -j4 | 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 | +| 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 @@ -67,3 +76,21 @@ 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 -- cgit v1.2.3